企业官网建设流程全解析

聊到 Spring WebFlux，很多人的第一反应是“响应式编程”，接着就会蹦出 Flux、Mono、背压、非阻塞这一串名词。但真正要落地上手，问题往往不是概念不够炫，而是——我原来的 Spring MVC 项目到底卡在哪？换 WebFlux 之后哪些写法必须改？遇到线程池耗尽、事务不生效、数据流不输出的时候该怎么排查？

我最早接触 WebFlux，是在一个优化推送服务接口的项目里。当时服务的问题很典型：并发连接一多，Tomcat 线程池就被占满了，CPU 却只用了不到三成，大量请求都堵在等待数据库和远程接口返回上。换用 WebFlux 之后，最直观的变化不是单个接口延迟变低，而是同样一台机器能撑住的连接数和整体吞吐量完全不一样了。这篇文章不打算洋洋洒洒讲理论，而是把 WebFlux 的核心思路、从 MVC 迁移到响应式的实操路径、以及我踩过的一些坑一次性讲清楚。不管你是准备做技术选型、要在老项目里改造某一个接口，还是刚接手一个 WebFlux 服务，这篇文章都会对你有所帮助。

1. WebFlux 到底解决什么问题：先放下框架，想想业务的痛点

1.1 传统阻塞模型的天花板在哪

很多人问 WebFlux 是不是“让接口更快”，这个理解并不准确。它真正改变的是服务端处理大量并发请求时的资源利用方式。

传统 Spring MVC 基于 Servlet 规范，核心是“一个请求占用一个线程”。Tomcat 默认线程池一般是 200，这 200 是个硬上限。当请求进入后，如果这个请求要等数据库查询 100ms、调远程接口 300ms，那这个线程在这 100ms 或 300ms 里就是纯空等——什么也干不了，也不能去处理别的请求。并发一旦超过 200，后面的请求只能排队。

生活里的类比就是餐厅服务员。一个服务员接待一桌客人后，从点菜到上菜全程站在旁边等着，期间不能服务其他桌。如果餐厅同时来了 300 桌客人，而服务员只有 200 个，剩下的 100 桌只能在门口排着。服务员的空闲时间越长，餐厅能接待的总客流量就越低。

很多团队靠两个办法硬扛这个模型：一个是把线程池调大，一个是横向加机器。线程池调大到 500、1000，业务高峰期确实能扛得住，但每个线程默认栈空间就有 1MB 左右，线程数越多，内存开销和上下文切换的成本也跟着涨；加机器则更直接，但成本高，而且资源利用率依然不高——核心问题在于大量线程其实都在空等。

1.2 响应式不是更快，而是更省

WebFlux 采用的模型完全不同。它底层基于 Netty 的 event loop 机制，默认启用的线程数通常很少，一般等于 CPU 核数的 1 到 2 倍。这些线程不绑定具体请求，而是通过事件驱动的方式，把 IO 结果回来之后的回调分发给对应业务逻辑处理。

同样拿餐厅来类比：这次改成了为数不多的几个协调员，他们不用全程站在某桌客人旁边，而是把“菜做好后请上菜”的要求记下来，然后继续去接待下一桌客人。客人或者后厨有消息了，协调员再回来处理。这样一来，同样 6 个协调员就能服务几百桌客人，而不是只能服务 6 桌。

所以 WebFlux 的价值在高并发、IO 密集场景下体现得最明显：

• 大量接口都在等待外部系统、数据库、消息队列等返回结果
• 并发连接数很高，比如网关、推送服务、行情推送、聊天服务等
• 资源受限，比如单台容器内存只有 4G，不希望线程数一直往上涨

如果你的业务是纯 CPU 密集计算，比如大量图片处理、加解密、复杂算法，那 WebFlux 的意义就不大，这种场景并发再高也主要是把线程跑满，并不存在大量空等。这也是我在实际选型中最重要的判断标准。

2. 核心概念速通：Mono、Flux 与背压

2.1 Mono 和 Flux：一个结果和无数个结果

