# 通用后端开发规范 ## 1. 文档定位 本文记录可跨项目复用的后端开发约定，适用于以服务端 API、数据库、外部系统适配和业务规则为核心的后端项目。 复制到新项目后，应根据实际技术栈、目录结构、启动命令、接口契约和业务约束做项目级补充。当前项目的业务专属规则不应写入本文。 ## 2. 技术栈原则 具体版本以项目内构建文件为准，例如 `server/pom.xml`、`build.gradle` 或其他构建配置。 通用要求： - 升级 Java、Spring Boot、ORM、OpenAPI、数据库迁移工具或核心框架前，必须先做兼容性验证。 - 项目应提供可重复执行的本地启动、测试和构建命令。 - 后端依赖应按职责引入，避免为了少量功能引入过重框架。 - 外部 SDK、Provider Client 和生成代码应隔离在适配层，不进入领域模型。 - 新项目必须明确语言版本、语法版本、框架版本、ORM / Mapper、数据库迁移工具、OpenAPI 工具和测试框架之间的兼容关系。 - 构建文件应显式声明编译目标版本，避免本地、CI 和生产运行时不一致。 - Spring Boot 主版本与 ORM、OpenAPI、测试、插件 starter 必须匹配；例如 Spring Boot 3 项目应使用支持 Boot 3 的 starter。 - 引入 ORM 增强框架或 starter 后，不应再重复引入同生态的原生 starter，避免自动配置和依赖版本冲突。 ## 3. 后端分层与模块边界 推荐按业务能力和技术边界组织模块，而不是把所有代码堆在一个公共包里。 常见边界： ```text server/src/main/java/ ├── common ├── config ├── modules │ └── │ ├── control │ ├── service │ ├── service/impl │ ├── domain │ ├── mapper │ ├── repository │ └── common │ ├── dto │ ├── request │ ├── result │ └── enums ├── integrations │ └── //adapter └── support ``` 目录树、包结构、分层图和模块边界说明必须配中文注释或中文说明，不能只给英文目录名。建议在目录树后补充说明表，说明每一层的职责、依赖方向、可以调用什么、禁止调用什么。 职责规则： - 一个业务模块只负责一个清晰业务能力。 - 通用能力不能反向依赖具体业务模块。 - 跨模块调用优先通过 Service、Port、API 契约或事件完成。 - 禁止直接访问其他模块的 Mapper、Entity 或内部实现。 - 外部系统通过 `integrations` 或 Adapter 隔离，业务层只依赖稳定端口。 - 外部协议适配类放在具体集成模块的 `adapter` 包，例如 `integrations...adapter`。 - 外部协议转换类使用 `Adapter`、`Converter` 等后缀，不使用 `Mapper` 命名，避免和 MyBatis Mapper 混淆。 - 外部 DTO、数据库 Entity、领域对象和 API Response 必须分离。 - 公共代码只有在出现真实重复和稳定语义后再抽取。 ## 4. Controller / Service / Repository 规则 - Controller 只处理 HTTP 契约、参数校验、权限入口和响应映射。 - Controller 不直接访问 Mapper，不直接调用外部适配器。 - Service 负责业务编排、事务边界、领域对象、Repository 和外部端口调用。 - Domain 对象表达稳定业务语义，不引入 HTTP、JSON、ORM 或外部 Provider 细节。 - Repository 是领域侧持久化接口。 - Mapper / Entity / SQL 属于持久化细节，不应向上泄漏到 API 层。 - 外部调用通过 Port / Adapter 隔离，业务层不依赖厂商 SDK 或厂商 DTO。 - Request、Command、Query 条件建议放在模块内 `common.request`。 - Result、分页结果、操作结果建议放在模块内 `common.result`。 - 跨层 DTO、Snapshot、Draft 等通用数据载体建议放在模块内 `common.dto`。 - 枚举、状态码和失败原因建议放在模块内 `common.enums`。 - 生成或迁移代码前应先阅读项目规范并查看同模块既有代码习惯；目录归属、类名后缀或依赖方向不明确时，先询问再实现。 ## 5. 数据建模规则 - 内部主键、外部业务标识、第三方系统 ID 和展示编号必须分开建模。 - API 返回给前端的长整型 ID 建议使用字符串，避免 JavaScript 精度问题。 - 状态使用稳定代码，展示文案只用于显示。 - 不把中文或英文显示文本当作接口契约或业务判断依据。 - 金额使用 `BigDecimal`，并明确币种、精度和舍入规则。 - 日期、时间、时区必须结构化保存，不只保存展示字符串。 - JSON 字段只用于扩展元数据，不替代需要查询、约束或索引的正式列。 - 写操作应考虑幂等、并发版本、审计字段和失败恢复。 更多后端基础结构、ID、审计字段、分页和 Mapper 规范见 `backend-base-structure-pagination-guidelines.md`。 ## 6. 数据库与 Migration 规范 - 新建表和改表必须通过 migration 管理。 - 已发布 migration 禁止直接修改。 - 修正注释、索引或约束必须新增 migration。 - 表、字段、索引和约束命名应清晰表达业务含义。 - 业务表建议包含创建时间、更新时间、创建人、更新人、逻辑删除和版本字段。 - 需要查询、排序、唯一性或关联的字段必须有明确索引策略。 - 新项目建表前必须确认数据库字符集和 collation 策略，不能依赖数据库实例默认值。 - MySQL 项目建议新建表显式使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`，让字符串默认按大小写敏感保存和比较。 - 外部 opaque id、第三方消息 ID、哈希、Token、nonce、幂等键、状态码和业务代码必须大小写敏感；否则容易出现 `X` 与 `x` 被误认为同一值的幂等或唯一键问题。 - 如果业务需要大小写不敏感搜索，应通过查询层归一化、搜索字段、专门索引或搜索引擎实现，并在项目规范和 migration 注释中说明原因，不建议把整库或整表默认改回大小写不敏感。 - 新建表模板： ```sql CREATE TABLE example_table ( id BIGINT NOT NULL COMMENT '内部主键 ID', external_id VARCHAR(256) NULL COMMENT '外部系统 ID，按大小写敏感保存和比较', created_at DATETIME(6) NOT NULL COMMENT '记录创建 UTC 时间', PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表'; ``` - 测试数据、真实业务数据和本地样本不得直接提交到仓库。 ## 7. API 设计规范 - API 契约应有唯一来源，例如 OpenAPI、后端生成文档或共享契约文件。 - 接口字段使用稳定字段名和稳定业务代码。 - 前端业务判断不得依赖展示文案。 - 错误响应应使用统一结构，不回显 Secret、Token、原始报文或个人敏感信息。 - 写接口必须考虑幂等、并发版本、审计和失败恢复。 - 外部写操作结果不明确时，禁止盲目重试。 - 调试接口必须默认关闭，并使用独立访问控制。 ## 8. 安全与日志 Secret 只能通过环境变量、本地 `.env` 或部署平台 Secret 注入。仓库只提交无真实值的 `.env.example`。 禁止提交： - API Key、Token、Cookie、数据库密码和私钥。 - 真实客户数据、生产数据、支付信息和个人敏感信息。 - 外部系统真实凭证、真实请求报文和真实响应报文。 日志要求： - 日志必须有足够上下文，方便定位问题。 - 禁止输出 Secret、Token、Cookie、身份证件、支付卡、原始敏感正文和附件 URL。 - 捕获异常后不能静默吞掉，应保留错误上下文并转换为合适的业务错误。 ## 9. 配置规范 - 本地、测试、生产配置应分环境管理。 - Secret 与非敏感配置应分开。 - 后端 Secret 不得暴露给前端公开环境变量。 - 生产环境推荐使用部署平台 Secret、密钥管理系统或容器 Secret。 - 配置项应有清晰命名、默认值策略和缺失时的失败方式。 ## 10. 后端代码注释规范 后端 Java 代码应提供必要且准确的中文注释： - 架构文档、设计文档、目录结构、数据模型、字段映射和接口示例必须优先使用中文说明业务含义。 - 领域对象、应用服务、外部适配器、Controller、配置属性和复杂参数对象应说明业务含义、边界或调用约束。 - Mapper 中 ORM 自带继承方法不强制补中文注释；不要为了重命名 `selectById`、`insert`、`updateById` 等自带方法而写薄包装。自定义语义化查询、写入、更新方法应根据业务复杂度合理补充中文注释。 - Entity 字段建议有中文注释，说明字段业务含义、来源、代码值范围或安全限制。 - 复杂流程、幂等键、并发控制、事务边界、错误转换、外部字段映射和安全脱敏逻辑必须说明原因。 - 注释不得只复述类名、方法名或字段名。 - 不得用“TODO 待完善”替代真实说明。 - 修改旧代码时，应补齐触达代码的必要中文注释。 Java 代码风格默认参考 `alibaba-java-coding-guidelines-summary.md`。 ## 11. 测试与检查命令 后端项目应至少提供： ```bash cd server ./mvnw test ./mvnw verify ``` 如果项目不是 Maven，应在项目级文档中替换为实际命令。 聚焦开发时可先运行相关测试： ```bash cd server ./mvnw -Dtest=SomeFocusedTest test ``` 如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。 ## 12. Git 与协作流程 - 改动前说明目标、范围和将修改的文件。 - 每次只处理一个模块或一个纵向切片。 - 需求基准变化时，先做差异和影响分析。 - 修改接口前确认领域模型、字段映射、前端影响和测试范围。 - 不修改与当前任务无关的用户变更。 - 修改后运行项目已配置的检查命令。 - 生成或迁移代码前先参考当前项目代码规范和既有代码习惯；如果目录归属或命名不确定，先确认再继续。 - Git commit message 使用中文，清楚说明本次提交的业务或技术变更。 ## 13. 后端提交前检查清单 - [ ] Controller 是否没有直接访问 Mapper 或外部 Adapter？ - [ ] Request、Result、DTO 是否按语义放在 request、result、dto 目录，而不是混在 Service 或临时 application 包？ - [ ] 外部协议适配类是否放在 integrations 的 adapter 包，并避免使用 Mapper 命名混淆 ORM Mapper？ - [ ] Mapper 是否没有为了 ORM 自带继承方法写薄 default 包装？ - [ ] 外部 DTO 是否没有进入领域模型？ - [ ] DTO、Entity、Domain、Response 是否没有混用？ - [ ] 跨模块调用是否通过稳定接口完成？ - [ ] 写接口是否有幂等、版本或审计设计？ - [ ] 数据库变更是否通过 migration 管理？ - [ ] Java 复杂逻辑是否有必要中文注释？ - [ ] 是否没有提交真实 Secret、真实客户数据或敏感报文？ - [ ] 是否运行了项目后端检查命令或说明了无法运行原因？