本文详解如何在 spring boot 中规范返回符合 `{ "code": "...", "msg": "...", "data": { "data": [...] } }` 嵌套格式的 json 响应，避免因 map 直接嵌套导致结构错位，并推荐使用类型安全的 pojo 方式替代动态 map 构建。
在 Spring Boot 中，@ResponseBody 默认借助 Jackson 将返回对象序列化为 JSON。但直接使用 Map
要精准生成目标结构，推荐采用 强类型 POJO 封装，而非动态 Map 拼接。以下是完整实现方案：
✅ 正确做法：定义分层响应实体类
首先创建统一响应结构类（推荐泛型化以提升复用性）：
HISUI 前端框架基础开发指南。HISUI 是基于 easyui 二次开发的 jQuery UI 组件库，专为医疗信息系统设计。当涉及 HISUI 组件开发、jQuery easyui 表格/表单/布局/窗口、医疗系统前端页面编写时使用此 skill。 涵盖 40 个组件的官方文档参考，支持声明式与编程式两种初始化方式，提供 $cm/$m 数据访问方法。
public class ApiResponse<T> {
private String code;
private String msg;
private DataWrapper<T> data; // 关键：用独立类封装内层 "data" 对象
public static <T> ApiResponse<T> success(T data) {
ApiResponse<T> res = new ApiResponse<>();
res.code = "200";
res.msg = "success";
res.data = new DataWrapper<>(data);
return res;
}
// getter / setter 省略，或使用 Lombok @Data
}
// 专门承载内层 { "data": [...] } 的包装类
public class DataWrapper<T> {
private T data;
public DataWrapper(T data) {
this.data = data;
}
// getter / setter
public T getData() { return data; }
public void setData(T data) { this.data = data; }
}✅ Controller 层改造（简洁、类型安全）
@RestController // 替代 @Controller + @ResponseBody
@RequestMapping("/index/property")
public class PropertyController {
@Autowired
private PropertyService propertyService;
@GetMapping("/list") // 使用语义更清晰的注解
public ApiResponse<List<Property>> getPropertyList(
@RequestParam(defaultValue = "1") int pageNumber,
@RequestParam(defaultValue = "5") int pageSize) {
PageHelper.startPage(pageNumber, pageSize, true);
List<Property> propertyList = propertyService.queryList();
PageInfo<Property> pageInfo = new PageInfo<>(propertyList);
return ApiResponse.success(pageInfo.getList());
}
}? 提示：@RestController = @Controller + @ResponseBody，语义更明确；@GetMapping 是 @RequestMapping(method = GET) 的快捷写法，增强可读性。
⚠️ 注意事项与最佳实践
-
避免 Map 链式拼装：Map
虽灵活，但易出错、不可校验、缺乏 IDE 支持，仅适合极简原型； -
统一响应结构：生产环境建议全局定义 ApiResponse
，配合全局异常处理器（@ControllerAdvice）统一处理错误码与消息； - Jackson 序列化控制：若需忽略空字段，可在类上加 @JsonInclude(JsonInclude.Include.NON_NULL)；
- 性能考量：POJO 方式比反射构建 Map 更高效，且利于 JVM JIT 优化。
通过上述方式，最终返回的 JSON 将严格符合预期格式：
{
"code": "200",
"msg": "success",
"data": {
"data": [
{ "id": 1, "name": "A" },
{ "id": 2, "name": "B" }
]
}
}这不仅解决了当前嵌套结构问题，更为后续接口标准化、前端解耦和团队协作奠定了坚实基础。
