作者：不想打工的码农
标签：#SpringBoot #Java #后端开发 #RESTful #工程实践
上周五下班前，组长 review 我的代码，指着满屏的 return Result.success(data) 说：
“你这接口返回格式是统一了，但……能不能别每个方法都写一遍？”
我嘴上说“好的”，心里嘀咕：“不这么写，前端拿不到统一结构啊。”
结果第二天，他甩给我一段代码——用 ResponseBodyAdvice 全局包装返回值。
我跑通后，当场删掉了项目里 200 多行重复的 Result.success()。
今天就把这个真正优雅的统一返回方案分享出来，全程无魔法，只有 Spring 原生能力。
一、先说说我们是怎么“作茧自缚”的
早期为了和前端约定好数据格式，我们定义了 Result 类：
public class Result<T> {
private int code = 200;
private String msg = "success";
private T data;
public static <T> Result<T> ok(T data) {
return new Result<>(data);
}
}
然后每个 Controller 都长这样：
@GetMapping("/user/{id}")
public Result<User> getUser(@PathVariable Long id) {
User user = userService.findById(id);
return Result.ok(user); // ← 这行写了几百遍
}
表面看没问题，实际很痛苦：
- 每个方法都要手动调用
Result.ok() - 如果哪天要加个字段（比如
timestamp），得改所有接口 - 异常走全局处理返回
Result.error()，正常流程却要手动包装，逻辑割裂
更惨的是，有次实习生忘了包 Result，直接 return user，前端直接报错——因为拿到的是 {name: "张三"} 而不是 {code:200, data: {name: "张三"}}。
二、尝试过 @ControllerAdvice？它不管正常返回！
有人会说：“用 @ControllerAdvice 啊！”
但请注意：@ControllerAdvice 只能处理异常（通过 @ExceptionHandler），对正常的 return 对象无能为力。
也就是说，它能让你的 500 错误变成 Result.error("系统忙")，但不能把 return user 自动变成 Result.ok(user)。
那怎么办？
答案是：ResponseBodyAdvice —— Spring 提供的一个被严重低估的扩展点。
三、正确姿势：用 ResponseBodyAdvice 全局包装
第一步：实现 ResponseBodyAdvice 接口
import org.springframework.core.MethodParameter;
import org.springframework.http.MediaType;
import org.springframework.http.server.ServerHttpRequest;
import org.springframework.http.server.ServerHttpResponse;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {
@Override
public boolean supports(MethodParameter returnType, Class converterType) {
// 只处理返回值不是 Result 类型的方法（避免重复包装）
return !Result.class.isAssignableFrom(returnType.getParameterType());
}
@Override
public Object beforeBodyWrite(Object body,
MethodParameter returnType,
MediaType selectedContentType,
Class selectedConverterType,
ServerHttpRequest request,
ServerHttpResponse response) {
// 如果返回 null，也包装成 Result（避免前端收到 null）
if (body == null) {
return Result.ok(null);
}
// 直接包装原始返回值
return Result.ok(body);
}
}
第二步：Controller 回归清爽
现在你的接口可以这样写：
@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id) {
return userService.findById(id); // ← 直接返回业务对象！
}
@PostMapping("/user")
public User createUser(@Valid @RequestBody UserCreateDTO dto) {
return userService.create(dto); // ← 不用手动套 Result
}
效果：
无论你返回 User、List<Order> 还是 String，最终 JSON 都会自动变成：
{
"code": 200,
"msg": "success",
"data": { ... } // 你的原始返回值
}
第三步：兼容已有 Result 返回（防翻车）
注意 supports() 方法里的判断：
return !Result.class.isAssignableFrom(returnType.getParameterType());
这意味着：如果你某个接口已经手动返回了 Result，它不会被二次包装。
所以老代码不用改，新代码直接简化，平滑过渡。
四、踩过的坑 & 注意事项
⚠️ 坑1：不要包装 ResponseEntity
有些接口需要自定义 HTTP 状态码（比如 201 Created）：
@PostMapping("/user")
public ResponseEntity<User> createUser(...) {
User user = userService.create(dto);
return ResponseEntity.status(201).body(user);
}
上面的 supports() 方法没排除 ResponseEntity，会导致它被错误包装。
✅ 修复：在 supports() 中加判断：
Class<?> returnTypeClass = returnType.getParameterType();
return !Result.class.isAssignableFrom(returnTypeClass)
&& !ResponseEntity.class.isAssignableFrom(returnTypeClass);
⚠️ 坑2：void 方法返回 null
如果接口是 public void delete(@PathVariable Long id)，body 会是 null。
我们的 beforeBodyWrite 已经处理了这种情况，返回 Result.ok(null)，前端可识别。
⚠️ 坑3：文件下载等二进制响应会被破坏
ResponseBodyAdvice 会对所有 @RestController 生效，包括返回 byte[] 或 InputStreamResource 的文件下载接口。
✅ 解决方案：
- 文件下载接口单独用
@Controller（不带@ResponseBody语义） - 或在
supports()中排除特定路径（如/download/**）
五、为什么这个方案更“工程化”？
表格
| 方案 | 优点 | 缺点 |
|---|---|---|
手动 Result.success() | 简单直观 | 重复代码多，易遗漏 |
| AOP 切面包装 | 灵活 | 复杂，可能影响性能 |
| ResponseBodyAdvice | 无侵入、原生支持、精准控制 | 需理解 Spring 扩展机制 |
核心价值：
- 业务代码只关注“做什么”，不关心“怎么返回”
- 前端永远拿到一致的数据结构
- 后期调整返回格式（比如加 traceId），只需改一处
六、结语
刚工作时，我觉得“能跑就行”。
现在才明白：好的工程，是让后续的每一行代码都更容易写、更不容易错。
ResponseBodyAdvice 不是什么新技术，但它解决了一个被无数人忍受的“小麻烦”。
下次当你看到满屏的 return Result.ok(...)，不妨试试这个方案。
删掉那 200 行重复代码的感觉，真的爽。
我是「不想打工的码农」，一个正在用 Spring 原生能力打磨 SaaS 产品的独立开发者。
如果你觉得有收获，欢迎点赞、收藏、关注！
