企业官网建设流程全解析

先说个直观感受：我接手过一个并发不算低的内部工具平台，主要操作是查库、拼数据、返回 JSON。原系统用的 Spring MVC + Tomcat，压测到 800 QPS 时线程数已经冲到 400 多，线程池一直在创建新线程，响应反而变慢了。后来把核心链路切到 Spring WebFlux + R2DBC，同一台 4 核 8G 的机器，QPS 能跑到 2000 左右，线程数稳定在几十。这里面的差距不是单次请求变快了，而是 WebFlux 换了一种等 I/O 的方式。

后端服务的大部分时间其实都在等待数据库返回、等待下游 HTTP 响应。传统的 Servlet 模型里，一个请求从进入到返回要占住一个线程，如果这个线程在等数据库，那它就做不了任何别的活。WebFlux 把“等待”改成了“监听”：请求来了先注册回调，线程立刻回来处理下一个请求；数据到位后再触发后续逻辑。这就是响应式编程，核心是异步、非阻塞、背压。

如果你已经接触过 Java 的 Stream、JDK 的 CompletableFuture，或者前端的 Promise，那理解 WebFlux 会很快。它面向的是数据流：一个流可以发出 0 个、1 个或多个元素，你可以对流做变换、过滤、合并，然后再订阅。背压是消费速度和生产速度之间的阀门，防止下游处理不过来被数据淹没。下面我从设计到实操，把整条技术链路拆开讲。

1. 响应式编程到底在解决什么问题

1.1 传统线程模型的资源浪费

传统 Java Web 应用大多跑在 Servlet 容器上：Tomcat 默认 200 个线程，每个请求独占一个线程，直到响应写完才释放。数据库查询 200ms，这段时间线程什么也不干，就挂在连接等待上。并发一涨，线程不够就排队，线程数疯狂增加又带来上下文切换开销。更有意思的是，很多系统在压测时 CPU 利用率不高，但延迟很难看，因为大量线程阻塞在 I/O 上。这个模型不是不好，而是面对现代高并发 I/O 密集场景，性价比太低。

我用一个简单的计算来说明问题：假设一个请求平均耗时 250ms，其中 200ms 是在等数据库，50ms 是 CPU 计算。传统模型下，一个线程处理一个请求，线程被占住 250ms，那么 200 个线程每秒最多能处理 200 / 0.25 = 800 个请求。如果能把等待数据库的 200ms 省下来，让同一个线程在这段时间里去处理其他请求，同样 200 个线程的吞吐量会完全不同。WebFlux 做的事，就是让线程不被 I/O 等待牵着走，它把“等一会”的时间用来处理别的任务。

1.2 非阻塞 I/O 如何复用线程

WebFlux 默认跑在 Netty 上，Netty 使用少量 EventLoop 线程（一般是核数乘 2）完成所有网络读写。EventLoop 线程不会因为某个连接没数据就停在那等，而是注册好“可读”事件后继续处理其他连接，事件来了再回调。这里有一个必须刻在工位上的结论：一旦某个回调里有阻塞调用，比如同步查 JDBC，那么整个 EventLoop 组都会被卡住，别的请求全部排队。

所以，WebFlux 的响应式必须做到全链路非阻塞。访问数据库不能用传统的 JDBC，得用响应式的 R2DBC，或者采用响应式驱动的 NoSQL 客户端；调用下游 HTTP 不能用 RestTemplate，得用 WebClient。这也是为什么很多人一开始只改了 Controller 返回类型，后面发现性能没提升——因为真正的阻塞点还在数据库和外部调用上，只要有一个环节是阻塞的，前面省下来的线程资源就全被浪费了。

1.3 背压是怎么回事

背压是响应式流规范里最容易被忽视、却是最核心的机制。生产者发出一堆元素，消费者处理不过来的时候，可以主动告诉上游：“我先要 10 个，剩下的暂时别发。”这样即使数据源是无限流，内存也不会爆。一个常见的场景：从数据库查询 100 万行数据，传统方式要么一次全加载，要么分页反复查询，响应式流可以每读出一批就推给下游，同时根据下游处理能力调节读取节奏。背压不是延迟或丢弃数据，而是一种流量控制信号。

