Haigle 后端 Java 开发规范

解决什么问题

Haigle 后端项目在长期协作中容易出现几类隐性偏差：数据库改动缺少可追溯的增量脚本；请求 VO 与响应 VO 对时间字段的表示不一致；Service 层混入自定义 SQL，数据访问边界模糊；updateById 会静默忽略 null 字段；复杂 SQL 写进注解字符串后难以维护；springdoc/Knife4j 按类的简单名注册文档组件，不同外层 VO 复用同名嵌套静态类时互相覆盖，接口返回正常但文档字段不全或错乱。

技能如何工作

规范把上述问题拆成可执行约定：

• 数据库：每次涉及数据库变动都要创建 SQL 增量文件，命名为 本次变动名称-时间戳到秒.sql，例如 order-update-20260803155501.sql；同时把 SQL 按项目模块整合进原 SQL。
• 字段：请求 VO 的时间类型用 String 接收；响应 VO 的时间类型与数据库保持一致，并在时间字段上添加规范要求的注解。
• Mapper：Service 层不允许出现自定义 SQL 查询方法，这类查询必须放在 Mapper 中；updateById 不会更新 null 字段，需要用 LambdaUpdateWrapper 显式 set null；复杂 SQL 写 XML，不允许用注解字符串；生成完代码最后不用编译验证。
• Swagger：VO 中的嵌套静态类必须全局唯一命名，推荐带业务前缀，如 OrderItemVO、ProductGroupVO；若必须使用通用名，则加唯一 @Schema(name = ..., description = ...)。排查文档字段不对但接口返回正确的问题时，先用 Grep 查找 public static class \w+ 找出重复的嵌套类简单名，再给冲突类加唯一 @Schema(name = ...)；这只影响文档组件名，不改变接口 JSON。

适用边界与注意点

这套规范适用于 Haigle 后端 Java 项目里需要统一 SQL 增量、VO 时间字段、Mapper 边界和文档组件命名的场景。它不补充 SKILL.md 之外的示例注解或代码实现；示例 1、示例 2 在原始资料中以引用形式出现，使用时需要结合项目上下文确认。文档组件重名只影响 springdoc/Knife4j 的展示，不会改变接口实际返回结构。