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

前言

在过去的一年里，我参与了多个基于 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 设计应该在项目初期就确定好规范，避免后期返工。希望对你有所帮助。