Spring Boot实战：RESTful API接口规范与统一异常处理

Spring Boot 是后端接口开发使用最广泛的框架，但框架只是把接口做出来，规范决定接口好不好用。API 接口规范约束 URL 设计、状态码、响应体、错误信息，直接影响前后端联调效率和系统可维护性。本文用 Spring Boot 3 演示一套可复用的接口规范实现。

RESTful API 接口规范：URL 与状态码设计

URL 按资源命名，使用复数名词，不用动词描述动作。查询用 GET、创建用 POST、整体更新用 PUT、删除用 DELETE，语义各司其职。状态码同样要对齐：2xx 成功，4xx 客户端错误，5xx 服务端错误。

GET    /api/v1/users           # 用户列表
GET    /api/v1/users/42        # 查询单个用户
POST   /api/v1/users           # 创建用户
PUT    /api/v1/users/42        # 整体更新
DELETE /api/v1/users/42        # 删除用户

路径用单数还是复数团队内统一即可，重点是不混用；查询参数只做筛选排序分页，不做动词语义。

统一响应体与业务错误码设计

统一响应体让前端处理逻辑收敛，错误码比裸状态码携带更多业务信息。约定所有接口返回结构：code 为业务错误码，0 表示成功，非 0 按模块分段。

public record Result<T>(int code, String message, T data) {
    public static <T> Result<T> ok(T data) {
        return new Result<T>(0, "ok", data);
    }
    public static <T> Result<T> error(int code, String msg) {
        return new Result<T>(code, msg, null);
    }
}

全局异常处理：@RestControllerAdvice 实战

业务代码里到处 try-catch 会污染主流程，改用全局异常处理器统一拦截。业务异常、参数校验异常、兜底异常分别处理，返回对应的错误码与提示。

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BizException.class)
    public Result<Void> handleBiz(BizException e) {
        return Result.error(e.getCode(), e.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
            .map(f -> f.getField() + ": " + f.getDefaultMessage())
            .collect(Collectors.joining("; "));
        return Result.error(40001, msg);
    }

    @ExceptionHandler(Exception.class)
    public Result<Void> handleOther(Exception e) {
        log.error("未处理异常", e);
        return Result.error(50000, "服务内部错误");
    }
}

参数校验注解（@Validated + @NotBlank 等）配合全局异常，把校验逻辑全部声明化，代码更短也更清晰。

接口版本控制与 OpenAPI 文档

接口持续演进而客户端不会同步升级，版本控制是必须的。常用做法是 URL 路径带主版本号 /api/v1、/api/v2，破坏性变更升大版本，向后兼容的小改动只加字段。文档用 springdoc-openapi 自动生成 OpenAPI 描述，前端直接导入生成客户端代码，接口变更一处落地，文档同步更新，避免”代码改了文档忘了”的经典问题。