响应式流规范定义了 Publisher、Subscriber、Subscription 和 Processor 四种角色。订阅时 Subscriber 会收到一个 Subscription，随后通过subscription.request(n)声明自己本轮能处理多少个元素；上游每产生一个元素都会检查有没有剩余额度，有了才往出发送。Reactor 里我们用 Mono 和 Flux 就自动享受了这套协议，平时不需要手写这些接口，但理解它有助于排查“为什么我的 Flux 突然不继续发出了”——多半是消费者限制了额度，而逻辑里又不再继续请求了。

2. WebFlux 的核心概念与编程模型

2.1 Mono 和 Flux：像写 Stream 一样写异步

Reactor 是 WebFlux 的底层库，它带来两个核心类型：Mono 表示 0 到 1 个元素的异步序列，适合单个结果或空结果；Flux 表示 0 到 N 个元素的异步序列，适合集合、流式数据。和 Java Stream 不同，它们是懒加载的：声明操作符的时候什么都不会发生，只有真正调用subscribe()后数据才会开始流动。写过 Stream 的人上手很快，但要注意闭包里的变量语义，因为整个链路的执行可能是异步的。

举个例子：

Flux.just("user-1", "user-2", "user-3") .map(id -> "hello: " + id) .subscribe(System.out::println);

这段代码会输出三条消息。换成数据库调用的话，map 里可以返回 Mono，然后用 flatMap 来扁平化多个异步结果：

flux.flatMap(id -> userRepository.findById(id))

flatMap 不会等前一个 Mono 结束再订阅下一个，而是同时订阅所有输入元素，因此顺序不保证。要保持顺序，可以用concatMap或flatMapSequential。实战中，如果依赖外部接口且想保留结果顺序，用concatMap；如果希望并发调用，用flatMap但注意控制并发度。

2.2 调度器与线程模型

WebFlux 常用的调度器有这几个：

• Schedulers.immediate()：在调用者线程执行，不额外切换线程。
• Schedulers.single()：单线程，适合定时任务这类轻量场景。
• Schedulers.parallel()：固定大小的线程池，默认核数，适合 CPU 计算密集任务。
• Schedulers.boundedElastic()：弹性线程池，主要为阻塞型操作而设计。

默认情况下，WebFlux 的响应式链路跑在 Netty 的 EventLoop 线程上，所以处理链路上不能再有block()操作。如果确实有阻塞调用，比如遗留的 JDBC 查询，需要用subscribeOn或publishOn把它切到boundedElastic：

Mono.fromCallable(() -> legacyJdbcQuery()) .subscribeOn(Schedulers.boundedElastic()) .flatMap(data -> ...)

这个操作把阻塞查询放到独立的弹性线程池里，短时间内不会拖垮 EventLoop。但也不能滥用boundedElastic，它的线程数上限可以很大，如果每个请求都往里塞阻塞逻辑，线程照样会打满，延迟照样飙升。

2.3 注解式路由与函数式路由

WebFlux 提供两种路由方式。一种是像 Spring MVC 一样的注解式：@RestController、@GetMapping等。另一种是函数式RouterFunction。注解式对从 MVC 迁移的人来说最友好，代码差异最小；函数式更灵活，可以在一个方法里集中定义一组路由规则，适合做网关、代理层这类动态路由。我通常建议项目里主用注解式，少数特殊路径用函数式。

例如一个简单的函数式路由定义：

@Bean RouterFunction<ServerResponse> routes(UserHandler handler) { return route() .GET("/users", handler::list) .POST("/users", handler::create) .build(); }

它通过 HandlerFunction 接收ServerRequest、返回Mono<ServerResponse>。这种写法对于做参数透传、统一封装特别方便。不过在参数校验时，注解式能直接复用 Spring 的 Validation，函数式要手动处理，小项目无所谓，大项目建议统一用一种风格。

3. 实操：用 WebFlux + R2DBC 搭一个响应式 CRUD

3.1 依赖与工程配置

在 Spring Boot 工程里引入 WebFlux 和 R2DBC：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-webflux</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-r2dbc</artifactId> </dependency> <dependency> <groupId>org.mariadb</groupId> <artifactId>r2dbc-mariadb</artifactId> <scope>runtime</scope> </dependency>

