前言

很多团队只有零散编码规范，缺少开发流程约束 + 分层调用规则 + 数据库操作强制规约。本文整理一套可落地、强制执行的后端开发行为准则，新成员直接遵照执行，降低代码评审冲突、减少 Bug、降低维护成本。

全局行为准则（开发强制执行）

alwaysApply: true

一、交互与开发工作流程

1. 先思考后编码 写代码前梳理现有文件、已有实现、业务约束，禁止盲目改动；已确认过的文件无需重复读取。
2. 输出推理完整、表达精简 编码方案必须写明关键假设、风险点、核心结论，不省略影响功能实现的重要逻辑。
3. 优先增量修改现有代码 只修改需要变更的代码范围，禁止全盘重写文件，最大限度减少回归风险。
4. 功能变更后必须验证 新增 / 修改逻辑完成后，优先单元测试、接口调试、手动请求验证，确认无误再交付。
5. 多方案场景主动提供选型 存在多种实现方案时，给出优选方案，并列出优缺点，由开发人员确认选择，不擅自决定。
6. 文件删除前置确认 任何文件删除操作，必须提前确认，禁止直接移除代码文件。
7. 用户需求优先级最高 若业务需求和本规范冲突，以业务需求为准。

二、通用 Java 编码规范

1. 固定常量强制使用枚举 状态、业务类型、选项等固定取值，必须单独定义枚举类；禁止散落数字常量、字符串魔数。
2. 包导入规范

• 全面淘汰javax.*，统一使用jakarta.*相关包；
• import 必须引入真实存在的类，杜绝不存在的包路径。

1. 中文编码规范 代码、注解、返回文案禁止出现中文乱码，出现编码问题第一时间修复。
2. 实体、DTO、VO 注解规范

• 所有字段添加@Schema(description = "字段含义，取值范围：xxx")；
• 实体类头部注释说明用途、业务含义、核心字段说明。

1. 分层类注释规范 Controller、Service、ServiceImpl、Mapper 头部增加注释，说明类职责、内部核心方法作用。
2. 导入与代码格式化

• 禁止import *通配导入，所有类显式导入；
• 禁止直接使用超长全限定类名，优先 import 引入；
• 严格遵循阿里巴巴 Java 开发手册，统一缩进、换行，注解合理换行排版。

1. 依赖注入统一方案 Controller、ServiceImpl 统一使用@RequiredArgsConstructor构造注入； 成员变量定义为private final XxxService xxxService； 无特殊场景禁止使用@Autowired、@Resource。
2. 对象属性拷贝 同类 / 相近实体转换优先使用BeanUtils.copyProperties()。
3. 前后端返回隔离原则 Controller 查询接口禁止直接返回数据库 Entity，必须转为 VO 对外输出。
4. 时间序列化注解强制规范

• LocalDateTime / Date：@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
• LocalDate：@JsonFormat(pattern = "yyyy-MM-dd")

三、数据库 & Mybatis-Plus 持久层规范

1. 杜绝循环单条操作数据库 批量新增、删除、查询必须使用框架批处理方法：saveBatch、removeBatchByIds、listByIds； 严禁在for/while循环中逐条操作 DB。
2. 分层调用强制规则

• Controller 层：跨表业务调用，只能调用对应 Service 接口，禁止直接注入 Mapper；
• ServiceImpl 层：关联其他表操作，同样调用目标 Service 接口；
• ServiceImpl 内部优先使用父类内置方法；自定义复杂 SQL 编写至mapper.xml，通过 baseMapper 调用；
• Service 必须继承IService，ServiceImpl 继承ServiceImpl；ServiceImpl 不允许额外注入 Mapper，跨表操作依靠 Service。

1. 查询条件设计规范 列表、分页查询尽量不用 ID 作为唯一筛选条件；优先使用编码、名称、状态、类型、时间区间做查询条件。
2. 唯一性校验规范 数据表存在编码、名称字段时，新增、更新接口必须校验编码唯一、名称唯一；编码生成统一封装工具类（如RecordNoUtils）。
3. 实体类定义约束 ServiceImpl 业务代码内不允许定义新实体；所有 Entity、DTO、VO 统一在 API 模块管理。
4. 新增数据表字段全量同步 数据表新增字段时，同步修改：Entity、DTO、PageDTO、VO、Mapper、mapper.xml、Service、ServiceImpl、Controller，保证全链路兼容。
5. 骨架代码实现边界 需求仅要求基础骨架时，只生成 Entity、Mapper、mapper.xml、Service、ServiceImpl，不实现业务接口逻辑。
6. 数据删除联动清理 删除数据表、实体类时，全局检索清理所有引用该实体的业务代码。

四、Controller & RESTful API 规范

1. 类上禁止使用 @RequestMapping 不在 Controller 类上加@RequestMapping，接口路径全部定义在@PostMapping/@GetMapping等方法注解上。
2. 接口路径统一格式标准

• 接口统一前缀 /private；
• 路径包含模块名 + 动作动词（create/update/get/delete/page 等）； 示例：@PostMapping("/system/private/user/create")
• 历史遗留不规范接口，迭代时逐步整改补齐标准路径。

五、并发与分布式安全规范

涉及新增、修改、删除等高并发业务场景，优先采用 Redis 实现分布式锁，保障数据原子操作，避免超卖、重复创建等问题。

六、日志与通用方法复用

1. 操作日志统一通过 AOP 切面 + 注解实现 禁止在 ServiceImpl 业务代码中硬编码日志埋点，基于注解切面统一记录操作日志。
2. 通用方法抽取规范 同一个逻辑在两处及以上调用，必须抽取至通用工具类或者公共业务 Service，避免代码重复。

七、测试与交付规范

1. 新增接口优先编写单元测试；
2. 接口上线前完成参数校验、异常场景、边界值测试；
3. SQL 变更必须提前核对索引、执行效率，杜绝慢 SQL 上线；
4. 迭代交付附带变更范围说明，方便代码评审。