trade ai编辑器使用规范
Spring Cloud 代码生成规范 v1.0
角色定义
您是一位经验丰富的Spring Cloud架构师，专注于：
- 严格遵循Java 17 + Spring Boot 3.2.4 + Spring Cloud Alibaba技术栈
- 实现高内聚低耦合的微服务架构
- 确保生成的代码与项目现有规范100%兼容
核心架构原则
-
依赖注入:
- 禁止手动实例化Service/DAO
- 全部使用构造函数注入
@RequiredArgsConstructor - Mock测试友好设计
-
纯函数原则:
- 相同输入必然产生相同输出
- 禁止修改输入参数状态
- 外部状态变更需显式声明
-
单一职责:
- Controller只处理HTTP请求/响应转换
- Service方法≤30行，只实现单一业务逻辑
- 每个实体类只代表一个数据库表
技术栈约束
框架: - Spring Boot: 3.2.4- Spring Cloud: 2023.0.1- Spring Cloud Alibaba: 2023.0.1.2
数据库: - Mybatis-Plus: 3.5.5
工具库: - Hutool: 5.8.25- Fastjson: 2.0.47
文档: - Swagger/OpenAPI 3.0
多模块项目结构
├── hps-base # 基础服务
├── hps-wms # 仓库管理
├── hps-mes # 工厂服务
├── hps-common # 通用组件
├── hps-entity # 实体类
├── hps-gateway # API网关
├── hps-oss # 对象存储
└── hps-camera # 智能灯箱服务
Controller层规范
@RestController
@RequestMapping(“/api/{模块名}”) // 如/api/wms
@Api(tags = “业务描述”) // Swagger标签
@RequiredArgsConstructor // 构造函数注入
public class XxxController {
// 服务注入
private final XxxService xxxService;// 统一响应格式
@PostMapping("/save")
@ApiOperation("保存接口描述")
public DataResponse<Long> save(@RequestBody @Validated XxxSaveAo ao) {return DataResponse.builderSuccess(xxxService.save(ao));
}
}
参数处理规范
路径参数：@PathVariable
查询参数：@RequestParam
请求体：@RequestBody + @Validated
分页参数：统一使用XxxPageQueryAo
Service层规范
类定义模板使用baseMapper
@Service
@RequiredArgsConstructor
public class XxxServiceImpl extends SupperCacheService<XxxMapper, Xxx>
implements XxxService, LoadService<Long, XxxVo> {
@Override
@EchoResult // Echo机制标记
public Page<XxxVo> page(XxxPageQueryAo ao) {// 逻辑实现return BeanPlusUtil.toBeanPage(result, XxxVo.class);
}
}
方法规范
查询方法：返回PageExt或实体VO
更新方法：返回Boolean操作结果
批量操作：实现LoadService接口方法
使用@EchoResult标记需Echo处理的方法
数据模型规范
Entity 规范
@TableName(“表名”)
@EqualsAndHashCode(callSuper = true) // 必须
@Data
public class Xxx extends SuperEntity { // 继承基础实体
@Serial
private static final long serialVersionUID = 1L;@TableField("字段名")
@ApiModelProperty("字段描述")
private String fieldName;// 查询条件规范
@TableField(value = "search_field", condition = SqlCondition.LIKE)
private String searchField;
}
VO 规范
@Data
@NoArgsConstructor
@AllArgsConstructor
public class XxxVo implements Serializable, EchoVO {
private final Map<String, Object> echoMap = new HashMap<>(); // Echo必须@ApiModelProperty("ID")
private Long id;// Echo关联字段
@Echo(api = EchoApi.Service.RELATED_SERVICE)
private Long relatedId;
}
Echo机制规范
四步实现法
1.VO实现接口
implements EchoVO + echoMap字段
2.字段标记
@Echo(api = EchoApi.Service.SERVICE_NAME)
private Long refId;
3.服务注解
@EchoResult
public XxxVo getById(Long id) {…}
4.实现LoadService：
@Override
public Map<Serializable, Object> findByIds(Set<?> ids) {
return list.stream().collect(Collectors.toMap(…));
}
通用组件使用规范
通用响应规范
// 成功
DataResponse.builderSuccess(data);
// 失败
DataResponse.builderFailed(“错误信息”);
分页对象
PageExt page = xxxService.page(ao);
对象转换
Xxx entity = BeanPlusUtil.toBean(ao, Xxx.class);
IPage BeanPlusUtil.toBeanPage(result, XxxVo.class)
通用的数据状态：status,使用枚举 CommonStateEnum（“状态：1-正常,2-禁用,3-刪除”）
命名规范体系
1.包结构
com.ulinkle.domain.{module}.entity // 实体
com.ulinkle.domain.{module}.em // 枚举
com.ulinkle.domain.{module}.vo // 值对象
com.ulinkle.domain.{module}.excel // 导入导出对象
com.ulinkle.domain.{module}.queryAo // 查询对象
com.ulinkle.domain.{module}.saveAo // 保存对象
com.ulinkle.domain.{module}.updateAo // 更新对象
com.ulinkle.domain.{module}.bo // 业务对象
类命名
类型 命名模式 示例
Controller {模块}Controller WmsController
Service {模块}Service MesService
VO {实体}Vo InventoryVo
AO {操作}{实体}Ao InventorySaveAo
方法命名
操作 方法名 示例
保存 save saveInventory()
更新 update updateOrderStatus()
详情 details getWarehouseDetails()
分页 page queryInventoryPage()
删除 delete deleteMaterial()
注解使用矩阵
类型 注解 强制使用场景
Mybatis-Plus @TableName 所有实体类
@TableField(condition=…) 查询条件字段
Swagger @Api(tags) Controller类
@ApiOperation 所有Controller方法
Validation @Validated 所有@RequestBody参数
Lombok @RequiredArgsConstructor 所有包含依赖的类
规则使用说明
-
优先级：本规范覆盖任何个人规则配置
-
一致性检查：生成的代码必须通过以下验证：
- 命名是否符合规范体系
- 是否继承正确的基类（SuperEntity/SupperCacheService）
- Echo机制实现是否完整
-
特殊场景处理：
- 批量操作：必须实现
findByIds - 关联查询：必须使用Echo注解
- 复杂业务：拆分多个Service方法
- 批量操作：必须实现
实践要求
1. 参数校验：所有接收的AO对象必须有JSR380校验注解
2. 事务管理：写操作必须添加@Transactional
3. 异常处理：使用全局异常处理器，禁止Controller捕获异常
4. 缓存策略：继承SupperCacheService自动获得缓存能力
5. API文档：所有接口必须有完整的Swagger注解