企业官网建设流程全解析

从我开始接触WebFlux到现在，已经有大半年时间了。最开始触发我去系统性学习它的原因很现实：手上的某个内部服务，因为下游一个响应特别慢的第三方接口，导致Tomcat线程池被打满，整个系统在高峰期几乎动弹不得。那段时间我反复调过线程池参数、加过断路器，但总觉得只是在拖延问题，并没有真正解决“线程被白白占着等待”这件事。后来我彻底把Spring Boot WebFlux从零到尾学了一遍，并且在一个模拟业务上落地了响应式改造，才算真正理解了它的价值与代价。

这篇文章就是基于那段入门经历整理出来的，适合刚接触响应式编程、平时用Spring MVC比较多、但对WebFlux只有零散印象的朋友。我会从阻塞模型和非阻塞模型的差别讲起，然后带你把一个包含CRUD的响应式REST API完整写出来，最后分享我实际踩过的一些坑和性能对比结论。看完之后，你至少能判断自己的项目适不适合用WebFlux，也能写出第一个能跑起来的响应式应用。

1. 为什么需要Spring Boot WebFlux：一个慢接口引发的思考

1.1 传统Servlet模型到底瓶颈在哪

大部分Spring Boot应用默认使用Spring MVC，底层是Servlet容器（比如Tomcat）。这种模型的核心思路是“一个请求对应一个线程”。Tomcat默认有200个左右的工作线程，每个请求从进入到返回，都会一直占用其中一个线程。如果这个请求只是正常查数据库、算几个CPU指令，线程很快就能释放；但一旦请求需要等待第三方接口返回、等待消息队列确认、或者等待慢SQL执行，这个线程就只能干等着。

咱们用一个实际的例子算一笔账：假设某个接口需要调用外部系统，外部系统的平均响应时间是3秒。当QPS只有10的时候，同时刻就会有10个请求在等待这3秒，也就是同时占用10个线程，看起来没问题。但一旦QPS涨到80，你需要的线程数就接近240个，已经超过默认线程池上限了。后续的请求要么排队，要么直接超时失败。如果你再加10个这种慢接口，线程池很快就会被塞满，最后整个服务的所有接口全部遭殃，哪怕那个健康接口只需要几毫秒就能返回。

这就是阻塞模型最核心的代价：线程在等待外部资源的时候，既不能处理其他请求，又还在占用系统资源。你可能觉得JVM线程不算贵，但线程的创建、调度、上下文切换都是有成本的，当线程数超过CPU核心数太多时，系统大部分时间都花在切换上，真正干活的时间反而更少。

1.2 WebFlux换了一套什么玩法：事件循环与非阻塞IO

WebFlux默认运行在Netty上，使用的线程模型是事件循环。它的核心思路是从根本上抛弃“一个请求占一个线程”的绑定关系，改成少数几个线程处理大量请求。当一个请求发起IO操作时，事件循环线程不会原地等待，而是注册一个回调就立刻处理其他请求；等IO数据准备好了，再由事件循环线程继续执行后续逻辑。

这个模型很像你在餐厅吃饭的场景：传统模式是每位顾客配一个服务员，这个服务员从你点菜到上菜都站在你旁边等着，其他顾客没人管；非阻塞模式是服务员只负责记录订单，菜做好之后通过叫号通知你，服务员不用一直守着你。餐厅只需要少量服务员，就能服务比原来多得多的顾客。

WebFlux编程模型的底层是Reactor库，也就是Reactive Streams规范的一种实现。在这个模型里，数据不再是“取回来再处理”，而是以流的形式不断推送给你，你的代码负责描述“当一个数据到达时该做什么”。这样做的好处是：线程不等待、CPU不空转，在IO密集型场景下，同样资源的吞吐量可以高出很多。

1.3 关键抉择：不是所有项目都适合上WebFlux

我在入门之前听到过一句很中肯的话：WebFlux不是银弹，它解决的是特定类型的问题。如果你的场景属于下面这几种，用WebFlux可能比传统MVC更痛苦：

