# REST 与服务端渲染同源：Spring MVC View 层可插拔实战

```text
旧方案：纯 REST 后端只输出 JSON，管理报表需求来了
冲突：运营要浏览器直接看 HTML 报表，前端团队没排期
后果：临时拼字符串返回 HTML，维护失控，View 层能力被浪费
```

我是老李，在深圳南山科技园一家宠物医疗 SaaS 公司做架构师。

我们的 spring-petclinic-rest 一直只输出 JSON，前端用 React 单独部署。

上周运营总监在周会上拍桌子，说要看一张管理报表，浏览器打开就能看，不要等前端排期。

为什么 REST 后端遇到 HTML 报表会这么别扭？

是继续用 @ResponseBody 拼 HTML 字符串，还是启用 Spring MVC 的 ViewResolver 走服务端渲染？

如果选错，会不会把 Controller 写成大泥球，或者引入一套和现有 REST 完全割裂的页面框架？

# 01、故事

```text
周一 09:40→深圳南山科技园→给 Petclinic 加管理报表页→运营催得急，前端没排期
```

周一早上九点四十，我坐在工位上，任务是给 spring-petclinic-rest 增加一个 /admin/report 管理报表页。

运营总监在群里连发三条消息，说下午就要看兽医接诊量汇总。

前端组长说本周迭代已满，没法接。

我打开项目，发现只有 REST Controller，所有方法都标着 @ResponseBody。

搜了一圈，没有 ViewResolver，没有模板引擎，也没有静态资源映射。

脑子里闪过一个念头：难道要像十年前那样在 Controller 里用 StringBuilder 拼 HTML？

> 晨会催声急，报表无排期
> 后端本无页，何来 HTML
> 欲问 Spring 深处，可有视图梯
> 且把源码翻起，寻那渲染机

# 02、问题

```text
需求变化：纯 JSON API → 增加浏览器直接访问的 HTML 报表
冲突：REST Controller 只懂 @ResponseBody，没有 View 层配置
后果：临时拼 HTML 字符串，转义、布局、维护全部失控
```

纯 REST 项目里，所有 Controller 方法的返回值都被 @ResponseBody 交给 HttpMessageConverter，序列化成 JSON 写回响应体。

现在要返回 HTML 页面，如果继续用 @ResponseBody 返回 String，Spring 会把它当普通文本处理，不会走视图渲染。

有人会手动拼接 HTML 字符串，但报表里有表格、日期格式化、金额千分位，还有用户输入需要转义。

拼字符串不仅容易 XSS，改一个样式要动 Java 代码，重新编译部署。

可验证的验收标准是：浏览器访问 /admin/report 返回完整 HTML 文档，Content-Type 为 text/html，且表格数据来自后端 Model。

> 纯 JSON 路，行至半途遇岔口
> 拼串如饮鸩，转义布局皆成仇
> 视图本有径，藏在 Dispatcher 后
> 不识庐山面，只缘身在此山游

# 03、原理

```text
DispatcherServlet → HandlerMapping → Controller → ModelAndView → ViewResolver → View.render → HTML
DispatcherServlet → HandlerMapping → Controller → @ResponseBody → HttpMessageConverter → JSON
```

Spring MVC 的核心是 DispatcherServlet，它不关心最终输出是 JSON 还是 HTML。

Controller 返回 ModelAndView 时，DispatcherServlet 拿着逻辑视图名去找 ViewResolver，解析出具体 View 对象，再调用 View.render

把 Model 数据渲染成响应体。

@ResponseBody 是另一条捷径：Controller 直接返回对象，DispatcherServlet 跳过 ViewResolver，用 HttpMessageConverter 把对象序

列化。反直觉的是，REST 和服务端渲染不是两套框架，而是同一个 DispatcherServlet 的两条分支。

你完全可以在同一个项目里让 /api/vets 返回 JSON，让 /admin/report 返回 HTML。

> 一条主路分两径，JSON 与 HTML 同根生
> 视图解析非魔法，接口插拔自有凭
> 莫道 REST 无页面，ModelAndView 藏真经
> 反直觉处须记取，同源异流是本性

# 04、架构

