生产级 Spring Boot API —— 第3部分：一致的响应与全局异常处理

Source: Dev.to

为什么在微服务中 API 响应的一致性很重要

• API 必须在各个服务之间保持相同的外观。
• 错误必须是可预测的。
• 客户端不应猜测响应格式。

如果缺乏规范，最终会出现：

• 每个端点的响应格式不统一
• 错误信息不明确
• 控制器里充斥着 try‑catch 块

设计通用的 BaseResponse

通用包装类可以让成功和错误的负载统一化。

public class BaseResponse<T> {
    private int status;
    private String message;
    private T data;

    // getters, setters, builder, etc.
}

API 响应中的 Builder 模式

使用 Builder 可以让响应 可读、安全、可扩展、统一。

BaseResponse<String> response = BaseResponse.builder()
        .status(200)
        .message("Success")
        .data("Hello")
        .build();

好处

• 统一的成功响应
• 统一的错误响应
• API 演进更容易

ResponseEntity 与真实的 HTTP 语义

ResponseEntity 代表 完整的 HTTP 响应：

• 状态码
• 头部信息
• 主体

API 应该使用正确的 HTTP 语义进行通信，而不仅仅是返回 JSON。

使用 @RestControllerAdvice 进行全局异常处理

将错误处理集中化可以保持控制器的简洁，并让服务层抛出领域特定的异常。

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<BaseResponse<?>> handleNotFound(ResourceNotFoundException ex) {
        BaseResponse<?> body = BaseResponse.builder()
                .status(HttpStatus.NOT_FOUND.value())
                .message(ex.getMessage())
                .build();
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
    }

    // other exception handlers …
}

• 控制器保持干净。
• 服务层抛出领域异常。
• 错误统一由中心处理。
• 响应格式统一，代码零重复。

结论

上述结构正是我们在实际 Spring Boot 微服务中使用的：

• 清晰的层次结构
• 明确的依赖关系
• 一致的 API
• 面试时可辩护的设计

生产级的 Spring Boot 更多的是关于纪律和结构，而不是单纯的注解。本文为 生产级 Spring Boot API 设计 系列画上句号，基于真实项目经验和个人笔记的提炼。