# WebMvc.fn 与注解控制器：同一 DispatcherServlet 下的两条路线

```text
旧方案：GET /api/vets 只有注解控制器
冲突：团队想抽只读接口，又听说 Functional Endpoint 更轻
后果：两条路线并存，映射、参数、响应、验证、测试、维护成本说不清
```

现有宠物诊所系统里，`GET /api/vets` 已经用 `@RestController` 稳定跑了很久。

我是老李，深圳南山科技园一家 SaaS 公司的架构师，最近被研发同学问：同一个只读接口，能不能用 `RouterFunction<ServerResponse>` 再实现一遍，看看值不值得切。

Spring MVC 官方把 WebMvc.fn 定义为注解模型的替代编程方式，但它仍然运行在同一个 `DispatcherServlet` 生命周期中，可以和 `@Controller` 并存。

如果两条路线都能实现同一个接口，映射规则会不会互相覆盖？

参数读取、响应构造、Bean Validation、单元测试，哪一条路线在长期维护中更省成本？

如果选错路线，会不会出现路由分散、异常处理不一致、团队认知割裂，最后又回滚到注解模式？

# 01、故事

```text
周二 14:30→深圳南山科技园 12 楼→抽只读接口→路由方案冲突
```

周二下午两点半，深圳南山科技园 12 楼，宠物诊所项目组正在做接口瘦身。

任务是抽一个只读接口 `GET /api/vets`，返回兽医列表，不写库、不改状态。

后端小张说注解控制器已经够用，前端组长却坚持要试 Functional Endpoint，说路由更集中。

我打开 `spring-petclinic-rest` 源码，发现 `VetController` 里只有几行 `@GetMapping`，而 WebMvc.fn 的示例在官方文档里也只是一小段。

两边都说得通，但没人能拿出同一接口的对比证据。

> 南山午后雨未停，
> 路由两路各争鸣。
> 只读接口何须重，
> 先跑起来再论清。

# 02、问题

```text
需求变化：抽只读接口→冲突：注解与函数式并存→后果：映射、验证、测试成本不明
```

需求变化来自接口治理：把只读查询从写操作中拆出来，减少事务边界和权限面。

冲突在于，团队对“函数式更现代”有期待，但现有系统全部基于注解控制器。

如果直接引入 `RouterFunction`，同一个 `DispatcherServlet` 下会出现两套映射注册方式。

失效原因可能是：路由优先级不清晰、参数绑定方式不同、异常处理链路不一致。

影响是：接口行为看似相同，实际在参数校验失败、404、内容协商时表现可能不同。

可验证验收：用同一组请求分别打到两个实现，状态码、响应体、错误格式必须一致。

> 只读接口本简单，
> 两路并行走得难。
> 映射若不分先后，
> 排查半天仍茫然。

# 03、原理

```text
DispatcherServlet→HandlerMapping→HandlerAdapter→HandlerFunction→ServerResponse
```

WebMvc.fn 不是 WebFlux，它仍然运行在 Servlet 容器里。

`RouterFunction` 会被包装成 `HandlerMapping`，`HandlerFunction` 会被包装成 `HandlerAdapter` 可执行的 handler。

请求进入 `DispatcherServlet` 后，先按 `HandlerMapping` 找到路由，再通过 `HandlerAdapter` 调用函数。

反直觉判断：函数式端点并没有绕过 `DispatcherServlet`，它只是换了编程模型，生命周期完全一致。

另一个反直觉判断：`ServerResponse` 不是响应式流，它只是 Servlet 响应的一种函数式封装。

因此，函数式端点可以和注解控制器共存，但共享同一套异常解析、视图解析、消息转换器。

> 看似新路实旧途，
> 同门同脉同中枢。
> 函数不过换写法，
> 莫把 Servlet 当虚无。

# 04、架构

```text
HTTP 请求→DispatcherServlet→RouterFunction/RequestMapping→HandlerFunction/Controller→ServerResponse/ResponseEntity
```

本模块位于 Web 层，负责把 HTTP 请求映射到处理函数，并构造 HTTP 响应。

注解控制器以类为中心，方法级映射，参数通过注解解析，响应通过返回值加消息转换器。

