# monmer-solon

**Repository Path**: opensolon/monmer-solon

## Basic Information

- **Project Name**: monmer-solon
- **Description**: 一个方便快捷的单体架构框架满足基本的开发需求 
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: solon_3.x
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 1
- **Created**: 2024-06-24
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# monmer-solon 项目文档

## 项目概述

`monmer-solon` 是一个基于 Solon 框架构建的现代化 Java 微服务项目，采用模块化设计，集成了常用开发组件与业务能力。项目使用 Maven 多模块结构管理，支持快速构建、部署和扩展。

主要特性包括：
- 使用 Solon 3.8.1-M2 提供轻量级 Web 与微服务能力
- 集成 MyBatis-Plus 实现高效数据库操作
- 支持 Redisson 分布式缓存
- 集成七牛云 OSS 文件存储
- 支持微信小程序与支付 SDK
- 内置日志、定时任务、权限认证（Sa-Token）、API 文档（Knife4j）等插件

## 系统架构

### 项目模块结构

```
monmer-solon/
├── api                 # API 接口层，包含 Controller 和 Service 实现
├── common              # 公共工具类、配置、实体类、常量定义
├── data                # 数据访问层（DAO）、数据库配置、MyBatis-Plus 配置
├── gen                 # 代码生成器模块（用于自动生成实体、Mapper、Service）
└── pom.xml             # 父 POM，统一管理依赖版本
```

### 模块详细说明

| 模块 | 功能描述 |
|------|----------|
| `api` | 核心业务逻辑实现，包含 Controller、Service、ServiceImpl 及相关接口，同时包含智能套接字（Smart Socket）配置和定时任务 |
| `common` | 包含全局配置类、公共工具类、枚举、VO/DTO 类，以及第三方 SDK 配置（如七牛、微信），还包括异常处理、日志配置、MapStruct 映射等 |
| `data` | 数据源配置、HikariCP 连接池、MyBatis-Plus 插件、Mapper 接口及 XML 映射文件，以及具体的业务数据模型和服务 |
| `gen` | 基于 MyBatis-Plus Generator 的代码生成工具，可自动生成基础 CRUD 代码 |

### 技术栈

| 组件 | 版本 | 用途 |
|------|------|------|
| `solon` | 3.8.1-M2 | 主框架，提供轻量级开发体验 |
| `mybatis-plus` | 3.5.7 | ORM 框架，简化数据库操作 |
| `hutool` | 5.8.26 | 工具类库，提升开发效率 |
| `redisson` | 2.8.4 | 分布式缓存与锁支持 |
| `qiniu-java-sdk` | [7.13.0, 7.13.99] | 七牛云对象存储集成 |
| `weixin-java-miniapp` / `weixin-java-pay` | 4.6.0 | 微信小程序与支付功能支持 |
| `sa-token` | - | 轻量级鉴权框架 |
| `knife4j` | - | API 文档生成（基于 OpenAPI） |

## 项目详细结构

### API 模块
```
api/
├── src/main
│   ├── java/com/monmer
│   │   ├── auth
│   │   │   └── AuthConfig.java           # 认证配置
│   │   ├── controller
│   │   │   ├── common
│   │   │   │   ├── PayCallBack.java      # 支付回调控制器
│   │   │   │   ├── UploadController.java # 上传控制器
│   │   │   │   └── WxController.java     # 微信控制器
│   │   │   ├── doc
│   │   │   │   └── OpenApi2Controller.java # API 文档控制器
│   │   │   └── user
│   │   │       └── TbUserController.java # 用户控制器
│   │   ├── smartsocket
│   │   │   ├── ServerProcessor.java      # 智能套接字服务器处理器
│   │   │   ├── SmartSocketConfig.java    # 智能套接字配置
│   │   │   ├── StringClient.java         # 字符串客户端
│   │   │   └── StringProtocol.java       # 字符串协议
│   │   ├── task
│   │   │   └── Task.java                 # 定时任务
│   │   ├── util
│   │   │   ├── ListenerImpl.java         # 监听器实现
│   │   │   └── ServerLifecycle.java      # 服务器生命周期
│   │   └── App.java                      # 应用入口
│   └── resources
│       ├── static
│       │   └── base.css                  # 静态资源样式表
│       ├── templates
│       │   └── hello2.ftl                # FreeMarker 模板
│       ├── app-dev.yml                   # 开发环境配置
│       ├── app-prod.yml                  # 生产环境配置
│       ├── app.yml                       # 主配置文件
│       └── spy.properties                # P6Spy 配置
├── Dockerfile                            # Docker 部署文件
└── pom.xml                               # API 模块 POM
```