如果数据库是 MySQL，可以用org.mariadb:r2dbc-mysql之类的驱动，具体版本由 Spring Boot 的 BOM 管理。只引入 WebFlux 还不够，数据访问层必须用响应式驱动，这一步决定全链路是否真的非阻塞。

配置文件里连接池的初始大小不要照抄 JDBC 习惯：

spring: r2dbc: url: r2dbc:mariadb://localhost:3306/demo username: root password: example pool: initial-size: 10 max-size: 30 max-idle-time: 30s

连接池别配太大，因为每个连接都是异步复用的，一百个并发请求需要的连接数远小于传统 JDBC。后面你会看到，连接数越少越能暴露真正的瓶颈。

3.2 实体和响应式 Repository

以一个 User 实体为例：

@Table("users") public class User { @Id private Long id; private String name; private Integer age; // getter/setter 省略 }

Repository 继承ReactiveCrudRepository：

public interface UserRepository extends ReactiveCrudRepository<User, Long> { Flux<User> findByAgeGreaterThan(int age); }

Spring Data R2DBC 会自动为接口实现响应式方法，返回值是 Mono 或 Flux。相比 JPA，它没有懒加载、一级缓存这些复杂机制，模型更简单，SQL 更可控，反而适合喜欢直接写 SQL 的团队。

3.3 Controller 与 Service 保持响应式

Controller 直接返回 Mono 和 Flux：

@RestController @RequestMapping("/users") public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } @GetMapping public Flux<User> list() { return userService.list(); } @GetMapping("/{id}") public Mono<User> get(@PathVariable Long id) { return userService.get(id); } @PostMapping public Mono<User> create(@RequestBody User user) { return userService.create(user); } }

有一个很常见的初学错误：为了在 Controller 里做 try-catch，调用.block()把 Mono 变成对象。一旦这么做，请求就回到了同步模式，而且block()跑在 Netty 线程上还会带来严重告警。正确的做法是让框架订阅返回值，在链路里用onErrorResume处理异常。响应式编程要求你接受“数据什么时候到不一定”这件事，把它交给下游去处理。

3.4 用 WebClient 调用下游接口

微服务里调用另一个 HTTP 接口，推荐用 WebClient。它是响应式的 HTTP 客户端，基于 Netty，不会像 RestTemplate 那样阻塞线程：

webClient.get() .uri("/api/orders/{userId}", userId) .retrieve() .bodyToFlux(Order.class) .collectList();

返回值是Mono<List<Order>>，在最终路由层可以转换成 JSON 响应。注意，这里不要因为看着像同步就去包一层CompletableFuture，WebClient 本身已经异步，别画蛇添足。连接池的参数会在下一节详细说。

4. 性能调优与压测对比

4.1 线程池与连接池的关键参数

WebFlux 性能调优的第一步，是把 Netty 参数和连接池参数理清。Netty 的 EventLoop 线程数默认是 CPU 核数乘 2。如果机器 4 核，那 8 个 EventLoop 线程要服务所有请求。这本身不是问题，只要请求里没有阻塞操作。

对于 WebClient，可以用ConnectionProvider定制关键参数：

ConnectionProvider provider = ConnectionProvider.builder("http-pool") .maxConnections(500) .pendingAcquireTimeout(Duration.ofSeconds(30)) .maxIdleTime(Duration.ofSeconds(20)) .build(); WebClient client = WebClient.builder() .clientConnector(new ReactorClientHttpConnector(HttpResources.get(), provider)) .build();

maxConnections决定最多同时建立多少连接，pendingAcquireTimeout是连接池暂时拿不到连接时的最大等待时间。不要以为连接数越大越好，响应式模式下连接被循环利用，连接数过多只会增加空闲开销。R2DBC 连接池同理，max-size可以保守一点，30 在很多场景下都够用。

4.2 压测案例与数据解读

我在模拟项目 X 里做过一组对照压测：两个 HTTP 接口，一个查单条数据，一个查列表并做聚合，数据库用同一套 MySQL。传统 Spring MVC（Tomcat 默认 200 线程）和 WebFlux + R2DBC 分别跑，并发 200、持续 1 分钟。