函数式端点以路由为中心，`RouterFunction` 组合路由，`HandlerFunction` 接收 `ServerRequest` 返回 `ServerResponse`。

边界是：两者都不处理事务、不直接访问数据库，只做协议转换和输入输出适配。

收益是：函数式路由可以更集中地声明，适合路由组合明确的场景。

代价是：参数读取、校验、异常处理需要手动编排，团队要学第二套 API。

适用条件：普通企业 CRUD 以注解为主；路由组合明确、轻量 Handler 或框架扩展场景再考虑函数式。

> 一层协议一层壳，
> 注解类聚函数合。
> 边界守住不越界，
> 选型先看维护额。

# 05、第一版实战

```text
环境→配置→代码→启动→验证→V1
```

环境：JDK 17、Spring Framework 7.0.9、Maven 3.9、Tomcat 10.1。

依赖：`spring-webmvc`、`jackson-databind`、`spring-boot-starter-validation`。

先写注解版 V1。

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

    private final VetService vetService;

    public VetController(VetService vetService) {
        this.vetService = vetService;
    }

    @GetMapping("/vets")
    public List<VetDto> list() {
        return vetService.findAll();
    }
}
```

再写函数式 V1。

```java
@Configuration
public class VetFunctionalRoutes {

    @Bean
    public RouterFunction<ServerResponse> vetRoutes(VetHandler vetHandler) {
        return RouterFunctions.route()
                .GET("/api/vets", vetHandler::list)
                .build();
    }
}
```

```java
@Component
public class VetHandler {

    private final VetService vetService;

    public VetHandler(VetService vetService) {
        this.vetService = vetService;
    }

    public ServerResponse list(ServerRequest request) {
        return ServerResponse.ok().body(vetService.findAll());
    }
}
```

启动应用后，用 curl 验证。

```bash
curl -s http://localhost:8080/api/vets
```

示例输出：

```json
[{"id":1,"firstName":"James","lastName":"Carter"}]
```

成功标准：两个实现都能返回 200 和相同 JSON。

未在当前环境实测，以下为预期结果：函数式路由与注解路由同时注册时，`DispatcherServlet` 能正常分发。

> 一版两路都跑通，
> 返回相同 JSON 同。
> 看似简单无风浪，
> 隐患藏在细节中。

# 06、排查

```text
诊断树：404→路由注册→参数绑定→响应序列化→异常处理
```

问题一：函数式接口返回 404。

现象：`curl /api/vets` 返回 404，注解接口正常。

怀疑：`RouterFunction` 没有注册到 `DispatcherServlet`。

检查：打开日志，查看 `HandlerMapping` 列表。

```text
示例输出：
RouterFunctionMapping mapped GET /api/vets
RequestMappingHandlerMapping mapped GET /api/vets
```

证据：两个映射都存在，但函数式路由的 `RouterFunctionMapping` 顺序排在注解映射之后。

根因：注解映射先匹配成功，函数式路由没有机会执行。

修复：给函数式路由加前缀或调整映射顺序，验证时先只保留一个实现。

问题二：函数式接口返回 500，报 `HttpMessageNotWritableException`。

现象：注解接口正常，函数式接口序列化失败。

怀疑：`ServerResponse.body` 没有正确选择消息转换器。

检查：确认 `VetDto` 是否有 getter，以及 Jackson 是否在类路径。

```bash
mvn dependency:tree | grep jackson
```

证据：Jackson 存在，但 `VetDto` 缺少无参构造器。

根因：Jackson 反序列化需要无参构造器，函数式路径没有额外配置。

修复：给 `VetDto` 添加无参构造器，两个实现都恢复正常。

**错误尝试：** 一开始以为函数式路由需要单独注册 `WebMvcConfigurer`，结果加了配置类反而导致重复映射。

> 路由双生易相争，
> 序列化错更无声。
> 排查先看映射序，
> 再看 DTO 构造层。

# 07、优化

```text
V1：两路并存→证据：404 与序列化问题→V2：统一验证与异常格式
```

V1 的问题不是功能不可用，而是两套实现的行为不一致。

优化点一：给函数式 Handler 增加参数校验。

```java
public ServerResponse list(ServerRequest request) {
    List<VetDto> vets = vetService.findAll();
    if (vets.isEmpty()) {
        return ServerResponse.noContent().build();
    }
    return ServerResponse.ok().body(vets);
}
```

优化点二：统一异常格式。

```java
@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handle(Exception e) {
        return ResponseEntity.status(500).body(new ApiError(e.getMessage()));
    }
}
```

函数式端点抛出的异常同样会被 `@RestControllerAdvice` 捕获，因为共享同一套异常解析器。

优化点三：把函数式路由拆成独立配置类，避免和注解控制器混在一起。

```java
@Configuration(proxyBeanMethods = false)
public class VetFunctionalConfig {

