Spring Boot 中正确返回嵌套 JSON 结构的实践方法

本文详解如何在 spring boot 中规范返回符合 `{ "code": "...", "msg": "...", "data": { "data": [...] } }` 嵌套格式的 json 响应，避免因 map 直接嵌套导致结构错位，并推荐使用类型安全的 pojo 方式替代动态 map 构建。

在 Spring Boot 中，@ResponseBody 默认借助 Jackson 将返回对象序列化为 JSON。但直接使用 Map 容易引发结构歧义——如原代码中 map.put("data", info.getList()) 会将列表直接赋给顶层 "data" 字段，导致输出为 "data": []，而非期望的 "data": { "data": [] }。根本原因在于：JSON 对象（Object）与数组（Array）语义不同，而 Map 的 value 是扁平化的，无法天然表达“data 字段下再嵌套一个 data 字段”的层级关系。

要精准生成目标结构，推荐采用 强类型 POJO 封装，而非动态 Map 拼接。以下是完整实现方案：

✅ 正确做法：定义分层响应实体类

首先创建统一响应结构类（推荐泛型化以提升复用性）：

public class ApiResponse {
    private String code;
    private String msg;
    private DataWrapper data; // 关键：用独立类封装内层 "data" 对象

    public static  ApiResponse success(T data) {
        ApiResponse res = new ApiResponse<>();
        res.code = "200";
        res.msg = "success";
        res.data = new DataWrapper<>(data);
        return res;
    }

    // getter / setter 省略，或使用 Lombok @Data
}

// 专门承载内层 { "data": [...] } 的包装类
public class DataWrapper {
    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> getPropertyList(
            @RequestParam(defaultValue = "1") int pageNumber,
            @RequestParam(defaultValue = "5") int pageSize) {

        PageHelper.startPage(pageNumber, pageSize, true);
        List propertyList = propertyService.queryList();
        PageInfo 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" }
    ]
  }
}

这不仅解决了当前嵌套结构问题，更为后续接口标准化、前端解耦和团队协作奠定了坚实基础。