Java 后端 / 系统课时

返回 JSON 与自定义状态码

返回 JSON 与自定义状态码

接口不仅要返回数据,还要让客户端稳定判断操作结果。本课将使用 ResponseEntity 同时控制状态码、响应头和 JSON 响应体,并通过 Jackson 配置统一时间与空值的序列化方式。

学习目标

  • 理解 HTTP 响应状态码、响应头与响应体的职责
  • 使用 ResponseEntity 返回 201、200 和 404
  • 配置 Jackson 输出可预测的 JSON 字段和时间格式

稳定响应由哪些部分组成

控制器返回 Java 对象时,Spring MVC 会选择 JSON 消息转换器,再由 Jackson 完成序列化。ResponseEntity 在对象之外增加了状态码和响应头控制,因此适合需要表达“创建成功”“资源不存在”或自定义头信息的接口。

Spring Boot JSON 响应生成链路

常用状态码应与操作语义一致:查询成功返回 200,创建成功返回 201,成功但无响应体可返回 204;客户端输入错误使用 400,资源不存在使用 404,业务状态冲突可使用 409。

使用 ResponseEntity 构造响应

片段示例:以下控制器依赖已有的 Spring Boot Web 项目。创建接口返回 201 和 Location 响应头,查询接口根据资源是否存在返回 200 或 404。

java
package com.example.demo.web;

import java.net.URI;
import java.time.Instant;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
public class UserResponseController {

    @PostMapping
    public ResponseEntity<UserResponse> create(
            @RequestBody CreateUserRequest request) {

        long newId = 1001L;
        UserResponse body =
                new UserResponse(newId, request.name(), Instant.now());

        // created 会设置 201,并把新资源地址写入 Location 响应头
        return ResponseEntity
                .created(URI.create("/api/users/" + newId))
                .body(body);
    }

    @GetMapping("/{id}")
    public ResponseEntity<?> find(@PathVariable long id) {
        if (id != 1001L) {
            ApiError error =
                    new ApiError("USER_NOT_FOUND", "用户不存在");
            return ResponseEntity
                    .status(HttpStatus.NOT_FOUND)
                    .body(error);
        }

        return ResponseEntity.ok(
                new UserResponse(id, "Lin", Instant.now())
        );
    }

    public record CreateUserRequest(String name) {}

    public record UserResponse(long id, String name, Instant createdAt) {}

    public record ApiError(String code, String message) {}
}

生效行为:方法返回的记录对象会被序列化为 JSON;ResponseEntity.created(...) 产生 201,status(HttpStatus.NOT_FOUND) 产生 404。生产项目通常把错误对象与异常映射集中到统一异常处理器,而不是散落在每个控制器中。

配置 Jackson 输出规则

在 application.yml 中关闭时间戳输出,并忽略值为 null 的字段。配置是全局规则,修改后应检查是否会影响已有接口契约。

yaml
spring:
  jackson:
    default-property-inclusion: non_null
    serialization:
      write-dates-as-timestamps: false

生效行为:Instant 等时间类型输出为 ISO-8601 字符串,值为 null 的属性不进入 JSON。验证时应同时检查正常响应和错误响应,避免同一服务出现多套时间格式。

验证状态码、响应头与 JSON

<PORT> 替换为实际端口;<TIME> 表示运行时生成的时间,实际值每次可能不同。

bash
curl -i -X POST "http://localhost:<PORT>/api/users" \
  -H "Content-Type: application/json" \
  -d '{"name":"Lin"}'

curl -i "http://localhost:<PORT>/api/users/9999"

预期输出:

text
HTTP/1.1 201
Location: /api/users/1001
Content-Type: application/json

{"id":1001,"name":"Lin","createdAt":"<TIME>"}

HTTP/1.1 404
Content-Type: application/json

{"code":"USER_NOT_FOUND","message":"用户不存在"}

响应头顺序、协议版本和 <TIME> 的具体值可能不同。验收重点是状态码、Location、字段名称和 JSON 数据类型保持稳定。

避免不稳定响应

不要直接把 JPA 实体作为 API 响应,否则延迟加载字段、双向关联和数据库结构变化可能意外改变 JSON。应定义专用响应 DTO,并为错误结果使用固定字段,例如 code、message 和必要的追踪标识。

自定义状态码也不能只追求“能返回”。状态码必须与 HTTP 语义一致,客户端才能可靠地处理重试、跳转、缓存和错误提示。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

返回 JSON 与自定义状态码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通