    @Bean
    public RouterFunction<ServerResponse> vetRoutes(VetHandler vetHandler) {
        return RouterFunctions.route()
                .GET("/api/vets", vetHandler::list)
                .build();
    }
}
```

这样路由声明集中，但 Handler 逻辑仍然分散。

> 优化不在炫技多，
> 统一行为是正途。
> 异常格式若不一，
> 前端联调要吃苦。

# 08、演进

```text
V2：统一行为→能力：可并存可切换→遗留：两套 API 认知成本
```

V2 之后，同一个 `GET /api/vets` 可以用两种方式实现，行为一致。

收益是：团队可以按场景选择，路由组合明确的轻量接口用函数式，复杂参数绑定用注解。

代价是：新人要同时理解 `@GetMapping` 和 `RouterFunction`，代码评审要检查两套风格。

适用条件：框架扩展、动态路由、路由组合明确的场景适合函数式；普通 CRUD 继续用注解。

遗留问题：函数式端点的参数校验、内容协商、错误处理需要手动编排，容易漏掉边界。

用 V1 同一组请求前后验证：`curl /api/vets` 返回 200，空列表返回 204，异常返回统一 JSON。

> 演进不是全替换，
> 并存切换有空间。
> 遗留认知两套法，
> 选型守住维护线。

# 09、洞见

```text
从现象到判断：函数式不是新架构，只是新语法
```

## 函数式端点没有绕过 DispatcherServlet
```text
请求→DispatcherServlet→RouterFunctionMapping→HandlerFunctionAdapter→ServerResponse
```

反直觉判断：很多人以为函数式端点更底层、更接近原生，实际上它只是换了编程模型，生命周期完全一致。

## 路由集中不等于维护成本低
```text
路由集中→声明清晰→Handler 分散→逻辑追踪变难
```

反直觉判断：`RouterFunction` 把路由集中在一处，但 Handler 逻辑仍然分散，排查问题时反而要多跳一层。

## 注解控制器更适合企业 CRUD
```text
参数绑定→注解声明→校验自动→异常统一→维护成本低
```

普通企业 CRUD 的复杂度在参数绑定、校验、异常处理，注解模型把这些能力内建，函数式需要手动编排。

## 函数式端点的真正价值在框架扩展
```text
动态路由→路由组合→轻量 Handler→框架扩展→收益明显
```

当路由需要动态生成、组合嵌套、或者作为框架内部机制时，函数式 API 的表达力更强。

> 洞见不在追新潮，
> 同门同脉莫混淆。
> 选型先看维护账，
> 莫把语法当高招。

# 10、系统落地

```text
HTTP 请求→DispatcherServlet→RouterFunction/RequestMapping→HandlerFunction/Controller→VetService→数据库
```

原来系统只有注解控制器，`GET /api/vets` 直接返回兽医列表。

本篇增加了函数式端点实现，证明两条路线可以并存且行为一致。

现在系统能做什么：同一个只读接口可以用两种方式实现，团队可以按场景选择。

下一篇缺什么：函数式端点的参数校验、内容协商、错误处理需要更完整的工程化方案。

官方文档主页：https://docs.spring.io/spring-framework/reference/web/webmvc-functional.html

> 系统落地看全局，
> 注解函数本同渠。
> 今日只读已双路，
> 明日校验再补齐。

# 11、小结

```text
三问三答：映射覆盖→参数响应→选错后果
```

第一问：映射规则会不会互相覆盖？会，但可以通过路由顺序和前缀控制，实际项目中应避免同一路径双实现。

第二问：参数读取、响应构造、校验、测试哪条路线更省成本？注解控制器更省，因为参数绑定、校验、异常处理都是内建能力。

第三问：选错路线会怎样？会出现路由分散、异常格式不一致、团队认知割裂，最终回滚到注解模式。

当前状态：V2 已统一行为，函数式端点作为可选方案保留，默认继续用注解控制器。

> 三问三答已分明，
> 注解为主函数轻。
> 选型守住维护线，
> 莫让新潮乱工程。

# 12、作业

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

## 理解题：WebMvc.fn 和 WebFlux 的区别是什么？

WebMvc.fn 运行在 Servlet 容器和 `DispatcherServlet` 中，是同步阻塞模型；

WebFlux 运行在响应式容器中，是异步非阻塞模型。

两者 API 相似但运行时完全不同。

## 实战题：给函数式端点增加一个查询参数 `specialty`，过滤兽医列表。

在 `VetHandler.list` 中读取 `request.param("specialty")`，调用 `vetService.findBySpecialty`，返回过滤后的列表。

## 排障题：函数式端点返回 404，但注解端点正常，如何排查？

先看 `HandlerMapping` 日志，确认 `RouterFunctionMapping` 是否注册；再看映射顺序，注解映射可能先匹配；最后检查路径是否完全一致。

## 架构判断题：一个已有 50 个注解控制器的系统，是否应该全面切换到函数式端点？

不应该。普通企业 CRUD 以注解模式为主，函数式端点适合路由组合明确、轻量 Handler 或框架扩展场景。全面切换会增加维护成本，且没有明显收益。

> 作业四题练真功，
> 理解实战排障通。
> 架构判断守底线，
> 莫让新潮乱初衷。

# 13、升华

```text
工程结论：同一 DispatcherServlet 下，注解为主，函数式为辅
```

有依据的结论：WebMvc.fn 不是 WebFlux，它仍然运行在同一个 `DispatcherServlet` 生命周期中，可以和 `@Controller` 并存。

普通企业 CRUD 继续以注解模式为主，因为参数绑定、校验、异常处理的内建能力更省维护成本。

路由组合明确、轻量 Handler 或框架扩展场景再考虑 Functional Endpoint，它的价值在表达力，不在性能。

下一篇可以深入函数式端点的参数校验、内容协商、错误处理，补齐工程化能力。

> 同门同脉两条路，
> 注解为主函数辅。
> 选型守住维护线，
> 工程判断不糊涂。

**系列项目：** 宠物诊所 REST API 系统，服务兽医与宠物诊疗数据查询。

**已完成：** 环境工具、Petclinic、DispatcherServlet、Controller、Binding、Converter、Filter、Error、MVC Config。

**本篇：** WebMvc.fn 与注解控制器并存，同一 DispatcherServlet 下两条路线对比。

**下一篇：** 函数式端点的参数校验、内容协商、错误处理工程化。

现有宠物诊所系统里，GET /api/vets 已经用 @RestController 稳定跑了很久。

《SpringMVC7实战》第10招 Functional Endpoint什么时候值得用

从只读接口抽取实战出发，对比 WebMvc.fn 与注解控制器的映射、参数、响应、验证、测试与维护成本，给出企业 CRUD 的工程判断。

架构师

编程语言

后端

开发工具

同一DispatcherServlet下，WebMvc.fn与注解控制器可并存，但注解模式凭内建校验与异常处理更省维护成本。函数式路由适合轻量、组合明确场景，若路径重复需控制映射顺序。普通CRUD应以注解为主，函数式为辅，避免路由分散与认知割裂。

单元测试

代码解释

数据库

容器

路由

SaaS

JSON

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

《SpringMVC7实战》第10招 Functional Endpoint什么时候值得用-腾讯云开发者社区-腾讯云

《SpringMVC7实战》第10招 Functional Endpoint什么时候值得用

《SpringMVC7实战》第10招 Functional Endpoint什么时候值得用

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