| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465 |
- ---
- description: Java CRUD 通用规范（分层、SQL 仅 XML、Mapper、实体、Swagger、注入、自检）；适用于各 java* skill
- globs: "**/*.java,**/mapper/**/*.xml,**/resources/mapper/**/*.xml"
- alwaysApply: false
- ---
- # Java CRUD 通用规则（java-common）
- > 适用范围：各项目 CRUD skill（java1/java2/java4/java5 等）。
- > 目标：跨项目通用约束；项目差异以各 skill「场景差异」为准。
- ## 一、分层职责（通用）
- - 统一分层：`Controller -> Service -> Mapper -> Mapper.xml`
- - `Controller` 仅处理请求接收、参数绑定、响应封装
- - 业务规则、流程编排、事务边界在 `Service` 层
- - `Controller` 不直接操作 `Mapper`
- ## 二、SQL 放置规则（通用）
- - SQL 只能写在 `*Mapper.xml`
- - 禁止在 `Controller`/`Service` 中拼接 SQL
- - 禁止在 `Mapper.java` 使用注解 SQL（如 `@Select/@Update/@Delete/@Insert`）
- ## 三、Mapper/XML 规范（通用）
- - `Mapper.java` 仅保留方法签名
- - 自定义方法必须在 `*Mapper.xml` 中提供同名 `id`
- - `namespace` 必须与 Mapper 接口全限定名一致
- - `Mapper.xml` 目录统一 `resources/mapper/**`
- - 禁止 `select *`，必须显式列字段
- - 动态 SQL 使用标准标签：`where/trim/set/foreach`
- ## 四、实体生成规范（通用）
- - 除非用户明确要求，否则实体类默认使用 Lombok 生成样板代码（如 `@Data`、`@Builder`、`@NoArgsConstructor`、`@AllArgsConstructor`）
- - 若项目已有既定风格（例如仅使用 `@Getter/@Setter`），优先跟随项目既有风格
- ## 五、Swagger 规范（通用）
- - 若项目已使用 Swagger/OpenAPI（如 Springfox、springdoc、Knife4j），必须沿用现有方案与注解风格
- - 若项目未使用 Swagger/OpenAPI，且任务涉及接口开发或文档能力，需要引入与当前 Spring Boot 版本匹配的实现方案
- - 引入后应保持文档注解风格统一，避免在同一项目混用多套 Swagger 方案
- ## 六、依赖注入规范（通用）
- - 若项目其他模块已有明确注入风格（如 `@Resource`、`@Autowired`、`@RequiredArgsConstructor`），优先沿用既有实现
- - 若项目中没有可参考的既有实现，默认使用构造器注入，并使用 Lombok `@AllArgsConstructor` 注入 Service 或其他依赖对象
- ## 七、标准生成步骤（通用）
- 1. 识别实体与主键信息（并检查是否已有同名文件）
- 2. 生成/补全 Controller（分页、详情、新增、修改、删除、批删）
- 3. 生成/补全 Service 与 ServiceImpl（不写 SQL）
- 4. 生成/补全 Mapper 与 Mapper.xml（SQL 全部落 XML）
- 5. 按项目差异对齐返回体、路由风格、日志/权限注解
- ## 八、自检清单（通用）
- - [ ] 无注解 SQL（`@Select/@Update/@Delete/@Insert`）
- - [ ] Controller 无业务编排
- - [ ] SQL 全部在 `*Mapper.xml`
- - [ ] `namespace` 与 Mapper 全限定名一致
- - [ ] 未使用 `select *`
- - [ ] 接口风格与目标模块一致
|