• 业务链路以CPU密集型为主，比如大量加解密、图像处理。此时线程等待不是瓶颈，CPU计算才是，非阻塞模型帮不上本质忙。
• 底层数据访问方式是传统JDBC和MyBatis，因为JDBC的API天然是阻塞的，你在WebFlux里用它，照样会在事件循环线程里阻塞，反而伤害整体机制。要真正响应式，得换R2DBC或响应式MongoDB驱动。
• 整个团队对响应式编程不熟悉，既有代码库又庞大，全面切换成本极高。
• 你的QPS不高，慢请求也不多，默认Tomcat完全撑得住，那就没必要为了“新”而折腾。

反过来，WebFlux真正发光发热的场景是：高并发网关、接口需要聚合多个下游慢服务、长连接推送、物联网数据接入、实时流处理服务，以及所有IO等待比重特别大的服务。如果用一句话概括选型原则，那就是：你的瓶颈如果是“等待外部IO”，WebFlux收益明显；如果瓶颈是“CPU计算本身”，收益就非常有限。

2. 从零搭建：第一个响应式应用诞生记

2.1 项目初始化与依赖选择

搭建Spring Boot WebFlux项目其实和普通Spring Boot项目非常像，你只需要引入spring-boot-starter-webflux，替换掉原来的spring-boot-starter-web就可以了。注意两个包不要同时引，否则Spring Boot会有两个自动配置同时生效，可能出现非常奇怪的Bean冲突。比如你在启动日志里看到同时加载了Tomcat和Netty，资源分配就会很混乱。

最小化的Maven依赖是这样：

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

启动之后，观察日志。如果你看到类似“Netty started on port 8080”的日志，说明当前应用的运行容器已经是Netty了。我见过很多新人，明明引入了WebFlux，但因为一些IDE模板同时保留了spring-boot-starter-web，最后跑起来仍然是Tomcat，这就完全没发挥出WebFlux的特性。

如果你用的IDE自带Spring Initializer，可以直接选择WebFlux依赖生成工程。这个过程中唯一要留意的是Java版本，建议使用JDK 17以上，Reactor和Boot的兼容性会更好。

2.2 第一个接口：Mono与Flux到底返回什么

习惯了Spring MVC的写法之后，第一次看到Mono和Flux回来时，最容易蒙住的地方是：返回值里没有直接的数据对象，而是一个“容器”。你需要理解，Mono和Flux在响应式世界里扮演的是“发布者”的角色，它们不是数据本身，而是描述数据什么时候会到来、以什么形式到来。

用一句话区分：

• Mono<T>：最多只会发出0或1个数据。适合表示单个对象、单个结果，比如一个查询结果、一次保存操作。
• Flux<T>：可以发出0到N个数据。适合表示列表、数据流、事件流，比如查询多条记录、消息订阅。
• 两者都可以发出错误信号，携带异常信息；也都可以为空，也就是没有数据地完成。

可以直接写一个最简单的接口试一试：

@RestController public class DemoController { @GetMapping("/hello") public Mono<String> hello() { return Mono.just("hello reactive") .delayElement(Duration.ofMillis(100)); } }

这里Mono.just("hello reactive")会立即产生一个包含字符串的Mono，delayElement会在发出数据之前延迟100毫秒。从客户端视角看，这个接口行为和普通接口没什么区别，但服务端在处理这个请求时，并不会有一个线程阻塞100毫秒，而是注册了一个定时任务就立刻去服务别的请求了。

2.3 用Flux写一个实时推送的接口

用一个稍微生动点的例子感受Flux的特性。假如你要开发一个股票行情推送接口，希望每秒钟向客户端推送一次最新价格，用Spring MVC写会比较别扭（通常要引入SSE或原生WebSocket），但在WebFlux里，Flux天生就能表达这种“持续不断的序列”。

