使用 Spring Boot 构建 RESTful API 的最佳实践

Mon, 15 Jun 2026 00:00:00 GMT

前言

在过去的一年里，我参与了多个基于 Spring Boot 的后端项目开发，逐渐积累了一些关于 RESTful API 设计的经验。本文总结了一些我认为比较重要的实践。

1. 统一响应格式

无论是在开发还是调试阶段，一个统一的响应格式都能大大降低沟通成本。我习惯使用如下结构：

{
  "code": 200,
  "message": "success",
  "data": {}
}

对应 Java 实现：

@Data
public class ApiResponse<T> {
    private Integer code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> success(T data) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(200);
        response.setMessage("success");
        response.setData(data);
        return response;
    }

    public static <T> ApiResponse<T> error(Integer code, String message) {
        ApiResponse<T> response = new ApiResponse<>();
        response.setCode(code);
        response.setMessage(message);
        return response;
    }
}

2. 全局异常处理

借助 @RestControllerAdvice 和 @ExceptionHandler，可以优雅地集中处理异常：

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<?> handleValidation(MethodArgumentNotValidException ex) {
        String msg = ex.getBindingResult().getFieldErrors()
            .stream()
            .map(e -> e.getField() + ": " + e.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return ApiResponse.error(400, msg);
    }

    @ExceptionHandler(Exception.class)
    public ApiResponse<?> handleException(Exception ex) {
        return ApiResponse.error(500, "服务器内部错误");
    }
}

3. 参数校验

Spring Boot 内置了 Bean Validation，配合 @Valid 注解可以很方便地做参数校验：

@RestController
@RequestMapping("/api/users")
public class UserController {

    @PostMapping
    public ApiResponse<User> create(@Valid @RequestBody CreateUserRequest request) {
        // 业务逻辑
    }
}

4. API 版本管理

推荐将版本号放在 URL 路径中：

/api/v1/users
/api/v2/users

这样在需要不兼容升级时，可以平滑过渡。

总结

以上就是我在实际项目中使用 Spring Boot 构建 RESTful API 时的一些实践。好的 API 设计应该在项目初期就确定好规范，避免后期返工。希望对你有所帮助。

SHEN LI

使用 Spring Boot 构建 RESTful API 的最佳实践

前言

1. 统一响应格式

2. 全局异常处理

3. 参数校验

4. API 版本管理

总结