Spring Boot中不同2xx成功响应码的差异化响应结构实现

一、是否允许？ #

完全允许。HTTP协议和RESTful架构的核心原则之一就是用状态码标识请求结果的语义，不同状态码对应不同业务场景，自然可以搭配不同的响应结构：

• 比如200 OK通常用于单资源查询成功，响应结构可以是单个资源对象；
• 207 Multi-Status用于批量操作（如批量更新多个资源），响应结构需要包含每个操作的状态和结果，和200的结构必然不同。
  只要每个状态码对应的响应结构在API文档中明确说明，符合“自描述性”的REST要求，就完全合规。

二、Spring Boot中的实现方式 #

1. 直接返回不同类型响应对象+@ResponseStatus #

在Controller方法中，根据业务逻辑返回不同对象，通过@ResponseStatus指定对应状态码：

@RestController
@RequestMapping("/api/resources")
public class ResourceController {

    // 200 OK 返回单个资源对象
    @GetMapping("/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Resource getResource(@PathVariable Long id) {
        // 业务逻辑：查询单个资源
        return new Resource(id, "示例资源", "详细描述");
    }

    // 207 Multi-Status 返回批量操作结果
    @PostMapping("/batch")
    @ResponseStatus(HttpStatus.MULTI_STATUS)
    public BatchOperationResult batchUpdate(@RequestBody List<ResourceUpdateRequest> requests) {
        BatchOperationResult result = new BatchOperationResult();
        // 业务逻辑：处理批量更新，记录每个操作的状态
        for (ResourceUpdateRequest req : requests) {
            result.addResult(req.getId(), HttpStatus.OK.value(), "更新成功");
            // 模拟部分失败的情况
            if (req.getId() % 2 == 0) {
                result.addResult(req.getId(), HttpStatus.BAD_REQUEST.value(), "参数错误");
            }
        }
        return result;
    }
}

// 单个资源的响应结构
class Resource {
    private Long id;
    private String name;
    private String description;
    // 构造器、getter/setter
}

// 批量操作的响应结构
class BatchOperationResult {
    private List<SingleOperationResult> results = new ArrayList<>();

    public void addResult(Long resourceId, int statusCode, String message) {
        results.add(new SingleOperationResult(resourceId, statusCode, message));
    }

    // getter/setter
    static class SingleOperationResult {
        private Long resourceId;
        private int statusCode;
        private String message;
        // 构造器、getter/setter
    }
}

2. 使用ResponseEntity灵活控制状态码和响应体 #

如果需要根据运行时条件动态切换状态码和响应结构，可返回ResponseEntity，它允许同时指定状态码和响应对象：

@PutMapping("/{id}")
public ResponseEntity<?> updateResource(@PathVariable Long id, @RequestBody ResourceUpdateRequest request) {
    // 业务逻辑：检查资源是否存在
    boolean exists = checkResourceExists(id);
    if (!exists) {
        // 返回404+错误响应结构
        ErrorResponse error = new ErrorResponse("NOT_FOUND", "资源不存在");
        return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
    }

    // 执行更新
    Resource updatedResource = updateResource(id, request);
    // 返回200+更新后的资源结构
    return new ResponseEntity<>(updatedResource, HttpStatus.OK);
}

// 错误响应结构
class ErrorResponse {
    private String code;
    private String message;
    // 构造器、getter/setter
}

3. 207多状态响应的注意事项 #

207 Multi-Status是HTTP标准中专门用于批量操作的状态码，Spring Boot对它的支持和其他状态码一致，但需注意：

• 响应结构要清晰区分每个子操作的状态，通常包含结果列表，每个元素包含资源ID、子状态码、消息；
• 需在API文档（如Swagger/OpenAPI）中明确说明207响应的结构，避免客户端误解。

内容的提问来源于stack exchange，提问作者user1354825