```text
HTTP 请求 → DispatcherServlet → Controller → ModelAndView → ViewResolver → View → HTML 响应
边界：ViewResolver 只负责找 View，View 只负责渲染，Controller 只负责准备 Model
```

View 层在 Spring MVC 里是可插拔设计。

ViewResolver 接口只有一个 resolveViewName 方法，View 接口只有 render 和 getContentType。

Thymeleaf、FreeMarker、JSP、PDF、Excel 都是这套接口的实现。

收益是 Controller 不用关心输出格式，换模板引擎只改配置不改业务代码。

代价是引入模板引擎依赖，增加学习成本。

适用条件是服务端渲染页面、邮件模板、报表导出等场景。

纯 API 服务不需要 ViewResolver，保持轻量。

> 接口两方法，插拔自从容
> 模板换 FreeMarker，业务不动松
> 边界划清楚，Model 归 Controller 中
> 渲染交给 View，各司其职通

# 05、第一版实战

```text
环境：Spring Boot 3.x + spring-petclinic-rest → 加 Thymeleaf 依赖 → 配置 ViewResolver → 写 Controller → 写模板 → 启动验证 → V1
```

在 pom.xml 加入 Thymeleaf 依赖。

Spring Boot 自动配置 ThymeleafViewResolver，默认前缀 classpath:/templates/，后缀 .html。

```xml
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
```

新建 AdminReportController，返回 ModelAndView，逻辑视图名为 admin/report。

```java
@Controller
@RequestMapping("/admin")
public class AdminReportController {

    private final VetRepository vetRepository;

    public AdminReportController(VetRepository vetRepository) {
        this.vetRepository = vetRepository;
    }

    @GetMapping("/report")
    public ModelAndView report() {
        List<Vet> vets = vetRepository.findAll();
        Map<String, Object> model = new HashMap<>();
        model.put("vets", vets);
        model.put("reportDate", LocalDate.now());
        return new ModelAndView("admin/report", model);
    }
}
```

在 src/main/resources/templates/admin/ 下创建 report.html。

```html
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <title>管理报表</title>
</head>
<body>
    <h1>兽医接诊量汇总</h1>
    <p>报表日期：<span th:text="${reportDate}">2025-01-01</span></p>
    <table border="1">
        <tr><th>ID</th><th>姓名</th><th>专科</th></tr>
        <tr th:each="vet : ${vets}">
            <td th:text="${vet.id}">1</td>
            <td th:text="${vet.firstName + ' ' + vet.lastName}">张三</td>
            <td th:text="${vet.specialties}">内科</td>
        </tr>
    </table>
</body>
</html>
```

启动应用，访问验证。

```bash
curl -i http://localhost:9966/petclinic/admin/report
```

预期返回 Content-Type: text/html，包含兽医表格。未在当前环境实测，以下为预期结果。

```text
示例输出：
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
<!DOCTYPE html>
<html>
<head><title>管理报表</title></head>
<body>
<h1>兽医接诊量汇总</h1>
...
```

> 依赖引入如添翼，模板目录安了家
> Controller 返回视图名，Model 数据手中拿
> 启动一声春雷响，HTML 终见天光洒
> V1 初成心稍定，且看排查细如发

# 06、排查

```text
诊断树：页面 404 → 模板路径错？→ 视图名拼写？→ 静态资源被拦截？
诊断树：页面 500 → 模板语法错？→ Model 属性缺失？→ 循环对象为 null？
```

问题一：访问 /admin/report 返回 404。怀疑是模板文件路径不对。检查 target/classes/templates/admin/ 下是否有 report.html。

```bash
ls target/classes/templates/admin/
```

证据显示文件存在，但文件名是 report.html，视图名写的是 admin/report，应该能匹配。

继续检查 Controller 的 @RequestMapping，发现类上写的是 @RequestMapping("/admin")，方法上是 @GetMapping("/report")，路径没问

题。最后发现是启动类扫描包范围没包含新 Controller 所在包。

修复：把 Controller 移到主扫描包下。

问题二：页面 500，日志显示 SpelEvaluationException。

怀疑模板里 th:text 表达式写错。