@GetMapping(value = "/price", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<String> priceStream() { return Flux.interval(Duration.ofSeconds(1)) .take(10) .map(i -> "current price: " + (100 + i * 2)); }

这段代码会每隔1秒输出一个价格字符串，最多输出10次，客户端通过SSE技术可以实时看到数据推送。Flux.interval是Reactor提供的一个定时发布器，它内部基于时间调度，而不是阻塞线程。你如果把这些数据打印出来，会非常直观地感受到“流”这个概念的含金量。

3. 把CRUD搬到响应式世界：一个真实业务接口的完整实现

3.1 先设计一个内存版数据仓库

为了不引入额外的数据库配置，先用一个简单的ConcurrentHashMap模拟数据存储。真实的响应式工程通常会用响应式MongoDB或R2DBC，但内存版更容易帮助你理解“响应式代码怎么组织”。

先定义一个实体类，我们叫它Article，包含ID、标题和内容三个字段，老实写getter、setter就行。然后建一个仓储接口：

@Repository public class ArticleRepository { private final Map<String, Article> store = new ConcurrentHashMap<>(); public Flux<Article> findAll() { return Flux.fromIterable(store.values()); } public Mono<Article> findById(String id) { return Mono.justOrEmpty(store.get(id)); } public Mono<Article> save(Article article) { return Mono.justOrEmpty(store.put(article.getId(), article)) .defaultIfEmpty(article); } public Mono<Void> deleteById(String id) { return Mono.fromRunnable(() -> store.remove(id)); } }

这段代码里的几个细节值得展开。

Flux.fromIterable是把普通的集合包装成Flux流，数据会逐个发送给订阅者；Mono.justOrEmpty是处理可能为null的情况，如果store里没有对应ID，就产生一个空的Mono，这样后续可以根据是否有值返回404；Mono.fromRunnable则适合包装那种“只执行但不返回值”的操作，比直接写return Mono.empty()干净很多。

3.2 Service层：理解map与flatMap的区别

很多人学习WebFlux时卡在操作符上，其中map和flatMap的差异绝对是高频问题。我自己的理解是：

• map：把一个状态直接映射成另一个状态，函数是同步的，处理过程不会产生新的发布者。
• flatMap：把一个元素映射成另一个发布者，然后把这层发布者“拍平”合并到主链路里。适合调用异步方法、继续链式调用其他返回Mono或Flux的操作。

举例来说，如果我要根据文章ID取出实体，然后把实体转换为响应对象，这就是个纯同步映射，用map：

return articleRepository.findById(id) .map(article -> new ArticleResponse(article.getId(), article.getTitle()));

但如果保存一篇文章后，还需要根据保存结果继续查询一条日志，或者调用另一个返回Mono的方法，就要用flatMap了：

return articleRepository.findById(id) .flatMap(article -> articleRepository.save(article));

刚开始可以记一个简单口诀：如果函数返回的是普通数据，用map；如果函数返回的是Mono/Flux，必须用flatMap，否则会出现“嵌套发布者”这种很难缠的类型问题。

3.3 Controller层：写一个完整的REST API

下面这段代码展示了在WebFlux里怎么组织常见的CRUD端点。重点不是代码本身，而是每段代码背后的处理思路。

@RestController @RequestMapping("/articles") public class ArticleController { private final ArticleService articleService; public ArticleController(ArticleService articleService) { this.articleService = articleService; } @GetMapping public Flux<Article> list() { return articleService.list(); } @GetMapping("/{id}") public Mono<ResponseEntity<Article>> detail(@PathVariable String id) { return articleService.findById(id) .map(ResponseEntity::ok) .defaultIfEmpty(ResponseEntity.notFound().build()); } @PostMapping public Mono<Article> create(@RequestBody Article article) { return articleService.create(article); } @PutMapping("/{id}") public Mono<ResponseEntity<Article>> update(@PathVariable String id, @RequestBody Article article) { return articleService.update(id, article) .map(ResponseEntity::ok) .defaultIfEmpty(ResponseEntity.notFound().build()); } @DeleteMapping("/{id}") public Mono<ResponseEntity<Void>> delete(@PathVariable String id) { return articleService.deleteById(id) .then(Mono.just(ResponseEntity.noContent().build())); } }

和Spring MVC相比，整个Controller几乎没有本质差别，最大的改变是返回值从“直接给实体”变成了“给Mono/Flux包装的实体”。其中defaultIfEmpty的作用非常关键，它负责处理查找结果为空的情况，把Mono