Project Reactor 是 WebFlux 的响应式基础库，里面有两个核心容器：Mono 和 Flux。

Mono 表示一个“最多只有一个数据”的异步序列，类比成异步版本的 Optional。比如查询一个用户详情、删除一条数据、保存一条记录，返回 Mono 是很自然的。Flux 表示一个“可以有 0 到 N 个数据”的异步序列，类比成异步版本的 List 或 Stream，比如查列表、监听消息流、间隔推送数据。

举个例子：

Mono<String> one = Mono.just("hello"); Flux<Integer> many = Flux.range(1, 100);

这两个容器本身不会立刻执行，它们只是描述了“将来会有什么数据产生”。真正开始工作时，必须有人订阅它。在 WebFlux 的 Controller 里，框架自动完成了订阅动作，所以你只需要把 Mono 或 Flux 作为返回值返回即可。但从原生 Reactor 的角度理解“冷序列、惰性执行”这个特性非常重要——如果一段响应式代码始终不触发，往往不是逻辑写错了，而是根本没有订阅。

对数据流的变换主要通过操作符完成，常用的一些操作符：

• map：同步转换，把一个元素映射成另一个元素
• flatMap：每个元素对应一个 Mono/Flux，然后合并这些内部序列
• filter：过滤
• zip：把多个流的最新结果合并成一个结果
• delayElements：给整个流加固定间隔
• take：取前 N 个元素

2.2 背压：保护下游，而不是花哨名词

背压（Backpressure）是响应式编程里最常被提到的机制，也是最容易被忽略的。简单说，在响应式流中，数据不是发布者一股脑全推到订阅者那里，而是订阅者根据自己的消费能力，向发布者申请“我一次能处理多少数据”。这个申请动作就是 request(n)。

看到这里你可能会问：这不就是限流吗？不太一样。限流往往意味着主动丢弃一部分请求，或者强制控制速率。背压是本意上的“量力而行”，下游说我现在能处理 100 个，上游就先发 100 个，处理完了再申请下一批。

类比自来水管：厨房水龙头就是下游，水厂就是上游。如果水龙头开小，水厂即使输水能力再强，也不会把水管撑爆，因为水龙头的通水量天然形成了背压。

在代码里，limitRate是控制背压最常用的操作符：

Flux.range(1, 1000000) .limitRate(100) .map(...)

这表示下游每次只向上游请求 100 个元素。这里有个细节：limitRate(100)实际预取时会请求 75 个并留 25 个作为缓冲，这是 Reactor 的一个性能优化策略，目的是减少上下游之间频繁的 request 信号交互。

如果完全不关注背压，把百万级数据用flatMap直接全量展开，同时调用远程接口，可能会导致瞬间发出大量并发请求，把数据库或下游服务打挂。这类问题往往不是写在文档里的，而是线上故障时才会暴露。

3. 从 MVC 到 WebFlux 的一次接口改造

3.1 工程初始化与依赖陷阱

新建一个 WebFlux 工程项目，最直接的方式就是用 Spring Initializr 选择 WebFlux 依赖。如果用 Maven 手动加依赖，核心是引入：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency>

有一个非常经典的坑需要提醒：spring-boot-starter-webflux和spring-boot-starter-web最好不要同时存在于同一个工程里。如果两个都在，Spring Boot 默认会优先使用 Spring MVC，你可能写了半天的 Flux/Mono Controller，结果底层还是 Tomcat 阻塞模型，一切都白做了。我曾经见过一个团队在统一网关工程里同时引入两个 starter，排查了几天性能问题，最后发现服务器跑的根本不是 Netty。

判断当前应用到底是 MVC 还是 WebFlux 很简单：看启动日志。WebFlux 启动时会打印 Netty started，MVC 工程则会打印 Tomcat started。

3.2 第一个响应式接口：Controller 返回 Mono 和 Flux

下面用两个最简单的接口演示 Controller 应该怎么写：

