在Spring Boot中通过自定义@ResponseResult注解结合ResponseBodyAdvice实现按需统一封装API响应：标记方法启用封装，非标记方法（如文件下载）不受影响，返回值自动包装为标准Result对象。
在 Spring Boot 项目中，通过自定义注解实现控制层统一包装标准 API 响应格式，核心思路是：**用注解标记需要统一封装的接口，再结合 ResponseBodyAdvice 拦截并自动包装返回值**。这种方式既保留了开发灵活性（按需启用），又避免了全局强制封装带来的副作用（比如文件下载、流式响应等场景）。
定义标准响应类 Result
这是所有封装的基础。建议包含状态码、提示消息、业务数据、时间戳等字段，并提供静态工厂方法：
- code：业务状态码（如 200、400、500），推荐用枚举管理
- message：可读提示，区分于 HTTP 状态码
- data：泛型字段，支持任意类型返回值
- timestamp：便于日志追踪和前端缓存判断
示例：
public class Result
private Integer code;
private String message;
private T data;
private Long timestamp = System.currentTimeMillis();
// 构造方法与 success/fail 静态方法略
}
创建自定义注解 @ResponseResult
这个注解用于显式声明哪些 Controller 方法需要被统一封装。它本身不带逻辑，只起标记作用：
立即学习“Java免费学习笔记（深入）”；
- 使用
@Target(ElementType.METHOD)，限定只能加在方法上 - 使用
@Retention(RetentionPolicy.RUNTIME)，确保运行时可反射获取 - 可选添加
@Documented和@Inherited
示例：
@Target(ElementType.METHOD)@Retention(RetentionPolicy.RUNTIME)
public @interface ResponseResult {
boolean value() default true;
}
编写 ResponseBodyAdvice 实现类
这是真正执行封装逻辑的地方。关键在于重写 supports() 方法——只对标注了 @ResponseResult 的方法返回 true：
- 通过
methodParameter.getMethod().isAnnotationPresent(ResponseResult.class)判断是否标记 - 在
beforeBodyWrite()中，若返回值已是Result类型则跳过；否则用Result.success(body)包装 - 注意处理
null、String、void等边界情况（如 String 需转 JSON 字符串再包装）
示例逻辑片段：
if (body instanceof Result) {return body;
}
if (body == null) {
return Result.success(null);
}
return Result.success(body);
在 Controller 中使用注解
只需在目标方法上加 @ResponseResult 即可，返回值保持原始类型不变：
- 返回
List<user></user>→ 自动变成Result<list>></list> - 返回
User→ 自动变成Result<user></user> - 不加该注解的方法（如文件下载接口、Swagger 接口）完全不受影响
示例：
@GetMapping("/user/{id}")@ResponseResult
public User getUserById(@PathVariable Long id) {
return userService.findById(id);
}
这样既满足了标准化要求，又保留了对特殊接口的控制权，不复杂但容易忽略细节。