### Common 模块
```
common/
├── src/main/java/com/monmer
│   ├── config
│   │   ├── doc
│   │   │   └── DocConfig.java            # 文档配置
│   │   ├── exception
│   │   │   └── CommonErrorException.java # 通用异常
│   │   ├── log
│   │   │   ├── Logging.java              # 日志注解
│   │   │   └── LoggingHandler.java       # 日志处理器
│   │   ├── mapstruct
│   │   │   ├── BaseMapper.java           # 基础映射器
│   │   │   ├── CommonMapperConfig.java   # 映射器配置
│   │   │   ├── EntityMapper.java         # 实体映射器
│   │   │   ├── IdNameDTO.java            # ID名称传输对象
│   │   │   └── Qualified.java            # 限定注解
│   │   ├── oss
│   │   │   ├── service
│   │   │   │   ├── impl
│   │   │   │   │   └── QiNiuService.java # 七牛服务实现
│   │   │   │   └── OssService.java       # OSS 服务接口
│   │   │   ├── OSSType.java              # OSS 类型枚举
│   │   │   ├── OssConfig.java            # OSS 配置
│   │   │   ├── OssConfigure.java         # OSS 配置类
│   │   │   ├── OssFactory.java           # OSS 工厂
│   │   │   └── OssProperties.java        # OSS 属性配置
│   │   ├── redission
│   │   │   └── Config.java               # Redisson 配置
│   │   ├── response
│   │   │   ├── Result.java               # 统一返回结果
│   │   │   └── ResultUtil.java           # 返回结果工具类
│   │   ├── wx
│   │   │   ├── mini
│   │   │   │   ├── WxMaConfiguration.java # 微信小程序配置
│   │   │   │   └── WxMaProperties.java   # 微信小程序属性
│   │   │   └── pay
│   │   │       ├── WxPayConfigurations.java # 微信支付配置
│   │   │       └── WxPayProperties.java  # 微信支付属性
│   │   ├── Config.java                   # 通用配置
│   │   ├── ErrorDetail.java              # 错误详情
│   │   └── MetaObjectHandlerImpl.java    # MyBatis元对象处理器
│   └── utils
│       ├── Base64ToImage.java            # Base64转图片工具
│       ├── Lambdas.java                  # Lambda表达式工具
│       └── NumberUtils.java              # 数字工具类
└── pom.xml                               # Common 模块 POM
```

### Data 模块
```
data/
├── src/main
│   ├── java/com/monmer/data
│   │   ├── common
│   │   │   ├── dto
│   │   │   │   ├── PayDTO.java           # 支付传输对象
│   │   │   │   ├── WriteOffMapStruct.java # 核销映射结构
│   │   │   │   └── WxUserInfoDTO.java    # 微信用户信息传输对象
│   │   │   ├── enums
│   │   │   │   └── PlatType.java         # 平台类型枚举
│   │   │   └── service
│   │   │       ├── impl
│   │   │       │   ├── PayServiceImpl.java # 支付服务实现
│   │   │       │   └── UploadServiceImpl.java # 上传服务实现
│   │   │       ├── PayService.java       # 支付服务接口
│   │   │       └── UploadService.java    # 上传服务接口
│   │   └── tbuser
│   │       ├── dto
│   │       │   └── TbUserDTO.java        # 用户传输对象
│   │       ├── entity
│   │       │   └── TbUser.java           # 用户实体
│   │       ├── map
│   │       │   └── TbUserMapper.java     # 用户映射器
│   │       ├── mapstruct
│   │       │   └── TbUserMapStruct.java  # 用户映射结构
│   │       └── service
│   │           ├── impl
│   │           │   └── TbUserServiceImpl.java # 用户服务实现
│   │           └── ITbUserService.java   # 用户服务接口
│   └── resources/mapper
│       ├── custom
│       │   └── custom.xml                # 自定义映射文件
│       └── tbuser
│           └── TbUserMapper.xml          # 用户映射XML
└── pom.xml                               # Data 模块 POM
```

### Gen 模块
```
gen/
├── src/main
│   ├── java/com/monmer
│   │   ├── EnhanceFreemarkerTemplateEngine.java # 增强的FreeMarker模板引擎
│   │   └── Main.java                     # 代码生成器主类
│   └── resources/templates
│       ├── Mapstruct.java.ftl            # MapStruct模板
│       ├── controller.java.ftl           # 控制器模板
│       ├── entityDTO.java.ftl            # DTO实体模板
│       ├── mapper.java.ftl               # 映射器模板
│       ├── mapper.xml.ftl                # 映射XML模板
│       ├── service.java.ftl              # 服务接口模板
│       └── serviceImpl.java.ftl          # 服务实现模板
└── pom.xml                               # Gen 模块 POM
```