检查 report.html，发现 ${vet.specialties} 是集合，直接输出会调用 toString，但 Thymeleaf 对空集合处理正常。

真正原因是 Vet 实体里 specialties 是懒加载集合，模板渲染时 Session 已关闭，抛出 LazyInitializationException。

修复：在 Controller 里用 JOIN FETCH 查询或把 specialties 转成字符串列表放入 Model。

**错误尝试：** 第一次遇到 404 时，我以为是 Thymeleaf 没生效，手动在 application.properties 里配 spring.thymeleaf.prefix 和 suf

fix，结果还是 404。

浪费了半小时，根因是包扫描，不是配置。

> 排查如破案，证据链上寻
> 404 非配置，包扫描漏了人
> 500 藏懒加载，Session 关后魂
> 错误尝试记一笔，莫再绕远门

# 07、优化

```text
V1：Controller 直接返回 ModelAndView，懒加载集合在模板渲染时报错
证据：日志显示 LazyInitializationException，发生在 View.render 阶段
V2：Controller 里把实体转成 DTO，View 层只接触扁平数据
```

V1 的问题是 Controller 把 JPA 实体直接放进 Model，模板渲染时懒加载集合可能触发数据库访问，但事务已结束。优化方案是引入 DTO，在 Controller 里完成数据组装。

```java
@GetMapping("/report")
public ModelAndView report() {
    List<Vet> vets = vetRepository.findAllWithSpecialties();
    List<VetReportDto> rows = vets.stream()
        .map(v -> new VetReportDto(
            v.getId(),
            v.getFirstName() + " " + v.getLastName(),
            v.getSpecialties().stream()
                .map(Specialty::getName)
                .collect(Collectors.joining(", "))
        ))
        .collect(Collectors.toList());
    Map<String, Object> model = new HashMap<>();
    model.put("rows", rows);
    model.put("reportDate", LocalDate.now());
    return new ModelAndView("admin/report", model);
}
```

模板同步改为遍历 rows。

```html
<tr th:each="row : ${rows}">
    <td th:text="${row.id}">1</td>
    <td th:text="${row.name}">张三</td>
    <td th:text="${row.specialties}">内科</td>
</tr>
```

> V1 埋雷懒加载，渲染时刻爆了膛
> 证据日志指方向，事务已关莫逞强
> DTO 扁平化，View 层不再碰 JPA 肠
> V2 落地稳当当，前后对比见真章

# 08、演进

```text
V2：DTO 隔离 + Thymeleaf 渲染 → 能力：HTML 报表、Redirect、Forward、静态资源、PDF/Excel 扩展点
遗留：模板里还有少量逻辑，未做分页和权限控制
```

用 V1 同一组请求验证：curl -i http://localhost:9966/petclinic/admin/report 返回 200，Content-Type 为 text/html，表格

数据完整，无懒加载异常。

演进后新增能力：Redirect 用 return "redirect:/admin/report" 实现重定向；

Forward 用 return "forward:/admin/report" 实现服务器内转发；

静态资源放在 src/main/resources/static/ 下，Spring Boot 自动映射；

PDF 用 AbstractPdfView 或 iText 实现 View 接口，Excel 用 AbstractXlsxView。

代价是引入 Thymeleaf 依赖，模板语法需要学习。适用场景是内部管理页面、报表导出、邮件模板。遗留问题是模板里还有 th:if 条件判断，后续可考虑把复杂逻辑下沉到 DTO。

> V2 验证过，同请求前后同
> 能力渐丰盈，重定向与转发通
> 静态资源自动映，PDF Excel 接口中
> 遗留分页与权限，留待后篇再进攻

# 09、洞见

```text
从现象到判断：REST 与服务端渲染不是对立，而是同一 DispatcherServlet 的两条分支
```

## 反直觉判断：@ResponseBody 不是 View 层的替代品，而是绕过 View 层的捷径
```text
Controller → @ResponseBody → HttpMessageConverter → JSON
Controller → ModelAndView → ViewResolver → View → HTML
```
很多人以为 REST 项目里没有 View 层，其实 @ResponseBody 只是跳过了 ViewResolver，HttpMessageConverter 承担了类似 View 的渲染职责。