@RestController @RequestMapping("/demo") public class DemoController { @GetMapping("/hello") public Mono<String> hello() { return Mono.just("hello") .delayElement(Duration.ofMillis(200)); } @GetMapping("/values") public Flux<String> values() { return Flux.interval(Duration.ofSeconds(1)) .map(i -> "value-" + i) .take(5); } }

第一个接口返回的是 Mono，内部通过delayElement模拟了 200ms 的延迟。注意这个延迟是基于 Netty 的定时调度实现的，不是把当前线程 sleep 住。在 MVC 场景下，一个 200ms 延迟的请求，对应 Tomcat 线程会被占住 200ms；在 WebFlux 里，这 200ms 内线程可以继续去处理其他请求的回调。

第二个接口返回的是一个每秒产生一个元素的无限流，我用take(5)限制了只取前 5 个，然后请求就正常完成。Flux.interval也是非阻塞定时器，不会影响 Netty 线程。

有个容易忽略的点：Controller 返回Flux<T>时，如果内部是一个无限流且没有take或者别的方式终止，请求会一直挂着，客户端等不到结束。之前调试过一个“响应式接口半天不返回”的问题，就是这个原因。

3.3 调用链改造：RestTemplate 换成 WebClient

WebFlux 工程里虽然也能勉强使用 RestTemplate，但那是完全反模式的。RestTemplate 是阻塞的，调一次远程接口就占住当前线程，哪怕上游接口响应要 3 秒，你的 Netty 线程就在这 3 秒里被占住不释放——这会让 WebFlux 的非阻塞优势荡然无存。正确做法是使用 WebClient，它是 Spring 官方的响应式 HTTP 客户端。

比如要在一个聚合服务里调用用户服务和订单服务，代码可以这样写：

@Service public class AggregateService { private final WebClient userClient; private final WebClient orderClient; public AggregateService(WebClient.Builder builder) { this.userClient = builder.baseUrl("http://user-service").build(); this.orderClient = builder.baseUrl("http://order-service").build(); } public Mono<UserOrderDTO> getUserOrder(Long userId, Long orderId) { Mono<UserDTO> userMono = userClient.get() .uri("/users/{id}", userId) .retrieve() .bodyToMono(UserDTO.class); Mono<OrderDTO> orderMono = orderClient.get() .uri("/orders/{id}", orderId) .retrieve() .bodyToMono(OrderDTO.class); return Mono.zip(userMono, orderMono) .map(tuple -> new UserOrderDTO(tuple.getT1(), tuple.getT2())); } }

这里最值得琢磨的是Mono.zip。两个远程调用在响应式模型下天然就是并行发起的，不需要像 MVC 里那样手动用线程池或者 CompletableFuture 去组合。在传统模型下，串行调两个接口耗时是相加的；在 WebFlux 配合 zip 后，耗时会接近两者的最大值。

改造调用链的时候，有一个阶段容易觉得别扭：以前在 Service 层直接拿到数据，现在拿到的都是 Mono/Flux，需要往上透传。这个模式要尽快适应——响应式编程本质上是让异步信号在整个调用链上一路传到底，中间一旦有某个环节又转成阻塞等待结果，响应式链条就断掉了。

4. R2DBC 数据访问：全链路非阻塞的最后一公里

4.1 为什么不能继续用 JDBC

如果 Controller 非阻塞、远程调用用 WebClient，但数据库访问还是 JDBC，那么整个响应式链路仍然不通。因为 JDBC 规范本身就是同步阻塞的，PreparedStatement.executeQuery()一说出来，调用线程就要一直等数据库返回结果。

可以理解为高速公路前面一段都畅通，结果最后一公里是土路，车流依然会堵在出口。数据库访问往往是请求链路中耗时最长的 IO 操作，这一环不换成响应式驱动，其他环节做的非阻塞化几乎白费。

R2DBC（Reactive Relational Database Connectivity）就是为解决这个问题出现的。它是一个响应式数据库访问协议，MySQL、PostgreSQL 都有相应驱动支持。注意，R2DBC 并不是 JDBC 的响应式包装，而是从协议层面重新实现的底层驱动。

