Spring Boot REST接口需遵循REST规范、统一校验、全局异常处理及标准HTTP状态码。路径用复数资源名和路径变量，禁用动词；参数用@Valid注解校验；异常用@RestControllerAdvice统一处理并返回对应状态码；响应结构应含code、message、data、timestamp，避免重复语义。
Spring Boot 写 REST 接口不难，但真正上线稳定、可维护、不被前端吐槽、不被测试揪出问题的接口，往往卡在几个关键细节上。防坑不是靠背规则，而是把高频出错点变成开发习惯。
HTTP 方法和路径设计别“自创语义”
REST 的核心是资源+标准动词，不是“看着顺眼就行”。很多接口一上来就写 /getUserById 或 /deleteUser?id=123，这已经违背了基本契约。
- 用名词复数表示资源集合：
/users，而不是/user/list - 单个资源用路径变量定位：
/users/101，而不是/users?id=101 - 创建用
POST /users，全量更新用PUT /users/101，部分更新用PATCH /users/101，删除用DELETE /users/101 - 避免在 URL 中暴露业务动作，比如
/users/activate应改为PATCH /users/101并在请求体中传状态字段
参数校验不能只靠“if (xxx == null)”
手动判空既啰嗦又漏判，还无法统一返回格式。Spring Boot 原生支持 JSR-303 校验，该用就得用到位。
- 入参对象加
@Valid，字段加@NotBlank、@Min(1)、@Email等注解 - 分页参数推荐用
Pageable（配合@PageableDefault），不用自己解析pageNum/pageSize - 路径变量也要校验：
@PathVariable @Min(1) Long id，防止负数或零 ID 调用底层逻辑 - 校验失败默认返回 400，但错误信息在响应体里——必须配全局异常处理器才能转成统一结构
异常处理别让 Controller 自己 try-catch
每个接口都写 try-catch，不仅重复，还会掩盖真实异常类型，导致日志混乱、前端无法区分“参数错”还是“服务挂了”。
- 用
@RestControllerAdvice拦住MethodArgumentNotValidException（校验失败）、EntityNotFoundException（查不到）、BusinessException（自定义业务异常）等 - 每种异常对应明确的 HTTP 状态码：400 给参数问题，404 给资源不存在，401/403 给权限问题，500 留给未捕获的系统异常
- 异常响应体必须和正常接口一致（如
ApiResponse），前端才能复用解析逻辑 - 生产环境禁止返回堆栈信息，敏感字段（如数据库表名、类名）要过滤
响应结构和状态码必须“前后端对齐”
后端返回 { "code": 200, "msg": "成功", "data": {...} } 很常见，但容易忽略两点：一是 code 和 HTTP 状态码重复表达，二是没利用好标准状态码的语义。
- 优先用标准 HTTP 状态码传递“成败”信号，JSON 里的
code仅用于细分业务错误（如 1001=余额不足，1002=库存不够） - 创建成功返回
201 Created+Location头；删除成功返回204 No Content（不带 body）；查询为空也应返回200 OK+ 空数组，而非 404 - 统一包装类建议含字段：
code（业务码）、message（用户提示）、data（泛型）、timestamp（便于排查） - 不要为“成功”硬凑 code=0，也不要为“失败”统一返回 500 —— 状态码本身就是契约的一部分
