Java 后端 / 系统课时
返回 JSON 与自定义状态码
返回 JSON 与自定义状态码
接口不仅要返回数据,还要让客户端稳定判断操作结果。本课将使用 ResponseEntity 同时控制状态码、响应头和 JSON 响应体,并通过 Jackson 配置统一时间与空值的序列化方式。
学习目标
- 理解 HTTP 响应状态码、响应头与响应体的职责
- 使用
ResponseEntity返回 201、200 和 404 - 配置 Jackson 输出可预测的 JSON 字段和时间格式
稳定响应由哪些部分组成
控制器返回 Java 对象时,Spring MVC 会选择 JSON 消息转换器,再由 Jackson 完成序列化。ResponseEntity 在对象之外增加了状态码和响应头控制,因此适合需要表达“创建成功”“资源不存在”或自定义头信息的接口。

常用状态码应与操作语义一致:查询成功返回 200,创建成功返回 201,成功但无响应体可返回 204;客户端输入错误使用 400,资源不存在使用 404,业务状态冲突可使用 409。
使用 ResponseEntity 构造响应
片段示例:以下控制器依赖已有的 Spring Boot Web 项目。创建接口返回 201 和 Location 响应头,查询接口根据资源是否存在返回 200 或 404。
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 的字段。配置是全局规则,修改后应检查是否会影响已有接口契约。
spring:
jackson:
default-property-inclusion: non_null
serialization:
write-dates-as-timestamps: false生效行为:Instant 等时间类型输出为 ISO-8601 字符串,值为 null 的属性不进入 JSON。验证时应同时检查正常响应和错误响应,避免同一服务出现多套时间格式。
验证状态码、响应头与 JSON
<PORT> 替换为实际端口;<TIME> 表示运行时生成的时间,实际值每次可能不同。
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"预期输出:
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 语义一致,客户端才能可靠地处理重试、跳转、缓存和错误提示。