# Owner 查询 JSON API：从 HTTP 到 Response 的完整调用链

```text
旧方案：仅返回 Thymeleaf 视图，无标准 JSON API
冲突：前端/第三方需要结构化数据，但现有 Controller 只返回视图名
后果：无法复用业务逻辑，接口契约不清晰，错误响应格式不统一
```

Petclinic 官方项目默认面向服务端渲染，OwnerController 的查询方法返回 ModelAndView 或视图名。

当团队需要给移动端、管理后台或开放平台提供 Owner 查询能力时，直接复用现有 Controller 会暴露 HTML 片段，而不是结构化 JSON。

我是老李，今天要带你把 Owner 查询改造成标准 JSON API，并且把 HTTP 请求从进入 Tomcat 到最终返回 Response 的每一层都追清楚。

为什么 Controller 里只写了一句 return owner，最终客户端却能收到一个完整的 HTTP JSON Response？

是继续在现有 Controller 上增加 @ResponseBody，还是单独建立 ApiController 并引入 DTO、校验和统一异常处理？

如果选错，会不会出现实体直接序列化导致循环引用、校验错误返回 500、或者 404 与业务异常格式不一致的问题？

# 01、故事

```text
周二 14:30 → 研发区 → 给运营后台提供 Owner 查询接口 → 前端催接口、现有代码只返回 HTML
```

周二下午两点半，我坐在研发区，任务是给运营后台提供一个按 ID 查询 Owner 的 JSON 接口。

前端同事在群里催：“接口什么时候好？我现在拿到的全是 HTML 片段，根本没法解析。”

我打开 Petclinic 的 OwnerController，发现查询方法返回的是视图名，数据通过 Model 传给 Thymeleaf 渲染。

如果直接加 @ResponseBody 返回 Owner 实体，又担心宠物集合被序列化出一大堆嵌套对象，甚至可能出现循环引用。

> 午后工位催声急，
> 旧日视图难解意。
> 欲把主人成数据，
> 却愁嵌套无穷已。

# 02、问题

```text
需求变化：服务端渲染 → 标准 JSON API
冲突：Controller 返回视图，实体直接序列化风险高
后果：接口不可用、错误格式混乱、前后端联调成本高
```

现有 OwnerController 的查询逻辑绑定视图渲染，无法直接满足 JSON 接口需求。

如果直接返回 Owner 实体，JPA 关联的 pets、visits 可能被 Jackson 深度序列化，导致响应体膨胀、性能下降，甚至双向关联引发循环引用。

同时，参数缺失、ID 不存在、业务校验失败等场景没有统一的错误结构，前端需要针对不同状态码和响应体写多套解析逻辑。

可验证的验收标准是：GET /api/owners/{id} 返回标准 JSON；

参数错误返回 400；

不存在返回 404；

业务异常返回 409；

未预期异常返回 500，且错误体符合 Problem Detail 规范。

> 视图转身成接口，
> 实体裸奔隐患久。
> 错误若还无定式，
> 联调终夜空白首。

# 03、原理

```text
HTTP → Tomcat → Filter → DispatcherServlet → HandlerMapping → HandlerAdapter → ArgumentResolver → Validation → Controller → Service → MessageConverter → Response
```

Spring MVC 的核心是 DispatcherServlet，它把请求分发给 HandlerMapping 找到的处理器，再由 HandlerAdapter 完成参数解析、校验、调用和返回值处理

。

Controller 方法返回的 Owner 对象并不是 HTTP 响应本身，它只是返回值。

真正把它变成 JSON 的是 HttpMessageConverter，Spring Boot 默认配置了 MappingJackson2HttpMessageConverter。

一个反直觉判断是：Controller 里那句 return owner 并没有“发送响应”，它只是把对象交给框架，框架在方法返回后才开始序列化和写响应。

另一个反直觉判断是：@Valid 校验失败抛出的 MethodArgumentNotValidException 如果不在统一异常处理中捕获，默认会变成 500，而不是 400。

> 一句返回非终点，
> 框架接力方成全。
> 校验若无人接住，
> 五百错把四百演。

