Spring Boot统一封装REST接口返回的核心是定义标准响应体Result类并配合@RestControllerAdvice自动包装。通过泛型Result封装code、message、data，结合ResponseBodyAdvice实现无感封装，再用@ExceptionHandler统一处理异常，确保所有接口响应结构一致、语义清晰、可扩展。
Spring Boot 中统一封装 REST 接口返回，核心是让所有接口输出结构一致、语义清晰、可扩展，同时避免每个 Controller 方法手动包装。不靠“写一堆 if-else”，而是用约定 + 框架机制自动完成。
定义标准响应体 Result
这是封装的基石。一个干净、泛型化的类即可覆盖绝大多数场景：
- code：业务状态码（如 200 成功、400 参数错误、500 系统异常），建议用枚举管理，避免硬编码
- message：对前端友好的提示信息，非技术堆栈，比如“用户名已存在”而非“DuplicateKeyException”
- data：实际业务数据，支持任意类型（String、List、DTO 等），失败时为 null
- 可选添加 timestamp 或 requestId，便于日志追踪和前端调试
配合 Lombok 的 @Data 和静态工厂方法（success() / fail()），调用简洁直观。
用 @RestControllerAdvice 实现无感封装
这是最关键的一步——让 Controller 回归“只管业务逻辑”的本职。无需修改任何已有接口代码，只需一个全局增强器：
sc-java-to-ts-interface
下载
将后端 Java 接口文档转换为前端 TypeScript 类型定义（interface / type）。输入：飞书文档、Spring Boot 接口文档、Swagger/OpenAPI、手写 API 文档等。输出：包含请求参数与响应结果的 .md 文件，含完整 JSDoc 注释。触发关键词：Java 转 TS、接口转换、生成前端类型、接口文档转 TypeScript、DTO/VO/BO 转 interface、后端文档转前端类型、生成接口类型、类型定义生成。
- 实现
ResponseBodyAdvice<object></object>接口，重写beforeBodyWrite - 判断返回值是否已是
Result类型，是则放行；否则自动包装成Result.success(body) - 搭配
@Order(Ordered.HIGHEST_PRECEDENCE)确保它在其他转换器前生效
这样，原本写 @GetMapping("/user") public User getUser() { return new User(); } 就能自动变成 {"code":200,"message":"success","data":{...}}。
统一处理异常，保持响应结构一致
接口正常流程有了封装，异常路径也必须走同一套结构，否则前端又要写两套解析逻辑：
- 自定义异常类（如
BusinessException），构造时传入状态码枚举和提示消息 - 在
@RestControllerAdvice中用@ExceptionHandler捕获所有异常 - 对
BusinessException返回Result.fail(code, msg)；对未预期异常（如 NPE）返回通用错误码（如 500）并记录日志 - 连 HTTP 状态码（404、400）也可通过
ResponseEntity统一转为业务格式，避免暴露 Tomcat 默认页
注意 DTO 层的数据可序列化性
再规范的封装，若返回对象本身 Jackson 无法序列化，也会直接报错：
- 禁止将接口（interface）或抽象类直接作为
Result<t></t>的泛型 T 返回，Jackson 不知道实例化哪个实现 - DTO 类必须有无参构造器、public getter/setter，字段不能是 private final（除非加
@JsonCreator） - 复杂嵌套结构（如含泛型集合、时间类型）建议显式配置 Jackson 序列化器，或使用
@JsonFormat注解
封装不是加一层壳就完事，它要贯穿 Controller → Service → DTO 全链路的一致性设计。
