一、为什么要统一

在真实项目开发中，你是否遇到过这些问题？

• 前端需要为不同接口编写差异化处理逻辑
• 错误信息格式五花八门，定位问题困难
• 全局异常处理缺失导致敏感信息泄露

在前后端分离架构中，统一的 API 响应格式是提升协作效率的关键。本文将手把手教你用 SpringBoot 实现标准化响应封装，从此告别接口格式混乱的烦恼！

二、统一响应格式的价值

1. 标准化：所有接口遵循相同数据结构
2. 可维护性：集中处理异常和成功响应
3. 安全性：隐藏技术细节，暴露友好提示
4. 可扩展性：轻松添加统一字段（如 traceId ）

三、结果要求

1、正常情况下，API 的相应结果是统一格式的

2、API 开发人员的 controller 方法的返回值依旧可以是原生的类型，比如 List、或者其他自定义类等，不需要 API 开发人员手动的将结果构造成统一格式，而是由底层框架统一格式化。

3、有些特殊接口需要忽略统一格式化。比如下载接口，或者是和第三方对接，需要满足第三方的自定义报文格式。

4、具有全局异常处理。如果有异常，代码中直接 throw new Exception("消息提示")，API 统一将提示信息返回，不需要给业务方法的正常响应对象再包一层结果信息。

四、设计标准化响应体

基础响应结构示例：

{
  code : "200",
  msg : "操作成功",
  data : null,
  timestamp : 1759321000000
  extra : {}
}

字段说明：

字段	类型	说明
code	String	业务状态码（非HTTP状态码）
msg	String	提示信息
data	Object	业务数据（可为null）
timestamp	Long	响应时间戳

五、实现步骤