理解这一点，就不会在需要 HTML 时硬拼字符串。

## 反直觉判断：ViewResolver 的解析结果可以缓存，但 View 实例必须无状态
```text
ViewResolver.resolveViewName → View 实例 → 并发 render
```
ViewResolver 可以缓存 View 实例，但 View.render 会被多线程并发调用。

如果 View 里存了请求相关的状态，就会串数据。

所以自定义 View 时，请求数据只能通过 render 方法的参数传入。

## 判断：模板引擎的选择取决于团队技能和部署环境
```text
Thymeleaf：自然模板，浏览器可直接打开
JSP：依赖 Servlet 容器，打包成 jar 时受限
FreeMarker：性能好，语法简洁
```
Thymeleaf 适合前后端分离过渡期，JSP 在 Spring Boot 可执行 jar 里支持不完整，FreeMarker 适合高并发渲染。选型要看团队现有技能，不要为了技术而技术。

## 判断：Redirect 和 Forward 的差异决定了浏览器地址栏和请求次数
```text
Redirect：302 + Location → 浏览器发起第二次请求
Forward：服务器内部转发 → 浏览器无感知
```
Redirect 会改变浏览器地址栏，适合防止表单重复提交。Forward 不改变地址栏，适合同一请求内跳转。选错会导致刷新时重复提交或地址栏与页面内容不一致。

> 洞见如灯照暗路，反直觉处最醒神
> 捷径非替代，绕过视图另有因
> 无状态 View 铁律，并发渲染不串门
> 重定向与转发，地址栏里见乾坤

# 10、系统落地

```text
入口：浏览器 /admin/report → Controller → DTO 组装 → ViewResolver → Thymeleaf View → HTML
存储：VetRepository 查询数据库
未实现：分页、权限控制、PDF/Excel 导出
```

原来 spring-petclinic-rest 只有 REST API，所有响应都是 JSON。

本篇增加了 Thymeleaf 依赖、AdminReportController、report.html 模板，现在能通过浏览器直接访问 HTML 报表。

系统现在能同时服务 REST 客户端和浏览器用户，View 层可插拔设计得到验证。

下一篇缺的是 PDF/Excel 导出能力，需要实现自定义 View 或使用专门的视图类。

官方文档见 Spring Framework 文档首页 https://docs.spring.io/spring-framework/reference/ 和 spring-petclinic-re

st 仓库 https://github.com/spring-petclinic/spring-petclinic-rest 。

> 系统落地图，入口到存储清
> 本篇加模板，HTML 报表生
> 未实现分页权限，导出待后行
> 官方文档可核验，主页仓库指路径明

# 11、小结

```text
三问三答：为什么别扭？→ 因为纯 REST 项目没有 ViewResolver
选 @ResponseBody 还是 ViewResolver？→ 看输出类型，HTML 走 ViewResolver
选错后果？→ Controller 拼字符串，维护失控
```

为什么 REST 后端遇到 HTML 报表会别扭？

因为项目里只有 @ResponseBody 和 HttpMessageConverter，没有 ViewResolver 和模板引擎，返回 HTML 没有现成通道。

是继续用 @ResponseBody 拼 HTML 字符串，还是启用 ViewResolver？

答案是启用 ViewResolver，让 Controller 返回 ModelAndView，模板引擎负责渲染，Controller 只准备数据。

选错会怎样？Controller 里拼 HTML 字符串，转义、布局、维护全部失控，XSS 风险高，改样式要重新编译部署。

当前状态：/admin/report 已能返回 HTML，DTO 隔离了 JPA 实体，View 层可插拔设计验证完毕。

> 三问三答毕，迷雾散如烟
> 别扭因无视图，通道未建全
> 选型看输出，HTML 走 ViewResolver 边
> 选错拼串苦，维护如登山

# 12、作业

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

## 理解题：@ResponseBody 和 ViewResolver 在 DispatcherServlet 处理流程中的分叉点在哪里？
分叉点在 Controller 方法返回后。

DispatcherServlet 检查 HandlerMethod 是否标注 @ResponseBody 或返回值类型是 ResponseEntity。

如果是，走 HttpMessageConverter 序列化；

