Spring Boot 5.3 RESTful API 必须遵循规范：使用 @RestController、统一 /api/v1 前缀、资源路径无动词、嵌套≤两层、GET/POST 按参数复杂度选择、统一 ApiResponse 封装、@Valid 校验+全局异常处理。
要在 Spring Boot 5.3 中快速搭建符合行业标准的 RESTful API，必须从控制器定义、URL 结构、HTTP 方法映射到响应格式全程遵循规范，避免因动词混入路径或状态码误用导致前端联调反复失败。
定义资源型控制器
使用 @RestController 替代 @Controller + @ResponseBody 组合，这是 Spring Boot 5.3 的默认推荐方式，省去手动标注响应体序列化的冗余操作。
在类级别添加 @RequestMapping("/api/v1")，为所有接口统一前缀，版本号必须显式声明，【不建议将版本放在请求头中】，否则 Swagger 文档无法自动识别且 Nginx 路由配置复杂化。
控制器类名以 Controller 结尾，例如 UserController，不要写成 UserAPI 或 UserHandler。
URL 路径与 HTTP 方法精准匹配
按操作类型严格选用注解：查询集合用 @GetMapping("/users")，查单个用 @GetMapping("/users/{id}")，新增用 @PostMapping("/users")，全量更新用 @PutMapping("/users/{id}")，部分更新用 @PatchMapping("/users/{id}")，删除用 @DeleteMapping("/users/{id}")。
路径中禁止出现动词：/getUserById → 必须改为 /users/{id}；/searchOrdersByStatus → 必须改为 /orders?status=xxx。
嵌套资源最多两层：/departments/{deptId}/employees 是可接受的，但 /departments/{deptId}/teams/{teamId}/members 不符合 Spring Boot 5.3 官方推荐实践，应拆分为独立端点或改用查询参数。
查询接口的 GET 与 POST 决策
方法一：简单条件走 GET
当参数全部为字符串、数字、日期（≤8 个），且无嵌套结构时，强制使用 GET。例如：@GetMapping("/products") 接收 @RequestParam String name, @RequestParam LocalDate startDate。
方法二：复杂条件必须用 POST
只要 DTO 中含 List、Map、嵌套对象（如 PriceRange）、或字段数 ≥9，就必须改用 @PostMapping("/products/search") 并接收 @RequestBody ProductSearchDTO。GET 的 URL 长度限制在 Spring Boot 5.3 默认嵌入 Tomcat 下为 2048 字符，超长会直接返回 400 错误且无日志提示。
统一响应结构实现
第一步：创建泛型响应类 ApiResponse<T>，包含 code、message、data、timestamp 四个字段，构造器私有，仅暴露 success() 和 fail() 静态工厂方法。
第二步：在 Controller 方法返回值统一包装为 ApiResponse<User>，而非裸返回 User 或 Page<User>。Spring Boot 5.3 的 ResponseEntity 已不推荐用于业务响应封装，它更适合控制 HTTP 状态码和 Header 的底层场景。
第三步：用 @ControllerAdvice + @ResponseBodyAdvice 拦截所有返回值，自动套用 ApiResponse 包装，避免每个方法手写 ApiResponse.success(user)。
参数校验与错误响应
在 DTO 字段上标注 @NotBlank、@NotNull、@Min(1) 等 javax.validation 注解，Controller 方法参数前加 @Valid。
全局异常处理器捕获 MethodArgumentNotValidException，提取 BindingResult 中第一个错误字段，组装成 ApiResponse.fail(400, "用户名不能为空") 并返回 400 状态码。
注意：@Validated 与 @Valid 在 Spring Boot 5.3 中行为一致，但 【分组校验必须用 @Validated】，否则分组失效。