# 04、架构

```text
输入：GET /api/owners/{id}
本模块：ApiController → OwnerRequest/Response DTO → Validation → OwnerService → ExceptionHandler → ProblemDetail
输出：标准 JSON + 正确 HTTP Status
边界：不直接暴露 JPA 实体，不把业务异常泄漏到客户端
```

本模块分为四层：Controller 负责接收 HTTP 请求并调用 Service；

DTO 负责请求和响应契约；

Service 复用现有业务逻辑；

ExceptionHandler 负责把异常映射为 Problem Detail。

Controller 不直接返回 Owner 实体，而是返回 OwnerResponse DTO，这样可以把 JPA 关联关系隔离在服务层内部。

统一异常处理放在 @RestControllerAdvice 中，分别处理参数校验失败、资源不存在、业务冲突和未预期异常。

收益是接口契约清晰、错误格式统一、实体演化不影响外部 API。

代价是增加 DTO 映射代码，且需要明确哪些异常映射到哪些 HTTP 状态码。

适用条件是系统需要对外提供 JSON API，或前后端分离后需要稳定契约。

> 实体深藏服务内，
> 契约只露薄薄层。
> 异常各有归处去，
> 状态分明不误人。

# 05、第一版实战

```text
环境：Spring Boot 4 + Java 21 + Maven
配置：pom.xml 引入 spring-boot-starter-web、spring-boot-starter-validation、spring-boot-starter-data-jpa
代码：OwnerResponse、OwnerRequest、ApiOwnerController、GlobalExceptionHandler
启动：mvn spring-boot:run
验证：curl GET /api/owners/1
V1：返回 OwnerResponse JSON，但错误处理不完整
```

先确认 pom.xml 包含 Web、Validation 和 JPA 依赖。

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
```

创建 OwnerResponse DTO，只暴露必要字段。

```java
public record OwnerResponse(
        Long id,
        String firstName,
        String lastName,
        String address,
        String city,
        String telephone
) {
}
```

创建 ApiOwnerController，返回 DTO 而不是实体。

```java
@RestController
@RequestMapping("/api/owners")
public class ApiOwnerController {

    private final OwnerService ownerService;

    public ApiOwnerController(OwnerService ownerService) {
        this.ownerService = ownerService;
    }

    @GetMapping("/{id}")
    public OwnerResponse getOwner(@PathVariable Long id) {
        Owner owner = ownerService.findOwnerById(id);
        return new OwnerResponse(
                owner.getId(),
                owner.getFirstName(),
                owner.getLastName(),
                owner.getAddress(),
                owner.getCity(),
                owner.getTelephone()
        );
    }
}
```

启动应用。

```bash
mvn spring-boot:run
```

验证正常查询。

```bash
curl -i http://localhost:8080/api/owners/1
```

示例输出：

```text
HTTP/1.1 200
Content-Type: application/json