## 环境准备

- JDK 11 或以上版本
- Maven 3.6+
- MySQL 8.0+（用于数据存储）
- Redis（可选，用于缓存）
- 七牛云账号（用于文件上传）

## 快速开始

### 1. 克隆项目

```bash
git clone <your-repo-url>
cd monmer-solon
```

### 2. 构建项目

```bash
mvn clean install
```

### 3. 配置数据库

在 `data/src/main/resources/application.yml` 中配置数据库连接：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/monmer?useSSL=false&serverTimezone=UTC
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver
```

### 4. 配置其他服务

在 `api/src/main/resources/app.yml` 中配置：

```yaml
# 七牛云配置
oss:
  qiniu:
    accessKey: your_access_key
    secretKey: your_secret_key
    bucket: your_bucket_name

# 微信小程序配置
wx:
  miniapp:
    appid: your_app_id
    secret: your_app_secret

# 微信支付配置
wx:
  pay:
    appId: your_app_id
    mchId: your_mch_id
    mchKey: your_mch_key
```

### 5. 启动项目

```bash
cd api
mvn solon:run
```

或者在 IDE 中运行 `App.java` 类。

### 6. 访问服务

- 应用地址：`http://localhost:8080`
- API 文档：`http://localhost:8080/doc.html`

## 主要功能

### 1. 用户管理
- 用户注册、登录、信息查询等基本操作
- 基于 Sa-Token 的权限认证

### 2. 文件上传
- 支持多种 OSS 服务（当前实现七牛云）
- 文件上传、下载、删除等功能

### 3. 支付功能
- 微信支付集成
- 支付回调处理

### 4. 微信功能
- 微信小程序登录
- 微信支付

### 5. 智能套接字
- 基于 socket.d 的实时通信功能

### 6. 定时任务
- 基于 Solon 调度的定时任务功能

### 7. 代码生成
- 基于 MyBatis-Plus Generator 的代码生成工具
- 可自动生成实体、Mapper、Service、Controller 等代码

## 开发指南

### 1. 添加新功能模块

1. 在 [data](file:///E:\monmer-solon\monmer-solon\data) 模块中创建实体、Mapper 和 Service
2. 在 [common](file:///E:\monmer-solon\monmer-solon\common) 模块中添加 DTO 和配置
3. 在 [api](file:///E:\monmer-solon\monmer-solon\api) 模块中添加 Controller

### 2. 使用代码生成器

运行 `gen` 模块中的 [Main.java](file:///E:\monmer-solon\monmer-solon\gen\src\main\java\com\monmer\Main.java) 类，按照提示输入表名和其他参数即可生成基础代码。

### 3. 配置新 OSS 服务

在 [OSSType.java](file:///E:\monmer-solon\monmer-solon\common\src\main\java\com\monmer\config\oss\OSSType.java) 中添加新的类型，并实现相应的 [OssService](file:///E:\monmer-solon\monmer-solon\common\src\main\java\com\monmer\config\oss\service\OssService.java) 接口。

## 常见问题

### 1. 参数化构造函数错误

如果遇到 `Parameterized constructor are not allowed` 错误，请检查配置类（如 [OssProperties](file:///E:\monmer-solon\monmer-solon\common\src\main\java\com\monmer\config\oss\OssProperties.java)）中的内部类，确保它们只包含无参构造函数。

### 2. 依赖版本冲突

项目使用父 POM 统一管理依赖版本，如需修改版本，请在根目录 [pom.xml](file:///E:\monmer-solon\monmer-solon\pom.xml) 的 `<properties>` 部分进行修改。

### 3. 配置热更新

项目支持配置热更新，修改配置文件后无需重启服务（部分配置除外）。

## 部署方式

### 1. 传统部署

```bash
cd api
mvn package
java -jar target/api-{version}.jar --env=prod
```

### 2. Docker 部署

```bash
docker build -t monmer-solon .
docker run -d -p 8080:8080 monmer-solon
```

## 项目规范

1. 代码风格遵循 Google Java Style Guide
2. 使用 Lombok 减少样板代码
3. 使用 MapStruct 进行对象映射转换
4. 所有 API 接口返回统一格式的数据结构
5. 使用日志记录关键操作和错误信息

## 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 许可证

该项目采用 MIT 许可证 - 详见 [LICENSE](file:///E:\monmer-solon\monmer-solon\LICENSE) 文件。

## 联系方式

如有问题或建议，请联系项目维护者。