接口返回结构，往往是被低估的架构决策。很多人写SpringBoot接口，第一反应是“返回一个Map就行”，或者“直接返回业务对象”，结果到了前端联调、App上线、第三方对接的时候，才发现各种字段对不上、错误码满天飞、异常信息裸奔在JSON里。统一返回结构不是锦上添花，它是API的“契约面”。如果没有一个稳定、可扩展、语义清晰的返回外壳，你的接口越强大，未来重构的代价就越惨烈。
不只是包一层{f:code}那么简单
最常见的做法是定义一个Result<T>类，里面塞上code、message、data三个字段，然后所有Controller方法都返回它。这个思路没错，但陷阱藏在细节里。你的code到底代表什么？是HTTP状态码，还是业务状态码？如果两者混淆，前端就不得不写两套判断逻辑。正确姿势是：HTTP状态码只负责传输层语义（200、400、500），而code字段专门承载业务结果（如1000表示成功，2001表示用户不存在）。这样即使底层网络代理或网关重写了HTTP状态码，你依然能从body里的code精确判读业务成败。
更关键的是，message字段别写成“操作成功”这种废话。它应该是人类可读的、面向调用方的原因描述，甚至可以是错误码对应的文案模板。而data字段，建议永远不要让data为null——成功时返回实际对象，失败时返回null或空对象。前端就可以统一按code判断，不需要对data做空指针防御。这不仅仅是编程习惯，这是为了把“意外”变成“约定”。
泛型不是炫技，是给前端的定心丸
Result<T>的泛型参数，让每个接口都能声明自己返回什么类型的data。比如Result<UserInfo>、Result<List<Order>>。这带来的直接好处是：Swagger/OpenAPI文档可以自动推导出data字段的具体结构，前端能直接生成TypeScript类型定义，联调效率提升一个量级。如果你只写Result不带泛型，或者用Map装数据，那文档基本等于废纸，前端只能靠猜。
实现上要注意，泛型类型在运行时会被擦除，而JSON序列化时，Jackson靠的是方法返回类型的泛型信息。所以如果你的Controller是public Result<User> getUser()，没问题；但如果你把Result塞进一个Object变量再返回，泛型就丢了，序列化后data可能变成一个LinkedHashMap。要规避这个坑，建议Controller层的返回值直接写具体的Result<T>，不要用Object或ResponseEntity<Result>绕一层。实在需要统一包装，可以考虑@RestControllerAdvice配合ResponseBodyAdvice，但那个方案更复杂，后面讲。
状态码设计：别让数字成为玄学
统一返回结构里最容易被吐槽的就是状态码。状态码就是API的“词汇表”，它决定了调用方如何程序化地响应。如果你只有“成功”和“失败”两个码，那遇到“用户未登录”和“库存不足”都是同一个失败码，前端只能通过message字符串去匹配，一旦文案改动，前端就崩了。所以，状态码必须细分到“可编程”的粒度——至少每个业务异常大类一个码，每个常见错误场景一个码。但也不能无限细分，否则维护成本爆炸。
一个比较成熟的做法是定义顶层错误码枚举，加上模块前缀。比如USER_NOT_FOUND对应A-1001，ORDER_EMPTY对应B-2001，用字母区分模块，用数字递增。这样看一眼code就知道是哪个模块出了问题，排查问题时不必在日志里翻来覆去。同时，在枚举里给每个code配上默认message和HTTP状态映射，统一返回时自动填充，避免业务代码里到处写魔法数字和魔法字符串。错误码枚举的getCode()，getMessage()，getHttpStatus()，三者永远一起变，不会出现改了code忘了改文案的尴尬。
异常处理：统一返回结构的灵魂伴侣
Controller里总要有异常抛出来，如果每个方法都try-catch然后封装成Result，代码会变得恶臭无比。利用@RestControllerAdvice配合@ExceptionHandler，把异常到Result的转换集中到一个地方，这是SpringBoot的标配做法。但这里有几个深水区。
第一个是同一种异常在不同接口里可能需要不同的code。比如IllegalArgumentException，在“创建用户”接口里是“参数格式错误”，在“查询订单”接口里可能是“订单号不合法”。如果在全局异常处理器里统一把IllegalArgumentException映射成一个固定code，就会丢失上下文。解决方案是自定义业务异常类，携带code和message，比如BizException(code, message)，业务代码里抛new BizException(UserErrorCode.NOT_FOUND)。然后全局异常处理器只处理BizException，其他异常按照类型兜底。这样每个接口的错误语义由抛出异常的那个位置决定，而不是由全局逻辑一刀切。
第二个是不要直接返回异常的getMessage()给前端。底层数据库异常、网络异常的堆栈信息可能包含敏感内容，而且英文生硬。全局异常处理器必须对未知异常做“脱敏”处理——日志里打印完整堆栈，返回给前端的message使用统一的“服务繁忙，请稍后重试”。对于参数校验异常（MethodArgumentNotValidException），要主动解析FieldError，把字段名和错误信息组合成String，或者干脆返回一个字段错误明细的Map。
第三个是数据校验的失败信息要不要进data？我建议在data里放一个List<FieldErrorVO>，每个元素包含field、rejectedValue、defaultMessage。这样前端可以精确地在表单对应输入框下展示错误，而不是弹一个“校验失败”的toast。这才是统一返回结构的真正价值：不止告诉调用方“错没错”，还要告诉“哪儿错了、怎么改”。
巧妙利用ResponseBodyAdvice省去手动包装
有人觉得每个Controller方法都写return Result.success(data)很繁琐，于是想用ResponseBodyAdvice在响应写出前自动包装。这是可行的，但它是一把双刃剑。实现ResponseBodyAdvice后，所有Handler返回的值都会被拦截，包括文件下载的ResponseEntity<byte[]>，也包括String类型返回值——这是因为String默认用StringHttpMessageConverter，直接return一个包装类会被当字符串处理。另外，接口返回类型已经是Result<T>时，你要跳过包装，否则会嵌套Result<Result<T>>。这些判断逻辑写起来不难，但会让你的代码比显式包装更隐晦，新人接手容易在“为什么这个接口没被包装？”的疑问中抓狂。
我的建议是：项目初期的接口数量少，直接手动返回Result.success(...)最清晰。如果你实在想统一，至少要做到：support()方法里用if (returnType.getGenericParameterType() == Result.class) return false;避开二次包装；同时把String类型单独返回，避免序列化问题。记住，方便的前提是直观，自动化的代价是抽象泄漏。
分页与列表：别把整个List塞进data
很多人的第一个分页接口长这样：Result<List<User>>，然后把total放到message里，或者干脆不做分页返回全部。这是对统一返回结构最经典的滥用。分页信息（total、page、size、hasMore）是业务数据的一部分，它必须结构化地放在data里，而不是藏在字段外。正确的做法是建立一个PageResult<T>内部类，包含list和分页元数据，然后Result<PageResult<T>>。这样就保证了无论前端是无限滚动、表格分页还是移动端加载更多，它的数据结构始终一致。
分页的另一个坑是“总数为什么要count”。当业务复杂时，count查询可能很重，但如果前端要做分页控件，你必须返回total。这时候可以约定：当page和size都为空时，返回全量数据；否则返回分页数据并附带total。但更提倡的是：所有列表接口保持统一的分页参数，比如page从1开始、size默认20，返回结构永远包含items和total。不要搞“特殊接口，特殊处理”，这会让前端的请求层无法抽象。统一的请求约束和统一的响应结构是一体两面，缺一个都不是真正的统一。
文件下载与二进制流：统一结构要懂得“退让”
统一返回结构并非处处适用。下载文件、导出Excel、返回图片这类接口，响应体是二进制流，你没法把JSON塞进去。这时候如果强行返回Result<byte[]>，客户端收到的将是Base64编码的字符串，文件大小膨胀33%，而且没法流式下载。正确的做法：文件下载接口直接返回ResponseEntity<Resource>或void配合HttpServletResponse写出，不套Result。同时，在异常处理时，如果下载过程中出错，你无法修改响应头（可能已经输出了一部分），只能终结输出流。为了避免这种情况，下载前先做所有校验，比如权限、文件存在性，校验失败时直接抛BizException，让全局异常处理器输出JSON错误。一旦开始写文件流，就假设成功，错误只能记录日志。这个“边界意识”是统一返回结构设计里最容易被忽略的实战智慧。
铁律：post与put的返回要有差别
统一返回结构不能脱离HTTP语义。创建资源（POST）成功后，返回Result<Long>，其中data是新资源的ID；更新资源（PUT）成功后，返回Result<Void>，data为null；删除资源（DELETE）成功后，同样返回Result<Void>。如果所有写操作都返回完整对象，前端不得不对比新旧对象来确认操作结果，浪费流量和计算。如果所有操作都返回空，前端又无法获知新资源的ID。在统一外壳之下，data的形态要跟随资源生命周期变化，而不是从一而终。用泛型来传达这些变化：Result<Long>、Result<Void>、Result<OrderDetail>，文档里一目了然。这也是统一返回结构灵活性的体现——外壳固定，内容随场景自适配。
是时候考虑版本兼容了
接口一旦上线，返回结构就是契约。如果你在某个版本里把data从List改成了PageResult，前端的老版本代码会直接崩溃。所以统一返回结构必须从第一天开始就考虑演进方案。常见做法是：在Result里加一个version字段，默认为"1.0"。当后续需要对结构做破坏性变更时，可以同时维护新旧结构，通过请求头或URL路径中的版本标识路由。如果不想维护两套代码，至少保证新增字段时不删除旧字段，并且所有字段都有明确的可选性标注。加字段是兼容的，删字段或改类型不兼容。前端可以依赖code和data，但不应该依赖任何未声明稳定的字段。把这些约定写在接口文档的“版本说明”里，比在代码注释里吼一万遍都有效。
统一返回结构，统一的不只是代码
说到底，统一返回结构是为了统一团队的心智模型。当每个后端开发都能默写出Result.success(data)的构造方式，当前端能闭着眼睛解析出res.code 0的判断分支，当测试能通过code字段一键断言接口是否通过，这套结构才算真正成功。它不应该只是一个类加几个注解，而应该是一个完整的规范：状态码在枚举里集中定义，异常在通知器里统一处理，分页有固定范式，文件下载有明确边界。有了这套规范，新成员写出的接口和老成员一样整齐，跨端联调变成了一次编译通过后的愉快闲聊。反之，如果每个人都自己设计返回壳，那所谓的“统一”只是一场幻觉，最终你会看到前端在data.success、data.result、data.info之间反复横跳，然后崩溃在深夜的群聊里。
一个聊胜于无的补充：如果你的接口要对外开放，比如构成开放平台，那么建议额外遵循错误码文档化、鉴权失败码独立、幂等键返回规范等进阶约定。但那些都是在此基础上叠加的东西。先把这个核心的Result<T>、异常处理器、状态码枚举打磨到极致，你就已经跑赢了绝大多数SpringBoot项目。真正优秀的返回结构，应该让调用方觉得“和我在文档里看到的一模一样”，而不是“怎么又多了个字段”的惊讶。这个标准，值得你用一次重构去实现。
