Web 接口契约

要解决什么问题

多人协作的 Spring Web 项目里，接口层最容易出现「动词用错、响应形状不一、Controller 里吞异常」三类问题：前端难以统一解析，联调时要对照每个方法的返回结构，排错时日志与 HTTP 状态也对不齐。本技能把团队里已经形成的接口约定写成可执行的写作规则，让新生成的 Controller 代码默认贴合同一套契约。

技能如何约束实现

• 路由与注解：使用 @RestController 与 @RequestMapping 组织接口；HTTP 方法语义需准确——GET 查询、POST 新增或复杂查询、PUT 全量修改、DELETE 删除。
• 统一响应：所有接口返回包装类 HttpResult，字段为 code（int）、msg（String）、data（T）；成功与失败应调用 HttpResult 实体中已有的对应方法，而不是临时拼 Map 或自定义 DTO。
• 异常路径：禁止在 Controller 内 try-catch；业务与校验异常向上抛出，由 @RestControllerAdvice 全局处理器捕获并转换为对外输出。
• 日志：若项目中既有 Controller 已用 @Log 标记日志，新接口应沿用相同方式；若项目从未使用该注解，则不要凭空引入。

适用边界

本技能针对 Spring MVC / Spring Boot 风格 的后端接口，不覆盖 GraphQL、gRPC 或其它框架的契约。HttpResult 的具体类名与成功/失败 API 以你仓库中的实体为准，技能不会替你发明新的错误码体系；全局异常处理器的包名与切面范围需与现有工程一致。