{"id":1,"firstName":"George","lastName":"Franklin","address":"110 W. Liberty St.","city":"Madison","telephone":"6085551023"}
```

V1 成功返回 JSON，但此时如果传入非数字 ID，会触发 500；如果 ID 不存在，也会因为 Service 抛异常而返回 500。

> 初版接口已成形，
> 正常路径走得通。
> 只是错误无人管，
> 五百乱象隐其中。

# 06、排查

```text
诊断树
├── 参数类型错误 → 怀疑 MethodArgumentTypeMismatchException → 检查默认异常处理 → 证据：返回 500 → 根因：未捕获该异常
├── ID 不存在 → 怀疑 Service 抛 NoSuchElementException → 检查响应 → 证据：返回 500 → 根因：未映射为 404
└── 业务校验失败 → 怀疑 Service 抛 IllegalStateException → 检查响应 → 证据：返回 500 → 根因：未映射为 409
```

第一个问题是传入非数字 ID。

```bash
curl -i http://localhost:8080/api/owners/abc
```

示例输出：

```text
HTTP/1.1 500
{"timestamp":"...","status":500,"error":"Internal Server Error","path":"/api/owners/abc"}
```

怀疑是 MethodArgumentTypeMismatchException 没有被处理。

检查日志，看到异常堆栈：

```text
Failed to convert value of type 'java.lang.String' to required type 'java.lang.Long'
```

根因是 Spring 默认把类型转换失败当作未预期异常，返回 500。

第二个问题是 ID 不存在。

```bash
curl -i http://localhost:8080/api/owners/9999
```

示例输出：

```text
HTTP/1.1 500
{"timestamp":"...","status":500,"error":"Internal Server Error","path":"/api/owners/9999"}
```

怀疑是 Service 抛出的 NoSuchElementException 没有被映射。

检查 Service 实现，发现 findOwnerById 内部使用 Optional.orElseThrow()。

根因是异常直接冒泡到容器，被默认 500 处理。

**错误尝试：** 我一开始在 Controller 里用 try-catch 捕获所有异常并手动构造 ResponseEntity，结果每个方法都重复大量样板代码，而且状态码散落各处，难以统一维护。

> 参数错时五百现，
> 资源不在也同面。
> 若在方法里捕尽，
> 样板成灾更难辨。

# 07、优化

```text
V1：正常路径可用，错误路径全部 500
证据：curl 参数错误、不存在 ID 均返回 500
V2：引入 @RestControllerAdvice + ProblemDetail，统一映射 400/404/409/500
```

创建 GlobalExceptionHandler，集中处理四类异常。

```java
@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentTypeMismatchException.class)
    public ProblemDetail handleTypeMismatch(MethodArgumentTypeMismatchException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.BAD_REQUEST,
                "参数类型错误: " + ex.getName()
        );
        pd.setTitle("Bad Request");
        return pd;
    }

    @ExceptionHandler(NoSuchElementException.class)
    public ProblemDetail handleNotFound(NoSuchElementException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.NOT_FOUND,
                "Owner 不存在"
        );
        pd.setTitle("Not Found");
        return pd;
    }

    @ExceptionHandler(IllegalStateException.class)
    public ProblemDetail handleConflict(IllegalStateException ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.CONFLICT,
                ex.getMessage()
        );
        pd.setTitle("Conflict");
        return pd;
    }

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleGeneric(Exception ex) {
        ProblemDetail pd = ProblemDetail.forStatusAndDetail(
                HttpStatus.INTERNAL_SERVER_ERROR,
                "服务器内部错误"
        );
        pd.setTitle("Internal Server Error");
        return pd;
    }
}
```

同时让 Service 在业务校验失败时抛出 IllegalStateException，而不是返回 null 或布尔值。

这样 Controller 保持简洁，所有错误路径都汇聚到 GlobalExceptionHandler。

> 异常汇聚一处管，
> 状态分明各有安。
> 四百四百零九，
> 五百不再乱纠缠。

# 08、演进

```text
V2：统一异常处理 + Problem Detail
能力：标准 JSON 契约、稳定错误格式、可扩展异常映射
遗留：校验异常尚未覆盖，请求体校验需后续补充
```

用 V1 同一组请求验证 V2。

正常查询：

```bash
curl -i http://localhost:8080/api/owners/1
```

示例输出：

```text
HTTP/1.1 200
Content-Type: application/json

{"id":1,"firstName":"George","lastName":"Franklin","address":"110 W. Liberty St.","city":"Madison","telephone":"6085551023"}
```

参数类型错误：

```bash
curl -i http://localhost:8080/api/owners/abc
```

示例输出：

```text
HTTP/1.1 400
Content-Type: application/problem+json

{"type":"about:blank","title":"Bad Request","status":400,"detail":"参数类型错误: id","instance":"/api/owners/abc"}
```

ID 不存在：

```bash
curl -i http://localhost:8080/api/owners/9999
```

示例输出：

```text
HTTP/1.1 404
Content-Type: application/problem+json