在 Spring Boot 工程里，引入依赖后配置示例：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-r2dbc</artifactId> </dependency> <dependency> <groupId>org.aspectj</groupId> <artifactId>aspectjweaver</artifactId> </dependency>

数据库驱动按需引入，比如 MySQL 使用：

<dependency> <groupId>com.mysql</groupId> <artifactId>mysql-connector-j</artifactId> <scope>runtime</scope> </dependency>

注意，MySQL 的 R2DBC 驱动坐标不同，需要引入io.asyncer:r2dbc-mysql这类驱动包。application.yml 配置示例如下：

spring: r2dbc: url: r2dbc:mysql://localhost:3306/demo username: root password: 123456

4.2 Spring Data R2DBC 的实战写法

Spring Data R2DBC 提供了一套模仿 Spring Data JPA 的 Repository 接口写法，方法返回类型天然支持 Mono 和 Flux：

public interface UserRepository extends ReactiveCrudRepository<User, Long> { Flux<User> findByStatus(Integer status); Mono<User> findFirstByUsername(String username); }

Service 层使用时直接返回响应式类型：

@Service public class UserService { private final UserRepository userRepository; public UserService(UserRepository userRepository) { this.userRepository = userRepository; } public Flux<UserDTO> listActiveUsers() { return userRepository.findByStatus(1) .map(user -> new UserDTO(user.getId(), user.getUsername())); } }

这一段流程和 JPA 非常像，但有一个关键区别：R2DBC 中没有一级缓存，没有懒加载代理，也没有持久化上下文。你查询出来的实体就是纯粹的数据对象，离开 Repository 方法之后就跟数据库没有任何关系了。所以以前依赖 JPA 缓存和懒加载的各种习惯，在 R2DBC 下都必须重新审视。

4.3 事务、缓存与 N+1 的响应式版本

先说事务。在响应式编程里，事务边界不像 MVC 那样由线程绑定，而是绑定在响应式链路上。直接给方法加@Transactional在纯 Spring WebFlux + R2DBC 应用里不一定生效，必须确认工程里配置的是ReactiveTransactionManager而不是传统事务管理器。

如果是多条写操作需要放在同一个事务里，TransactionalOperator是更灵活的手动方式：

@Autowired private TransactionalOperator transactionalOperator; public Mono<Void> createUserWithOrder(User user, Order order) { return transactionalOperator.execute(status -> userRepository.save(user) .then(orderRepository.save(order)) .then() ); }

这样一组写操作会被纳入同一个事务，任何一步失败都会回滚。

再说 N+1 查询问题。JPA 时代有懒加载，表面上写一个对象图查询很丝滑，实际上可能触发大量子查询。响应式时代没有懒加载，你显式做关联查询的时候，很容易写出一个“嵌套 flatMap 地狱”，比如：

userRepository.findAll() .flatMap(user -> orderRepository.findByUserId(user.getId()).collectList())

这段代码本身没问题，但flatMap默认并发数是 256，也就是一次最多同时发出 256 个查询。如果你的用户量很大，这个并发很容易打爆数据库。调优方法是显式限制并发数：

userRepository.findAll() .flatMap(user -> orderRepository.findByUserId(user.getId()).collectList(), 16)

这是我强烈建议记住的一个参数。很多响应式项目在测试环境没暴露问题，一上线就被数据库连接池压垮，原因就在这里。

5. 调度器与并发模型：决定性能的天平

5.1 四类 Schedulers 怎么选

Reactor 内置了几种调度器，常见的主要有四类，可以整理成一张表快速对照：

使用方式一般就是subscribeOn或publishOn操作符：

Mono.fromCallable(() -> legacyJdbcDao.getById(1)) .subscribeOn(Schedulers.boundedElastic());

这里插一个重要原则：响应式编程并不是真的“禁止任何阻塞操作”，而是不让阻塞操作发生在关键的 Netty 事件循环线程上。如果老代码里确实有一段绕不开的 JDBC 或同步 SDK，正确姿势是用Mono.fromCallable包一层，扔到 boundedElastic 线程池里去执行。

5.2 subscribeOn 和 publishOn 的线程切换真相

