代码生成标准指南

前置检查清单

生成代码前，请确认以下信息：

• [ ] 业务模块名称（如 demostu、teacher）
• [ ] 数据表名（如 tb_b_demo_stu）
• [ ] 数据库类型（MySQL 或 Kingbase/人大金仓）
• [ ] 是否需要分页查询
• [ ] 项目引入的 Swagger 版本（springfox v2 或 springdoc v3）

包结构说明

以业务模块（如 demostu）为单位组织代码，目录结构如下：

poc-service/
├── poc-service-business/          # 业务层模块
│   └── src/main/java/cn/szhn/poc/service/business/{module}/
│       ├── constants/             # 常量枚举类
│       │   ├── XxxOfBusinessExceptionCodeEnum.java  # 业务异常码枚举
│       │   ├── XxxOfLogCodeEnum.java                # 日志码枚举
│       │   └── XxxStatusEnum.java                   # 状态枚举
│       ├── controller/            # Controller 层
│       │   └── XxxController.java
│       ├── manager/               # Manager 层接口与实现
│       │   ├── XxxManager.java
│       │   └── impl/
│       │       └── XxxManagerImpl.java
│       └── model/                 # VO/DTO 模型
│           ├── dto/
│           │   └── XxxPageDTO.java
│           └── vo/
│               ├── XxxQueryVO.java
│               └── XxxVO.java
│
├── poc-service-domain/            # 领域层模块
│   └── src/main/java/cn/szhn/poc/service/domain/{module}/
│       ├── mapper/                # Mapper 接口
│       │   └── XxxMapper.java
│       └── model/                 # DO 数据对象
│           └── XxxDO.java
│
└── poc-service-domain/src/main/resources/mapper/{module}/
    └── XxxMapper.xml              # MyBatis XML 映射文件

分层架构说明

本项目采用以下分层结构：

层级	职责	调用关系
Controller	接收 HTTP 请求参数、参数校验、调用 Manager、返回响应	Controller → Manager
Service	Dubbo 接口定义与实现	Service → Manager
Manager	业务逻辑封装、事务边界、日志记录、异常处理	Manager → Mapper
Mapper	数据访问、SQL 执行	Mapper → 数据库

Web 请求链路

HTTP Request → Controller → Manager → Mapper → Database

Dubbo 服务链路

Dubbo Client → Service → Manager → Mapper → Database

Step-by-step 生成流程

Step 1：确定命名

根据业务模块名称，按以下规则确定各层类名：

类型	命名规则	示例（模块名 DemoStu）
Controller	XxxController	DemoStuController
Service Dubbo服务接口	XxxService	DemoStuService
Service Dubbo服务实现	XxxServiceImpl	DemoStuServiceImpl
Manager 业务接口	XxxManager	DemoStuManager
Manager 业务实现	XxxManagerImpl	DemoStuManagerImpl
Mapper	XxxMapper	DemoStuMapper
DO	XxxDO	DemoStuDO
VO（入参）	XxxVO / XxxQueryVO	DemoStuVO / DemoStuQueryVO
DTO（返参）	XxxDTO / XxxPageDTO	DemoStuDTO / DemoStuPageDTO
业务异常码枚举	XxxOfBusinessExceptionCodeEnum	DemoStuOfBusinessExceptionCodeEnum
日志码枚举	XxxOfLogCodeEnum	DemoStuOfLogCodeEnum
其他枚举	XxxStatusEnum	DemoStuStatusEnum

Step 2：确定方法命名

操作类型	方法前缀	示例
获取单个对象	get	getById
获取多个对象	list / query	queryPage
获取统计值	count	countByCondition
插入	add / save	add
删除	remove / delete	deleteById
修改	update	updateById
启用	enable	enableById
禁用	disable	disableById

Step 3：配置 Swagger 注解

根据项目实际引入的 Swagger 版本选择对应注解：

注解目标	Swagger 2 (springfox)	Swagger 3 (springdoc)
Controller 类	@Api(tags = "描述")	@Tag(name = "描述")
接口方法	@ApiOperation("描述")	@Operation(summary = "描述")
方法参数	@ApiParam("描述")	@Parameter(description = "描述")
模型类	@ApiModel("描述")	@Schema(description = "描述")
模型字段	@ApiModelProperty("描述")	@Schema(description = "描述")

类和方法注解需填写明确的业务描述，不留空。VO/DTO 中的复杂字段建议添加 example 示例值。

Step 4：选择对应模板生成代码

代码层级	模板文件
Controller	Controller 模板
Dubbo Service	Service 模板
Manager	Manager 模板
Mapper	Mapper 模板
DO/VO/DTO/枚举/常量	POJO 模板
Mapper XML	Mapper XML 模板

Do's and Don'ts

Do（推荐做法）	Don't（避免做法）
Controller 入参使用 VO，返参使用 DTO	入参和返参混用同一类型
数据变更方法标注 @Transactional(rollbackFor = Exception.class)	遗漏事务注解导致数据不一致
DO 继承项目基类（BaseDO 或 KingBaseDO）	在项目中自定义新的 BaseDO
分页查询继承 BasePageQueryVO	自行定义分页参数
日志使用 log.info("[{}] ...", LogCodeEnum.XXX.code(), params) 格式	使用 System.out 或 e.printStackTrace()
业务异常使用 BusinessException.error(enum) 抛出	直接抛出 RuntimeException
所有类添加 @author 和 @since Javadoc 注释头	省略类级别文档注释