落地spring boot rest接口规范的核心是“三定”：定结构（统一路径版本与响应格式）、定行为（http方法与资源路径严格对齐）、定约束（工具链固化校验）及定边界（明确禁止项）。
落地 Spring Boot REST 接口规范，关键不是堆砌理论，而是把设计原则转化为可执行、可检查、团队能一致遵循的日常动作。核心在于“三定”：定结构、定行为、定约束。
定结构：统一入口与响应格式
所有控制器必须使用 @RestController，且顶层路径强制带版本号和业务域前缀，例如 @RequestMapping("/api/v1/users")。禁止裸路径如 /users 或无版本路径 /api/users。
全局响应体必须封装为统一结构，包含 code（业务状态码，非仅 HTTP 状态码）、message、data 和 timestamp。不接受裸对象返回（如 return user;）或混合结构（有时返回 {"user":{}}，有时返回 {"data":{}}）。
建议通过 @ControllerAdvice + @ResponseBody 实现全局响应包装，避免每个 Controller 重复写 success/fail 方法。
定行为：HTTP 方法与资源路径严格对齐
URL 只用名词，禁用动词。正确写法：GET /api/v1/orders、POST /api/v1/orders、GET /api/v1/orders/123；错误写法：GET /api/v1/queryOrders、POST /api/v1/createOrder。
操作语义必须匹配 HTTP 方法：
- 查列表或单个资源 → 用 GET
- 新增资源 → 用 POST（返回
201 Created，并带Location头） - 全量更新 → 用 PUT（客户端提供完整资源）
- 局部更新 → 用 PATCH（明确只改部分字段）
- 删除资源 → 用 DELETE
分页、过滤、排序参数一律走 @RequestParam，如 ?page=1&size=20&status=active&sort=createdAt,desc，不塞进路径或请求体。
定约束：通过工具链固化规范
光靠人盯人不可持续，需嵌入开发流程：
- 用 SpringDoc OpenAPI 自动生成接口文档，配合
@Tag、@Operation、@Parameter注解补全语义，禁止手写离线文档 - 在 CI 流程中加入 Swagger Codegen 或 Spectral 校验 OpenAPI 文件是否符合命名、状态码、响应结构等规则
- Controller 方法必须标注明确的 HTTP 状态码语义，例如
@ResponseStatus(HttpStatus.CREATED)或ResponseEntity.status(201).body(...)，禁止默认 200 包打天下 - 所有 DTO 入参必须加 @Valid，并在实体类上声明
@NotBlank、@Min等约束，由框架自动拦截并返回标准错误格式
定边界：明确什么不该做
有些“灵活”做法看似省事，实则埋雷：
- 不允许多个操作共用一个 POST 接口（如
/api/v1/action?op=export），每个资源操作应有唯一、可推导的路径+方法组合 - 禁止在响应中混用不同层级的数据结构（如成功时返回
{"data":{}}，失败时返回{"error":"xxx"}），错误也必须走统一响应体，code设为 4xx/5xx 对应值 - 不推荐用
@PathVariable传复杂查询条件（如/users/{role}/{status}/{fromDate}），这类场景应归入@RequestParam
