在 spring boot 中，可通过自定义封装类统一返回多种类型数据（如 list 和 object），避免多次请求，提升接口设计的简洁性与前端调用效率。
在 spring boot 中，可通过自定义封装类统一返回多种类型数据（如 list 和 object），避免多次请求，提升接口设计的简洁性与前端调用效率。
在实际开发中，常遇到一个业务场景：根据 ID 查询订单详情的同时，还需关联获取多个快递信息（如历史配送记录）。此时若强行拆分为两个独立接口（如 /order/{id} 和 /couriers/{id}），不仅增加前端调用复杂度，还可能引发并发、时序或数据一致性问题。更优雅的方案是——将异构数据统一聚合到一个响应体中，通过单个 RESTful 接口返回。
✅ 正确实现方式：定义响应封装类
首先，创建一个 POJO 类（例如 SearchResponse），用于承载所有需返回的数据字段。注意：由于问题中提到需返回 List
public class SearchResponse {
private OrderRelatedInfo order;
private List<courier> couriers;
// 全参构造（便于 ResponseEntity 构建）
public SearchResponse(OrderRelatedInfo order, List<courier> couriers) {
this.order = order;
this.couriers = couriers;
}
// 必备：无参构造（Jackson 序列化所需）
public SearchResponse() {}
// Getter & Setter（Lombok 可简化为 @Data）
public OrderRelatedInfo getOrder() { return order; }
public void setOrder(OrderRelatedInfo order) { this.order = order; }
public List<courier> getCouriers() { return couriers; }
public void setCouriers(List<courier> couriers) { this.couriers = couriers; }
}</courier></courier></courier></courier>
✅ 控制器层：使用 ResponseEntity 返回
在 Controller 方法中，构造并返回该封装对象。推荐显式使用 ResponseEntity.ok()，既语义清晰，又便于后续扩展状态码或响应头：
@GetMapping("/search/{id}")
public ResponseEntity<searchresponse> search(@PathVariable String id) {
// 模拟业务逻辑：查询订单与快递列表
OrderRelatedInfo order = orderService.findById(id);
List<courier> couriers = courierService.findByOrderId(id);
// 封装并返回
SearchResponse response = new SearchResponse(order, couriers);
return ResponseEntity.ok(response);
}</courier></searchresponse>
? 提示：无需额外添加 @ResponseBody（Spring Boot 2.6+ 默认启用），且方法返回类型建议明确为 ResponseEntity
，而非泛型模糊的 ResponseBody<...>（该写法在 Spring 中并不存在，属原文笔误）。
⚠️ 注意事项与最佳实践
- 命名规范：避免使用 Output 或 Result 等泛化后缀，推荐采用语义化名称如 SearchResponse，体现接口用途；
- 空值安全：若某字段可能为空（如未查到订单），建议在封装前做判空处理，或使用 Optional + 自定义序列化策略；
- 性能考量：确保 courierService.findByOrderId(id) 是高效查询（如走索引），避免 N+1 查询问题；
- 前端兼容性：JSON 响应结构清晰，前端可直接解构：response.order.id、response.couriers[0].trackingNo；
- 扩展性预留：后续如需增加“物流轨迹”或“支付信息”，只需在 SearchResponse 中新增字段，保持接口契约稳定。
通过这种封装模式，你不仅实现了单一接口承载多维业务数据的目标，更践行了 REST API 设计中「资源聚合」与「客户端友好」的核心原则。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