这两个操作符特别容易混淆。subscribeOn影响的是源头发布者的订阅和执行线程，也就是“数据是从哪个线程开始产生的”；publishOn影响的是它下游所有操作符的线程，也就是“后面的一段链子在哪个线程上跑”。

简单理解：subscribeOn管出生地，publishOn管搬迁。一次响应式链路里如果有多段不同性能特征的处理，可以在中间插入publishOn做线程切换。比如数据库查询后数据量很大，计算逻辑放在 parallel 线程池；需要落库保存时又切回 boundedElastic。

线程切换本身是有开销的，不要在一个长链条里反复切换。我见过有人把几十个publishOn堆在同一个流里，最后性能不但没提升反而更差。这种经验在压测时才能深刻体会。

5.3 响应式代码里的“隐形阻塞”

有些阻塞行为比较隐蔽，不是简单一个Thread.sleep看得出来。比如：

• 在 WebFlux 的 Controller 或 Service 里调用xxx.get()，比如CompletableFuture.get()，会立即阻塞当前线程
• 使用LinkedBlockingQueue.take()等待数据
• 在 lambda 里执行了同步文件 IO
• 与某个同步 RPC SDK 交互，比如一些老旧的 Dubbo/Thrift 客户端

这些代码混进响应式链路后，表现往往很相似：接口偶尔高延迟、线程数异常增长、CPU 不高但整体吞吐很低。

一个开发期非常有用的工具是 BlockHound。它会在启动时织入检测逻辑，当你在 Netty 事件循环线程上执行了阻塞操作时直接抛异常。集成方式：

<dependency> <groupId>io.projectreactor.tools</groupId> <artifactId>blockhound</artifactId> </dependency>

启动入口加一行：

BlockHound.install();

这个工具不一定适合生产环境全量开启，但开发环境和压测环境强烈建议打开。它能很直观地暴露出所有“试图占住 event loop 线程不放”的代码。

6. 错误处理与问题定位：响应式代码的兜底姿势

6.1 onErrorResume 等错误处理操作符的边界

响应式链路的特点是错误也是异步信号，你可以把它想象成数据流里的一个特殊事件。常用错误处理操作符有这几个：

• onErrorReturn：出错了返回一个默认值
• onErrorResume：出错了用另一条 Publisher 的结果兜底
• doOnError：只感知错误，比如打日志，不改变结果
• retryWhen：按策略重试

实际项目里最常用的组合是onErrorResume加上doOnError打日志：

return userService.getById(id) .doOnError(e -> log.error("query user failed", e)) .onErrorResume(NotFoundException.class, e -> Mono.just(Result.noData("user not found")));

一个容易踩坑的点是：onErrorResume如果放在最外层，会把上游所有异常全部吞掉；如果放在flatMap内部，则只影响当前子流的错误。比如要循环调远程接口，某个子调用失败了不想让整个流中断，就更适合把兜底写在 flatMap 里面：

Flux.just("a", "b", "c") .flatMap(id -> remoteService.call(id) .onErrorResume(e -> Mono.empty()));

这里Mono.empty()表示这个子任务没有任何结果，不会影响其他元素的处理。

6.2 Hooks.onOperatorDebug 与 checkpoint 定位堆栈

响应式编程一个让老手都头疼的问题是：异常堆栈往往看不到真正的业务代码位置，因为异步调用链在不同线程之间切换，栈信息已经丢了。这时有两条思路：

第一种是全局调试钩子，在应用启动时执行：

Hooks.onOperatorDebug();

开启后每个操作符都会记录额外的装配信息，报错堆栈会详细很多。不过这个开关有较大的性能开销，只能用于测试环境，绝对不能默认开在生产环境。

第二种是针对关键链路的 checkpoint，更精确也更有性价比：

return userService.getById(id) .checkpoint("查询用户详情") .map(...);

当这个链路报错时，日志里会明确标记出“查询用户详情”这个检查点，方便你在一个复杂调用链中快速锁定是哪一段出了问题。