结果大致是这样的：MVC 版本平均延迟 118ms，线程数峰值接近 150，请求堆积严重时响应时间出现明显拐点；WebFlux 版本平均延迟 97ms，线程数稳定在 40 左右。更明显的差异在长连接场景：当有 1 万个客户端用 WebSocket 保持在线时，MVC 因为每个连接占一个线程，线程数很快被打满；WebFlux 的 EventLoop 可以轻松支撑几万个连接，这是它在实时推送和长连接场景下的核心优势。

另一个值得关注的参数是理论吞吐上限。4 核机器上 Netty 线程数约为 8，假设每个请求的 CPU 实际处理时间是 2ms，理论上限是 8 / 0.002 = 4000 QPS。传统模型用 200 个线程，如果每个请求总耗时 100ms，其中 95ms 是 I/O 等待，那它理论上限是 200 / 0.1 = 2000 QPS。实际测试因为上下文切换、GC、锁竞争等因素都会打折，但数量级差距已经说明问题：响应式适合把线程从 I/O 等待中解放出来，让 CPU 专注于真正该做的计算。

4.3 内存与背压限制

高吞吐下要关注队列和内存。flatMap的默认并发度是 256，意味着同一时间最多订阅 256 个元素。如果元素本身是大对象，比如很大的 JSON 或图片 Base64，建议调低并发度，或者用limitRate控制上游发送速率：

Flux.range(1, 1000) .limitRate(100) .flatMap(item -> process(item), 20)

limitRate(100)要求上游每轮最多发 100 个，flatMap的第二个参数 20 是最大并发订阅数。这样可以把内存峰值压下来。响应式并不意味着内存无限，恰恰相反，它把内存使用的控制权显式交给了开发者。我见过一个团队在 WebFlux 里把大列表直接返回，结果下游消费慢，内存疯狂增长，最后就是靠这几行参数调稳的。

5. 避坑指南：从 Spring MVC 迁过来的典型问题

5.1 一不留神就在 EventLoop 上阻塞了

最常见的问题，是在响应式链路里混入阻塞调用。比如在map里直接查了 JDBC，或者调了 RestTemplate：

userRepository.findById(id) // R2DBC，没问题 .map(user -> userService.fetchRemoteWithRestTemplate(user)) // 错误示例

RestTemplate 会阻塞当前线程。正确做法是用 WebClient 替代；实在没法替换的阻塞客户端，要通过subscribeOn(Schedulers.boundedElastic())切到独立线程池。注意一个容易混淆的点：subscribeOn会影响订阅时上游执行线程，因此后续flatMap里的代码默认也会跑在这个弹性线程池上。也就是说，你把阻塞调用切走了，但后续链路的执行位置也跟着变了，这对线程模型敏感的系统需要特别留意。

5.2 block() 不是不能用，但别乱用

WebFlux 里在响应式订阅之外调用block()是合法的，比如在main方法里获取结果，或者在启动完成后做一次性初始化。但在请求处理线程上绝对不能调用block()。如果你在 Controller 里写return userService.get(id).block()，WebFlux 就退化成同步模型了，而且block()在执行时可能抛出block()/blockFirst()/blockLast() are blocking, which is not supported in thread reactor-http-nio-*的警告，严重时请求全部超时。

记住一条简单的原则：返回类型保持 Mono / Flux，让框架帮你订阅。你如果发现自己在 Controller 里想拿“真实对象”，说明还停留在 MVC 的返回值思维里。响应式的接口设计应该从起点就接受“异步序列”，而不是在中途把它拽回来。

5.3 事务和 ThreadLocal 的坑

Spring 声明式事务@Transactional基于代理，在响应式里如果用 R2DBC，它内部会通过响应式事务管理器在订阅链路上绑定事务，传统线程本地事务跨线程就会失效。我见过一个真实的案例：A 同学把事务方法拆到另一个类里直接调用，结果因为代理不生效，数据库提交完全错乱。响应式事务不是不能用于@Transactional，但一定要确保它是通过 Spring AOP 调用的，而且整个链路属于同一个反应式事务上下文。