否则把返回值当作逻辑视图名，交给 ViewResolver 解析。

## 实战题：给 /admin/report 增加一个 CSV 导出功能，点击按钮下载 CSV 文件
在 AdminReportController 增加 @GetMapping("/report.csv")，用 produces = "text/csv" 返回 ResponseEntity<byte

[]>，或实现 AbstractCsvView 注册为 View。

Controller 里复用 DTO 组装逻辑，把 rows 转成 CSV 字节流，设置 Content-Disposition: attachment; filename=report.csv。

## 排障题：访问 /admin/report 返回 500，日志显示 TemplateInputException，如何定位？
先看异常堆栈里的模板文件名和行号，定位到具体 th: 表达式。

检查 Model 里对应属性是否存在、是否为 null。

用调试模式启动，在 Controller 返回前打印 model.keySet()，确认属性名与模板一致。

如果是 th:each 报错，检查集合是否为 null，可在模板里用 th:if="${rows != null}" 防御。

## 架构判断题：项目同时有 REST API 和服务端渲染页面，是否应该拆成两个独立应用？
不一定。如果页面数量少、与 API 共享同一领域模型，放在同一应用里成本最低，View 层可插拔设计天然支持。

如果页面复杂度高、需要独立前端团队和独立部署节奏，可以拆成两个应用，但要注意 API 版本管理和跨域配置。

判断标准是团队边界和部署频率，不是技术纯洁性。

> 作业四题如四关，理解实战排障判
> 分叉点处明流程，CSV 导出动手干
> 模板异常看行号，属性缺失莫慌乱
> 拆与不拆看团队，莫为纯洁拆两半

# 13、升华

```text
工程结论：REST 与服务端渲染同源，View 层可插拔是 Spring MVC 的架构红利
```

Spring MVC 的 View 层不是页面技术，而是一套可插拔的渲染接口。

REST 的 JSON 输出和服务端渲染的 HTML 输出，本质都是 DispatcherServlet 的两条分支。

理解这一点，就不会在需要页面时硬拼字符串，也不会为了页面引入一套与 Spring MVC 割裂的框架。

下一篇将深入 PDF/Excel 视图扩展，实现自定义 View 接口，把报表导出能力补齐。

> 同源异流本一脉，可插拔处见真功
> 莫道 REST 无页面，视图接口自从容
> 工程判断有依据，不拼字符串不盲从
> 下篇导出 PDF Excel，自定义 View 再相逢

**系列项目：** 宠物医疗 SaaS 后端服务，服务对象为宠物医院运营与兽医

**已完成：** 环境工具、Petclinic 启动、DispatcherServlet 流程、Controller 绑定、数据转换、Filter、错误处理、MVC 配置、函数式端点、URI 链接、CORS、安全、Range、缓存、异步

**本篇：** View 层可插拔实战，Thymeleaf 服务端渲染，REST 与 HTML 同源对比，Redirect、Forward、静态资源

**下一篇：** PDF/Excel 自定义 View 扩展，报表导出能力落地

我们的 spring-petclinic-rest 一直只输出 JSON，前端用 React 单独部署。

《SpringMVC7实战》第17招 View Technologies仍要知道请求怎么出去

从 Petclinic REST 到 /admin/report 报表页，对比 @ResponseBody 与 ViewResolver 两条渲染链路，掌握 R

架构师

后端

编程语言

开发工具

REST与服务端渲染同源，SpringMVC View层可插拔实战，通过Thymeleaf实现浏览器直接访问HTML报表，与JSON API共存。解决纯REST后端HTML输出难题，提供DTO隔离、ViewResolver配置及排查方案。含重定向、转发、静态资源处理，兼顾可维护性与扩展性，适合混合输出场景。

数据转换

代码解释

数据库

服务器

容器

ReAct 

SaaS

JSON

Java

腾讯云BI特惠9.9元起！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

《SpringMVC7实战》第17招 View Technologies仍要知道请求怎么出去-腾讯云开发者社区-腾讯云

《SpringMVC7实战》第17招 View Technologies仍要知道请求怎么出去

《SpringMVC7实战》第17招 View Technologies仍要知道请求怎么出去

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