我自己在排查响应式问题时，一般流程是：复现问题 → 开启Hooks.onOperatorDebug()拿到完整装配链 → 定位后用checkpoint固化在代码里。这样测试期和线上的问题定位速度会快很多。

6.3 日志链路追踪：ThreadLocal 在响应式里不可靠

这个问题非常隐蔽。在传统 MVC 下，一个请求从进入到返回基本绑定在一个 Tomcat 线程上，日志框架的 MDC 也绑定在线程上，所以traceId能顺着同一条线程传递。但响应式链路会在不同线程之间切换，ThreadLocal的内容会丢失，直接导致日志链路断裂、traceId 对不上。

正确的做法是使用 Reactor Context 来传递与请求相关的信息。React 的上下文会跟随整个数据流，即使切换线程也不会丢。简单的代码示例：

@GetMapping("/users/{id}") public Mono<Result<UserDTO>> getUser(@PathVariable Long id) { return userService.getById(id) .contextWrite(ctx -> ctx.put("traceId", TraceIdGenerator.generate())); }

在具体业务代码里读取：

return Mono.deferContextual(context -> { String traceId = context.get("traceId"); // 这里就可以把 traceId 写进日志或透传到下游服务 return actualQuery(); });

这个模式理解起来有一点门槛，但它是在响应式应用里做链路追踪的基础。如果项目里接入了 Micrometer Tracing，它内部也是基于 Reactor Context 来实现跨度传递的，原理是同一个东西。

7. 常见问题与排查速查表

7.1 高频问题速查

把很多人问我比较多的问题整理成一张速查表，后续排查时可以对照着看：

7.2 迁移实践中的经验清单

基于自己的实际经验，从 Spring MVC 迁移到 WebFlux 时有几条建议特别想说：

不要试图一次性把整个应用从 MVC 改成 WebFlux。响应式改造是一个高风险工程，更稳妥的方式是拆出某个高并发、IO 密集的模块先做试点。比如先做一个独立的网关聚合服务，把原来 Service 里的远程调用改成 WebClient，验证收益，也积累团队经验。等团队对 Mono、Flux、背压、线程模型都有了统一认知，再逐步扩大范围。

响应式代码的 Code Review 重点和 MVC 不太一样。MVC 主要看事务边界、缓存策略、SQL 效率；响应式还要额外关注操作符使用是否合理、flatMap 并发是否受限、是否有隐蔽阻塞、错误处理放在哪一层。这些点如果不盯住，很容易写出“看起来是响应式，实际上到处阻塞”的伪响应式代码。

另外建议把publishOn和subscribeOn的使用规范定得很保守。不是每个操作都需要切线程，能少切就少切。新同学刚接触时特别喜欢到处加调度器，实际上线程切换多了，性能开销比阻塞调用还可能更严重。

8. 写在最后：什么项目我会坚持选 WebFlux，什么项目我会拒绝

做 WebFlux 选型这些年，我现在的原则其实越来越朴素：先问一句，“这个请求到底在等什么”。如果绝大多数请求都在等 IO——等数据库、等远程接口、等消息队列、等客户端下发数据——那么响应式方案值得认真考虑。网关、推送网关、行情服务、实时聚合接口，这些场景换 WebFlux 之后收益非常明显。

反过来，如果你的团队完全没有响应式编程经验，业务又只是简单的增删改查，数据库访问量不大，接口逻辑也不复杂，那盲目切换 WebFlux 属于给自己找麻烦。响应式编程的调试门槛更高，对团队整体能力的要求也更实在，如果只是为了技术热点而迁，很多平时看起来很简单的改动都可能变成一场持久战。

我个人从第一次响应式改造之后，对新项目的技术选型思路变化挺大的：不再执着于“必须用哪套框架”，而是先判断业务瓶颈到底在等待还是在计算。想明白了这一点，再用 WebFlux 或 Spring MVC 都只是顺手的选择。如果你正准备在新的接口模块里尝试响应式，建议先把这篇文章里的示例代码跑一遍，再对照速查表过一遍自己项目的调用链，至少能避开大部分常见的坑。