backend-api-design

name	backend-api-design
description	后端接口设计强制规范：仅用 GET/POST；禁止 PUT/DELETE；请求体/响应体禁止直接使用 Map，必须定义 DTO/VO；批量查询需防 N+1；SQL 仅限 XML 或 Mapper 注解，Service 禁止拼 SQL（特殊无映射表需集中封装）；接口入参和响应对象必须有中文注释，方法关键操作需有清晰中文注释。用于接口设计、开发、评审、改动自查。

后端接口设计规范

适用场景

• 设计/修改后端 API（Controller/Service/Mapper）。
• 编写/评审接口文档，或开发自测、问题排查时校验是否合规。

硬性规则

1. HTTP 动词：仅允许 GET、POST。禁止 PUT、DELETE；更新/删除改用 POST + 语义化路径/操作码。
2. 载荷类型：请求体与响应体禁止直接使用 Map/HashMap 等字典；必须定义明确的请求 DTO 与响应 VO/DTO。
3. 批量查询防 N+1：
   • Service/DAO 必须批量取数：IN 批量查询或 JOIN 预取关联数据，禁止循环单查。
   • 若用 ORM 延迟加载，需关闭或预加载（fetch join/IN 预取）防止 N+1。
4. SQL 书写位置：仅允许在 XML 或 Mapper 注解中写 SQL；Service 层禁止字符串拼接 SQL。
   • 极少数无对象映射的特殊表，如需手写 SQL，须集中封装单一路径（专用 Repository/Mapper），禁止各处散写。
5. 注释要求：
   • 接口入参 DTO、响应 VO 字段必须有中文注释，说明业务含义/单位/取值范围（若适用）。
   • Controller/Service 中的关键操作（校验、核心分支、外部调用、事务边界等）需有简洁中文注释说明目的或影响。
6. 日志要求：
   • 代码的关键节点，或者逻辑比较复杂的地方需要有清晰的中文日志。

自检清单

• 路由与方法：
  • 无 PUT/DELETE 映射；更新/删除是否改为 POST。
• DTO/VO：
  • 请求/响应均为显式 DTO/VO，无 Map 直接暴露。
  • 字段有中文注释，含义/单位/范围清晰；必要处有校验注解（如 @NotNull, @Size）。
• 批量查询：
  • 批量接口未在循环中单查；SQL 使用批量 IN 或 JOIN。
  • ORM 关联已预加载/禁 Lazy 触发 N+1；必要时有单测或日志验证。
• SQL 位置：
  • Service 层无字符串拼接 SQL。
  • 特殊无映射表的 SQL 是否集中封装、入口统一。
• 注释：
  • DTO/VO 字段中文注释齐全。
  • 关键业务操作处有中文注释说明目的/影响。

处理违规的操作步骤

1. 标注违规文件/行号与问题类型（HTTP 动词、Map、N+1、SQL 位置、注释缺失）。
2. 提出修正方案（示例 DTO/VO、批量查询写法、SQL 下沉到 Mapper/XML、补充中文注释）。
3. 修正后按自检清单复核。

输出要求

• 回复需说明检查范围与发现问题；若无违规，明确声明“已按规范检查，未发现违规”。