{"type":"about:blank","title":"Not Found","status":404,"detail":"Owner 不存在","instance":"/api/owners/9999"}
```

收益是前端只需识别 Content-Type 和 status，就能统一解析错误。

代价是 GlobalExceptionHandler 需要持续维护异常映射，避免把所有异常都归为 500。

遗留问题是当前只有路径参数，还没有覆盖请求体校验，例如创建 Owner 时的 @Valid 校验失败。

> 同组请求再验证，
> 状态分明各归位。
> 契约稳定前端喜，
> 遗留校验待下回。

# 09、洞见

```text
从现象到判断：Controller 返回对象 ≠ HTTP 响应；异常映射决定 API 成熟度
```

## Controller 的 return 只是返回值，不是响应
```text
Controller → return Owner → HandlerAdapter → MessageConverter → HTTP Response
```

很多人以为 return 语句执行完响应就发出了，实际上 return 只是把对象交给框架。

真正的序列化和响应写入发生在方法返回之后，由 HttpMessageConverter 完成。

这解释了为什么 Controller 里只有一句 return owner，客户端却能收到完整 JSON。

## 反直觉判断：默认异常处理会把很多客户端错误变成 500
```text
参数类型错误 → 默认 500 → 实际应为 400
```

Spring Boot 的默认错误处理对未捕获异常统一返回 500，即使根因是客户端传错参数。

如果不显式映射 MethodArgumentTypeMismatchException，前端会误以为服务器故障。

统一异常处理不是可选优化，而是 JSON API 的基本能力。

## 反直觉判断：DTO 不是多余代码，而是契约边界
```text
实体直接序列化 → 关联爆炸/循环引用 → DTO 隔离 → 契约稳定
```

直接返回 JPA 实体看似省事，但会把持久化细节泄漏到 API。

DTO 的映射代码虽然增加，但换来的是外部契约与内部模型解耦。

当实体增加字段或调整关联时，API 可以保持稳定。

## Problem Detail 让错误从“状态码”升级为“可读文档”
```text
错误响应 → title + status + detail + instance → 前端可统一处理
```

Problem Detail 规范让错误响应包含人类可读的 title、机器可读的 status、具体 detail 和发生路径 instance。

前端可以只写一个错误解析器，而不需要为每个接口单独适配。

> 返回非响应须明辨，
> 异常映射定成熟。
> 契约边界靠 DTO，
> 错误文档解百忧。

# 10、系统落地

```text
入口：GET /api/owners/{id}
服务：ApiOwnerController → OwnerService → OwnerRepository
本模块：DTO 映射、统一异常处理、Problem Detail
存储：H2/MySQL 中的 owners 表
未实现：请求体校验、创建/更新 API、分页查询
```

原来 Petclinic 只有服务端渲染的 Owner 查询，没有标准 JSON API。

本篇增加了 ApiOwnerController、OwnerResponse DTO 和 GlobalExceptionHandler，使系统具备对外提供 Owner 查询 JSON 接口的能力。

现在前端可以通过 GET /api/owners/{id} 获取结构化数据，并且错误响应统一为 Problem Detail 格式。

下一篇需要补充创建和更新 Owner 的 JSON API，并引入请求体 DTO 与 Bean Validation。

官方文档可参考 Spring 官网 https://spring.io 和 Petclinic 仓库 https://github.com/spring-projects/spring-petclin

ic 。

> 旧日视图今成 API，
> 查询一路到存储。
> 错误统一契约稳，
> 创建更新待下章。

# 11、小结

```text
三问三答：return 如何变响应；是否新建 ApiController；选错后果
```

第一问：Controller 里只写了一句 return owner，为什么最终能变成完整 HTTP JSON Response？

因为 return 只是把对象交给 HandlerAdapter，后续由 MappingJackson2HttpMessageConverter 序列化为 JSON，并写入 HTTP 响应体。

第二问：是继续在现有 Controller 上增加 @ResponseBody，还是单独建立 ApiController？

单独建立 ApiController 更合适，因为服务端渲染和 JSON API 的返回类型、异常策略、契约要求不同，分离后各自演化更清晰。

第三问：如果选错会怎样？

如果直接返回实体会导致关联爆炸或循环引用；如果不做统一异常处理，参数错误和 404 都会变成 500，前端无法区分客户端错误和服务端故障。

当前状态是 Owner 查询 JSON API 已可用，错误响应符合 Problem Detail，但创建、更新和请求体校验尚未实现。

> 一句返回非终点，
> 框架接力方成全。
> 分离接口避旧债，
> 统一异常保平安。

# 12、作业

```text
理解 → 实战 → 排障 → 架构判断
```

## 理解题：为什么 @RestController 的方法返回对象后，客户端能收到 JSON？

因为 @RestController 组合了 @ResponseBody，HandlerAdapter 在方法返回后调用 HttpMessageConverter 将返回值序列化为 JSON，再写入

HTTP 响应体。

## 实战题：为 Petclinic 增加 GET /api/owners?lastName=xxx 的查询接口，返回 List<OwnerResponse>，并处理空结果。

创建 ApiOwnerController 中的查询方法，调用 OwnerService 按 lastName 查询，空结果返回空列表和 200，而不是 404。

## 排障题：调用 GET /api/owners/abc 返回 500，但日志显示 MethodArgumentTypeMismatchException，如何修复？

在 GlobalExceptionHandler 中增加 @ExceptionHandler(MethodArgumentTypeMismatchException.class)，返回 400 和 P

roblemDetail，而不是让它冒泡到默认 500 处理。

## 架构判断题：如果前端要求返回 Owner 的所有 pets 和 visits，是否应该直接返回 Owner 实体？

不应该。应该为这个需求单独设计包含 pets 和 visits 的 DTO，避免实体直接序列化带来的关联爆炸和循环引用，同时保持 API 契约稳定。

> 理解框架接力链，
> 实战查询列表添。
> 排障须看异常类，
> 架构判断守边界。

# 13、升华

```text
工程结论：JSON API 的成熟度取决于契约、校验和错误处理，而不是能否返回 JSON
```

能返回 JSON 只是起点，真正的工程能力在于稳定契约、明确校验和统一错误处理。

Controller 的 return 只是调用链中的一个环节，理解从 HTTP 到 Response 的完整路径，才能在排障时快速定位问题。

下一篇将引入请求体 DTO 和 Bean Validation，把创建 Owner 的 JSON API 落地，并覆盖校验失败的错误映射。

> 能返 JSON 非终点，
> 契约校验方为全。
> 调用链中明因果，
> 排障定位不茫然。

**系列项目：** Spring 官方 Petclinic 演进为生产级 Spring Boot 4 Java 应用

**已完成：** 环境搭建、启动机制、依赖与自动配置、配置体系、Web 基础、安全、数据、事务、远程调用、数据库迁移、缓存、并发、日志、测试、Testcontainers、Docker Compose、Actuator、可观测、自定义自动配置、容器构建、生产上线

**本篇：** Owner 查询标准 JSON API、DTO、统一异常处理、Problem Detail、HTTP 状态码映射

**下一篇：** Owner 创建与更新 JSON API、请求体 DTO、Bean Validation、校验错误映射

Petclinic 官方项目默认面向服务端渲染，OwnerController 的查询方法返回 ModelAndView 或视图名。

《SpringBoot4进阶实战》第8招 Web请求完整走一遍

以 Petclinic Owner 查询为例，追踪 Spring MVC 从 HTTP 请求到 JSON 响应的完整链路，并落地统一异常处理与 Problem

架构师

后端

编程语言

开发工具

将Petclinic的Owner查询改造为标准JSONAPI，核心在于分离Controller职责、引入DTO隔离实体，并通过统一异常处理将参数错误、资源不存在等映射为规范的ProblemDetail格式，确保400、404、500状态码准确返回，形成清晰稳定的接口契约。

结构化数据

代码解释

数据库

服务器

容器

MySQL

JSON

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《SpringBoot4进阶实战》第8招 Web请求完整走一遍-腾讯云开发者社区-腾讯云

《SpringBoot4进阶实战》第8招 Web请求完整走一遍

《SpringBoot4进阶实战》第8招 Web请求完整走一遍

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