En
48fc71b41d
- 修复 sys-config 接口参数对齐（configKey/configValue） - 添加 dict 字典项管理 API - 修复 logs 接口参数格式（批量删除/清理日志） - 添加 request.ts postForm/putForm 方法支持 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
440 lines
14 KiB
Markdown
440 lines
14 KiB
Markdown
# Java 后端开发规范
|
||
|
||
## 制定背景
|
||
|
||
提供一套可复用的标准化开发规范，适用于 Spring Boot 企业级应用开发。
|
||
|
||
## 核心原则
|
||
|
||
1. **OpenAPI 规范驱动** - 前后端通过接口规范对齐，零沟通成本
|
||
2. **类型安全优先** - TypeScript 强制类型校验，早发现早修复
|
||
3. **约定大于配置** - 统一代码风格和目录结构，降低认知负担
|
||
4. **自动化优先** - 能自动化的绝不手动（代码生成、部署、测试）
|
||
5. **三层架构分离** - Controller、Service、Mapper 职责清晰
|
||
|
||
---
|
||
|
||
## 一、技术栈规范
|
||
|
||
### 后端技术栈
|
||
|
||
| 组件 | 技术选型 | 版本 | 说明 |
|
||
|:------|:------|:------|:------|
|
||
| 框架 | Spring Boot | 3.2+ | 基于 Java 17 |
|
||
| 持久层 | MyBatis-Plus | 3.5+ | 简化 CRUD |
|
||
| 对象映射 | MapStruct | 1.5+ | VO/Entity 转换 |
|
||
| 数据库连接池 | Alibaba Druid | 1.2+ | 数据库连接池 + 监控 |
|
||
| 安全 | Spring Security + JWT | - | 无状态认证 |
|
||
| API 文档 | Knife4j (SpringDoc) | 4.x | OpenAPI 3.0 |
|
||
| 数据库 | MySQL | 8.0+ | 关系型数据库 |
|
||
| 迁移 | Flyway | - | 版本化数据库变更 |
|
||
| 校验 | Hibernate Validator | - | JSR-303 参数校验 |
|
||
| 缓存 | Redis + Spring Data Redis | - | 缓存、会话存储 |
|
||
| 日志 | Logback | - | 结构化日志 |
|
||
| JSON | FastJSON | 2.x | JSON 序列化 |
|
||
| 工具类 | Hutool | 5.x | 常用工具集合 |
|
||
| 文件存储 | 阿里云 OSS | - | 对象存储 |
|
||
|
||
---
|
||
|
||
## 二、项目结构规范
|
||
|
||
### 后端目录结构
|
||
|
||
主要模块包括 common（公共模块）、controller（控制器层）、service（服务层）、mapper（数据访问层）、entity（实体类）、dto（数据传输对象）、enums（枚举类）。资源配置包括 application 配置文件、Flyway 迁移脚本、日志配置、MyBatis XML。
|
||
|
||
---
|
||
|
||
## 三、三层架构规范
|
||
|
||
### 各层职责
|
||
|
||
| 层级 | 职责 | 数据接收 | 数据返回 |
|
||
|:------|:------|:---------|:---------|
|
||
| **Controller** | 接收请求、参数校验、调用 Service、返回响应 | DTO/Request | VO/Response |
|
||
| **Service** | 处理业务逻辑、事务控制 | DTO/Entity | Entity |
|
||
| **Mapper** | 数据库 CRUD 操作 | Entity/条件 | Entity |
|
||
|
||
### 核心规范
|
||
|
||
1. **Service/Mapper 层必须使用实体类** - Service↔Mapper 之间只用 Entity，禁止 DTO/VO 转换
|
||
2. **转换只在 Controller 层发生** - Entity ↔ VO 转换统一在 Controller 层处理
|
||
3. **Service 继承 IService<T>** - 所有 Service 接口继承 MyBatis-Plus 的 IService
|
||
4. **查询接口默认分页** - 所有返回列表的查询接口，默认进行分页处理
|
||
|
||
### 查询方式选择
|
||
|
||
| 场景 | 推荐方式 |
|
||
|:------|:---------|
|
||
| 单表按 ID 查询 | 通用方法 `getById(id)` |
|
||
| 单表条件查询 | QueryWrapper `list(wrapper)` / `getOne(wrapper)` |
|
||
| 单表分页查询 | QueryWrapper + Page `page(new Page<>(p, s), wrapper)` |
|
||
| 单表统计 | QueryWrapper `count(wrapper)` |
|
||
| 两表联查 | 自定义 SQL `mapper.selectWithXxx()` |
|
||
| 三表及以上 | 自定义 SQL |
|
||
| 聚合统计 | 自定义 SQL |
|
||
| 动态复杂条件 | 自定义 SQL(XML) |
|
||
|
||
### 消除魔法值规范
|
||
|
||
**核心原则：禁止在代码中使用魔法值，所有状态、类型、常量必须使用枚举定义**
|
||
|
||
| 场景 | 规范 |
|
||
|:------|:------|
|
||
| 状态字段 | 使用枚举定义（如 `CommonStatusEnum`） |
|
||
| 类型字段 | 使用枚举定义（如 `UserTypeEnum`） |
|
||
| 常量值 | 使用常量类或接口定义 |
|
||
| 错误码 | 使用枚举定义（如 `ErrorCode`） |
|
||
|
||
**枚举设计规范：**
|
||
- 枚举类统一存放在 `enums` 包下
|
||
- 枚举包含 `code` 和 `desc` 字段，便于前端展示
|
||
- 提供 `getCode()`、`getDesc()`、`valueOfCode()` 方法
|
||
- 数据库存储 `code`，代码中使用枚举
|
||
|
||
---
|
||
|
||
## 四、ORM 实体类规范
|
||
|
||
### 1. 表名命名规范
|
||
|
||
所有数据库表必须添加业务模块前缀，格式为 `t_{模块}_{表名}`：
|
||
|
||
| 模块分类 | 前缀 | 示例 |
|
||
|:------|:------|:------|
|
||
| 用户模块 | t_user_ | t_user, t_user_role |
|
||
| 系统模块 | t_sys_ | t_sys_config, t_sys_log |
|
||
| 业务模块 | t_biz_ | t_biz_order, t_biz_product |
|
||
| 权限模块 | t_auth_ | t_auth_role, t_auth_menu |
|
||
|
||
### 2. 表名与实体类名对应规范
|
||
|
||
**表名与实体类名必须保持一致**，仅允许下划线与驼峰的区别：
|
||
|
||
| 表名（下划线命名） | 实体类名（驼峰命名） |
|
||
|:------|:------|
|
||
| `t_auth_role` | `AuthRole` |
|
||
| `t_user_role` | `UserRole` |
|
||
| `t_sys_config` | `SysConfig` |
|
||
|
||
### 3. 不使用外键约束规范
|
||
|
||
- 数据库表之间**不使用 FOREIGN KEY 外键约束**
|
||
- 表与表之间的关联关系通过**代码逻辑控制**
|
||
- 关联查询通过 `JOIN` 或应用层组装实现
|
||
|
||
### 4. 多对多关系中间表命名规范
|
||
|
||
**核心原则：中间表名必须清晰表达两个关联实体的关系**
|
||
|
||
- 标准命名格式：`t_{实体 A}_{实体 B}`
|
||
- 按字母顺序或业务逻辑顺序排列
|
||
- 不使用 `relation`、`rel`、`link` 等冗余词
|
||
- 实体类名直接使用两个实体名的组合（如 `ParentStudent`）
|
||
|
||
### 5. 基础实体类
|
||
|
||
所有实体类继承 `BaseEntity`，包含公共字段：
|
||
|
||
| 字段 | 类型 | 说明 | 自动填充 |
|
||
|:------|:------|:------|:------|
|
||
| id | Long | 主键 ID（自增） | 数据库自增 |
|
||
| createBy | String | 创建人 | 插入时 |
|
||
| createTime | LocalDateTime | 创建时间 | 插入时 |
|
||
| updateBy | String | 更新人 | 更新时 |
|
||
| updateTime | LocalDateTime | 更新时间 | 更新时 |
|
||
| deleted | Integer | 逻辑删除标识 | - |
|
||
|
||
### 6. 审计字段规范
|
||
|
||
**所有数据库表必须包含审计字段**，用于追踪数据变更历史：
|
||
|
||
| 审计字段 | 类型 | 说明 | 必填 |
|
||
|:------|:------|:------|:------|
|
||
| create_by | VARCHAR(50) | 创建人账号 | 是 |
|
||
| create_time | DATETIME | 创建时间 | 是 |
|
||
| update_by | VARCHAR(50) | 更新人账号 | 是 |
|
||
| update_time | DATETIME | 更新时间 | 是 |
|
||
| deleted | TINYINT | 逻辑删除标识（0-未删除，1-已删除） | 是 |
|
||
|
||
**规范要求：**
|
||
- 审计字段通过 MyBatis-Plus `FieldFill` 自动填充
|
||
- 禁止在业务代码中手动设置审计字段
|
||
- 生产环境审计字段不得为空
|
||
|
||
---
|
||
|
||
## 五、日志规范
|
||
|
||
### 1. 日志语言规范（重要）
|
||
|
||
**所有日志打印内容必须使用中文**
|
||
|
||
| 场景 | 推荐格式 | 示例 |
|
||
|:------|:------|:------|
|
||
| 操作开始 | "开始{操作}，{关键参数}" | `开始创建用户，用户名：zhangsan` |
|
||
| 操作成功 | "{操作}成功，{关键结果}" | `用户创建成功，ID: 123` |
|
||
| 操作失败 | "{操作}失败，{关键参数}" | `用户删除失败，ID: 123` |
|
||
| 查询操作 | "{动作}{对象}，{关键参数}" | `查询用户，ID: 123` |
|
||
| 状态检查 | "{对象}不存在/已存在，{关键参数}" | `用户不存在，ID: 123` |
|
||
| 异常日志 | "{操作}异常，{关键参数}" + e | `创建用户异常，ID: 123` + e |
|
||
|
||
### 2. 日志级别使用场景
|
||
|
||
| 级别 | 使用场景 |
|
||
|:------|:------|
|
||
| ERROR | 系统异常，需要人工介入（数据库连接失败、第三方服务调用失败） |
|
||
| WARN | 业务异常，可预期的错误（参数校验失败、资源不存在） |
|
||
| INFO | 重要的业务操作记录（用户登录、订单创建、支付完成） |
|
||
| DEBUG | 调试信息，开发时使用（方法入参、SQL 执行结果） |
|
||
|
||
### 3. TraceId 链路追踪规范
|
||
|
||
- 使用 `MDC`（Mapped Diagnostic Context）实现 TraceId 链路追踪
|
||
- 通过 AOP 切面在请求入口自动生成 TraceId 并放入 MDC
|
||
- 请求结束时清除 MDC，防止内存泄漏
|
||
- 日志格式包含 `[%X{traceId}]` 实现全链路追踪
|
||
|
||
### 4. 环境差异化日志配置
|
||
|
||
| 环境 | 日志策略 |
|
||
|:------|:------|
|
||
| **开发/测试环境** | 全量记录（DEBUG 级别），包含所有业务日志、SQL 日志、调试信息 |
|
||
| **生产环境** | 精简记录（INFO/WARN 级别），仅记录：请求日志、错误堆栈、错误 SQL、关键业务操作 |
|
||
|
||
### 5. AOP 日志实现规范
|
||
|
||
- 使用 `@Aspect` 定义日志切面，拦截 Controller 层所有方法
|
||
- 请求日志包含：TraceId、请求方法、请求路径、IP、耗时
|
||
- 异常日志包含：TraceId、异常类型、异常消息、堆栈信息
|
||
- 生产环境关闭 DEBUG 日志，避免性能损耗和日志膨胀
|
||
|
||
---
|
||
|
||
## 六、统一响应格式
|
||
|
||
### 1. 响应类定义
|
||
|
||
Result 统一响应类包含 code（状态码）、message（消息）、data（数据）、timestamp（时间戳）字段。
|
||
|
||
### 2. 错误码枚举
|
||
|
||
| 错误码 | 说明 |
|
||
|:------|:------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未登录或 Token 已过期 |
|
||
| 403 | 没有访问权限 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 系统内部错误 |
|
||
|
||
### 3. 全局异常处理器
|
||
|
||
- 使用 `@RestControllerAdvice` 定义全局异常处理器
|
||
- 业务异常返回对应错误码
|
||
- 系统异常统一返回 500
|
||
|
||
---
|
||
|
||
## 七、多环境配置规范
|
||
|
||
### 1. 配置文件目录结构
|
||
|
||
配置文件包括 application.yml（主配置）、application-dev.yml（开发环境）、application-test.yml（测试环境）、application-prod.yml（生产环境）。
|
||
|
||
### 2. 环境配置对比
|
||
|
||
| 配置项 | 开发环境 (dev) | 测试环境 (test) | 生产环境 (prod) |
|
||
|:------|:------|:------|:------|
|
||
| 数据库 | 本地 MySQL | 测试服务器 | 生产服务器 |
|
||
| SQL 日志 | 开启 | 开启 | 关闭 |
|
||
| Swagger | 开启 | 开启 | 关闭 |
|
||
| Flyway Clean | 允许 | 禁止 | 禁止 |
|
||
| JWT 密钥 | 默认值 | 默认值 | 必须环境变量 |
|
||
| Redis 连接池 | 默认 | 默认 | 优化配置 |
|
||
|
||
### 3. 环境切换方式
|
||
|
||
- 方式一：环境变量 `export SPRING_PROFILES_ACTIVE=prod`
|
||
- 方式二：命令行参数 `java -jar project.jar --spring.profiles.active=prod`
|
||
|
||
---
|
||
|
||
## 八、工具类使用规范
|
||
|
||
### 1. 工具函数存放位置
|
||
|
||
| 场景 | 存放位置 |
|
||
|:------|:------|
|
||
| 多个地方调用（≥2 处） | 统一工具类（如 `CommonUtil`） |
|
||
| 仅在一个地方调用 | Service 层内部私有方法 |
|
||
| 业务无关的通用工具 | 独立工具类（如 `DateUtil`, `FileUtil`） |
|
||
|
||
### 2. 工具类设计原则
|
||
|
||
- **私有构造** - 防止实例化
|
||
- **静态方法** - 所有方法都是 `static` 的
|
||
- **无状态** - 工具类不应持有状态
|
||
- **线程安全** - 工具方法必须是线程安全的
|
||
- **充分注释** - 每个方法都要有 JavaDoc 注释
|
||
|
||
### 3. 工具类命名规范
|
||
|
||
| 类型 | 命名格式 | 示例 |
|
||
|:------|:------|:------|
|
||
| 通用工具类 | `XxxUtil` | `CommonUtil`, `DateUtil`, `FileUtil` |
|
||
| 业务工具类 | `XxxHelper` | `UserHelper`, `OrderHelper` |
|
||
| 转换工具类 | `XxxConverter` | `EntityConverter`, `DtoConverter` |
|
||
|
||
---
|
||
|
||
## 九、MapStruct 对象映射规范
|
||
|
||
### 1. Maven 依赖
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>org.mapstruct</groupId>
|
||
<artifactId>mapstruct</artifactId>
|
||
<version>1.5.5.Final</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 2. 使用规范
|
||
|
||
- 定义 Converter 接口，使用 `@Mapper` 注解
|
||
- 接口方法用于 Entity ↔ VO 之间的转换
|
||
- 在 Controller 层调用 Converter 进行对象转换
|
||
- 禁止在 Service 层和 Mapper 层进行 DTO/VO 转换
|
||
|
||
### 3. 命名规范
|
||
|
||
| 类型 | 命名格式 | 示例 |
|
||
|:------|:------|:------|
|
||
| 对象映射接口 | `XxxConverter` 或 `XxxMapStruct` | `UserConverter`, `OrderConverter` |
|
||
|
||
---
|
||
|
||
## 十、Hutool 工具类使用
|
||
|
||
### 常用工具方法
|
||
|
||
- 生成 UUID（不带横杠）：`IdUtil.fastSimpleUUID()`
|
||
- 密码加密（BCrypt）：`SecureUtil.bcrypt(password)`
|
||
- 密码校验：`SecureUtil.bcryptVerify(password, encrypted)`
|
||
- 手机号验证：`Validator.isMatchRegex("^1[3-9]\\d{9}$", phone)`
|
||
- 手机号脱敏：`DesensitizedUtil.mobilePhone(phone)`
|
||
|
||
---
|
||
|
||
## 十、Swagger/Knife4j 配置规范
|
||
|
||
### 1. 接口文档访问
|
||
|
||
- Knife4j UI: `http://localhost:8080/doc.html`
|
||
- OpenAPI JSON: `http://localhost:8080/v3/api-docs`
|
||
|
||
### 2. Controller 层注解
|
||
|
||
- 使用 `@Tag` 注解标注控制器
|
||
- 使用 `@Operation` 注解标注接口
|
||
- 使用 `@Schema` 注解标注 DTO 字段
|
||
|
||
---
|
||
|
||
## 十一、工具函数使用规范
|
||
|
||
**核心原则：工具函数必须集中管理，禁止在 Controller 层直接编写工具方法**
|
||
|
||
### 工具函数存放位置
|
||
|
||
| 场景 | 存放位置 |
|
||
|:------|:------|
|
||
| 多个地方调用（≥2 处） | 统一工具类（如 `CommonUtil`） |
|
||
| 仅在一个地方调用 | Service 层内部私有方法 |
|
||
| 业务无关的通用工具 | 独立工具类（如 `DateUtil`, `FileUtil`） |
|
||
|
||
### 工具类命名规范
|
||
|
||
| 类型 | 命名格式 | 示例 |
|
||
|:------|:------|:------|
|
||
| 通用工具类 | `XxxUtil` | `CommonUtil`, `DateUtil`, `FileUtil` |
|
||
| 业务工具类 | `XxxHelper` | `UserHelper`, `OrderHelper` |
|
||
| 转换工具类 | `XxxConverter` | `EntityConverter`, `DtoConverter` |
|
||
|
||
---
|
||
|
||
## 十二、限流规范
|
||
|
||
### 技术选型
|
||
|
||
| 方案 | 适用场景 |
|
||
|:------|:------|
|
||
| **Redis 滑动窗口** | 推荐：全局限流 |
|
||
| **自定义注解 + AOP** | 推荐：特殊接口限流 |
|
||
|
||
### 常见限流场景建议值
|
||
|
||
| 接口类型 | 时间窗口 | 最大请求数 | 说明 |
|
||
|:------|:------|:------|:------|
|
||
| 登录接口 | 60 秒 | 10 | 防止暴力破解 |
|
||
| 验证码/短信 | 60 秒 | 3-5 | 防止短信轰炸 |
|
||
| 文件上传 | 60 秒 | 30 | 防止资源滥用 |
|
||
| 普通业务接口 | 60 秒 | 100-1000 | 根据业务调整 |
|
||
| 导出接口 | 60 秒 | 5-10 | 防止服务器过载 |
|
||
|
||
---
|
||
|
||
## 十三、FastJSON 配置规范
|
||
|
||
### JSON 工具类
|
||
|
||
- `toJson(Object)` - 对象转 JSON 字符串
|
||
- `parseObject(String, Class)` - JSON 字符串转对象
|
||
- `parseArray(String, Class)` - JSON 字符串转列表
|
||
|
||
---
|
||
|
||
## 十四、阿里云 OSS 文件上传规范
|
||
|
||
### OSS 配置
|
||
|
||
配置项包括 endpoint、access-key-id、access-key-secret、bucket-name、url-prefix，均通过环境变量注入。
|
||
|
||
### 文件命名规范
|
||
|
||
- 使用日期目录：`yyyy/MM/dd/`
|
||
- 使用 UUID 文件名，避免重名冲突
|
||
|
||
---
|
||
|
||
## 附录：快速参考
|
||
|
||
### 表名命名规范
|
||
|
||
- `t_user_*` - 用户模块
|
||
- `t_sys_*` - 系统模块
|
||
- `t_biz_*` - 业务模块
|
||
- `t_auth_*` - 权限模块
|
||
|
||
### Redis Key 命名规范
|
||
|
||
- `auth:token:{token}` - 用户 Token
|
||
- `user:info:{userId}` - 用户信息缓存
|
||
- `dict:{type}` - 数据字典
|
||
- `lock:{resource}:{id}` - 分布式锁
|
||
- `rate_limit:{key}` - 限流计数器
|
||
|
||
### 核心配置速查
|
||
|
||
| 配置项 | 环境变量 |
|
||
|:------|:------|
|
||
| 活跃环境 | `SPRING_PROFILES_ACTIVE` |
|
||
| 数据库地址 | `DB_HOST` |
|
||
| 数据库密码 | `DB_PASSWORD` |
|
||
| Redis 地址 | `REDIS_HOST` |
|
||
| Redis 密码 | `REDIS_PASSWORD` |
|
||
| JWT 密钥 | `JWT_SECRET` |
|
||
| OSS AccessKey | `OSS_ACCESS_KEY_ID` |
|
||
| OSS Secret | `OSS_ACCESS_KEY_SECRET` |
|