另一个大坑是 ThreadLocal。MDC日志追踪、RequestContextHolder、Spring Security 的SecurityContextHolder，这些在传统 MVC 中很自然；但响应式链路里线程会不断切换，ThreadLocal 里的值会丢失。解决办法有几个方向：用 Reactor 的contextWrite和ContextView传递上下文；MDC 可以在订阅链路上手动传递；Spring Security 提供了ReactiveSecurityContextHolder，千万别再用SecurityContextHolder.getContext()去拿登录用户。

5.4 异常处理和超时控制

响应式流必须显式处理异常。如果在 Flux 链路上抛了异常，但没人订阅错误，异常就会静默丢失，日志和监控都看不到。规范写法：

return repository.findAll() .onErrorResume(e -> { log.error("查询失败", e); return Flux.empty(); });

对超时控制，可以用timeout(Duration.ofSeconds(3))。数据库连接池耗尽时，R2DBC 会抛PoolExhaustedException，排查时先看连接池大小是否合理，再看是否有人在链路里做了阻塞操作导致连接被长时间占用。连接池的max-idle-time和max-life-time也建议设置成合理值，避免无效连接堆积。

6. 选型建议与个人体会

6.1 哪些项目适合 WebFlux

需要高并发长连接、事件驱动、流式处理的场景，WebFlux 的优势非常明显。比如网关、消息推送、聊天服务、行情推送、物联网设备接入、机器状态上报等。这类系统 I/O 密集且要保存大量连接，响应式模型能以少得多的线程支撑海量连接。如果你的服务要做多个下游微服务的调用聚合，也可以用 WebFlux 把并发调用链串起来，代码可读性比一堆CompletableFuture好看得多。

如果你的团队已经熟悉 Reactor，用它做微服务间的聚合层、批处理任务、实时数据处理，都是顺手的事。关键不在于“换了框架”，而在于“全链路是否都响应式化了”。

6.2 哪些项目不建议硬上

纯 CRUD 后台管理系统、大量 CPU 密集计算、团队对异步编程不熟悉，这些情况建议继续用 Spring MVC。CPU 密集任务在响应式模型下并不会自动并行，需要自己拆任务、控制调度器，复杂度不低；CRUD 项目并发量有限的，引入响应式只会增加学习成本和排障难度。尤其是后端团队如果只有一两个人，出一次诡异的异步 bug 可能就要排查一天，这时候稳定压倒一切。

6.3 渐进式迁移怎么做

不要“大爆炸”式重写。Spring Boot 应用中，classpath 同时存在 spring-boot-starter-webmvc 和 spring-boot-starter-webflux 时只能二选一，不能同时以两种类型运行。常见的做法是把新模块独立启动成 WebFlux 服务，旧服务通过 HTTP 或消息队列和它对接。我见过成功的迁移，都是先从网关、消息入口这类纯响应式模块开始的，业务核心留在 MVC 里，等团队熟练后再逐步替换。一开始就想着把整个系统换掉，往往会卡在事务、权限、日志追踪这些细节上。

6.4 最后分享一点经验

从我的经验看，WebFlux 的学习曲线不在写 Mono/Flux，而在改变“一个请求一个线程”的思维惯性。用好它的核心不是背操作符，而是把每个环节都当成流处理：数据库访问用 R2DBC，外部调用用 WebClient，消息队列用响应式客户端，全链路真正响应式才有意义。如果只是 Controller 返回 Mono，但 Service 里全是阻塞调用，那还不如老老实实用 MVC。

另外一个心得是，压测和监控一定要前置。响应式应用的线程数很低，压测时不能只盯着 QPS 和 CPU，还要看连接池等待时间、GC 和 Netty 的调度任务堆积。我曾因为只看到 CPU 不高，没注意 Netty 的 pending task 积压，结果请求延迟从几十毫秒涨到了两秒。这些指标在传统线程模型里往往不那么显眼，但在响应式下就是排查故障的第一现场。

如果你正在考虑迁到 WebFlux，我建议先写一个最小的冒烟用例：用 WebClient 开 1000 并发，持续 30 分钟，观察线程曲线和连接池指标。如果一切平稳，说明方案底子是稳的；如果频繁出现pendingAcquireTimeout，先调连接参数，再回头检查链路里有没有被忽略的阻塞点。响应式不是银弹，但它确实是现代后端在 I/O 密集场景下的一个重要选项。