# WebFlux 缓存分层实战：从 304 到 Redis 的工程判断

```text
旧方案：每次请求都查库、都序列化、都回传完整 JSON
冲突：PetType/Specialty/Vet 几乎不变，但客户端反复拉取
后果：带宽浪费、服务端重复计算、接口 p95 被无意义抬高
```

很多团队一听到“读接口优化”，第一反应就是上 Redis。

我是老李，在深圳南山科技园做架构支持，经常看到项目把 Redis 当万能缓存，却忽略了浏览器和网关已经在重复传输同一份响应。

PetType、Specialty、Vet 这类基础数据，可能一周都不改一次，但每次打开页面都会被重新下载一遍。

如果客户端已经有一份完全相同的响应，为什么还要再传一次？

如果服务端能证明数据没变，为什么还要重新查库、重新序列化？

如果选错缓存层次，会不会 Redis 上了、性能没提升，反而多了一个故障点？

# 01、故事

```text
周二 14:30→深圳南山科技园某宠物医院平台研发部→给基础数据接口做性能优化→前端说页面慢，后端说接口不慢，运维说带宽涨了
```

周二下午两点半，我坐在南山科技园一栋写字楼的 23 层会议室里。

任务是给 PetType、Specialty、Vet 三个基础数据接口做一次性能优化。

前端负责人把监控截图投到屏幕上，说页面首次加载要 2.8 秒，其中基础数据接口占了 1.1 秒。

后端负责人立刻打开 JProfiler，说这三个接口平均响应只有 180 毫秒，数据库查询也就 60 毫秒。

运维负责人补了一句：最近三个月出口带宽涨了 40%，但业务量只涨了 15%。

三个人说的都是事实，但结论互相矛盾。

我打开浏览器开发者工具，看到同一个 Vet 列表接口在五分钟内被请求了六次，每次响应体都是 84KB。

数据没变，但每次都在完整传输。

> 会议室的投影仪亮着
> 三个角色的数据在打架
> 我盯着 Network 面板
> 六次请求，六份相同的 84KB

# 02、问题

```text
需求变化：基础数据接口要支撑更高并发和更低延迟
冲突：数据几乎不变，但客户端和服务端都在重复劳动
后果：带宽被无效传输占用，服务端 CPU 花在重复序列化上，Redis 即使上了也救不了传输层
```

这三个接口的响应体在一天内几乎没有变化。

PetType 只有十几种宠物类型，Specialty 只有几十个兽医专业，Vet 列表虽然大一些，但人员变动频率极低。

当前实现是典型的“每次请求都全量返回”：Controller 查库、Service 组装、Jackson 序列化、HTTP 响应体完整回传。

客户端即使已经缓存了同样的数据，也会因为缺少缓存协商机制而被迫重新下载。

服务端即使知道数据没变，也会因为缺少条件请求处理而重复执行整个调用链。

可验证的验收标准是：在数据未变化时，客户端第二次请求应收到 304 状态码，响应体为空，服务端不再执行数据库查询。

> 数据像一块不会动的石头
> 请求却像潮水一遍遍冲刷
> 每次冲刷都带走同样的沙粒
> 而岸边的人以为自己在搬运新的东西

# 03、原理

```text
HTTP 缓存协商：客户端带着验证器（ETag/Last-Modified）问服务端“变了吗”，服务端回答“没变，用你本地那份”
```

HTTP 缓存的核心不是“存”，而是“协商”。

服务端在第一次响应时，可以带上 ETag 和 Last-Modified 两个验证器。

ETag 是响应内容的指纹，通常用内容哈希或版本号生成。

Last-Modified 是资源的最后修改时间，精度到秒。

客户端在后续请求中，会通过 If-None-Match 带上 ETag，通过 If-Modified-Since 带上 Last-Modified。

服务端收到条件请求后，先比较验证器：如果匹配，直接返回 304 Not Modified，响应体为空。

如果不匹配，返回 200 和新的响应体，同时带上新的验证器。

一个反直觉的判断是：304 响应本身并不能减少服务端的数据库查询，除非你在服务端代码里显式地短路。

HTTP 缓存只解决了传输层的问题，计算层的问题需要 Spring Cache 或 Redis 来配合。

另一个反直觉判断是：对于低变化数据，HTTP 缓存带来的收益往往比 Redis 更大，因为它省掉的是网络传输，而不是内存读取。

> 验证器像一把尺子
> 客户端拿着尺子问：还是原来的长度吗
> 服务端看一眼：是，别传了
> 于是 84KB 变成 0KB

# 04、架构

```text
浏览器/网关 → 条件请求（If-None-Match/If-Modified-Since）→ WebFlux Controller → 短路判断 → 304 或 200 + 新验证器
```

这个方案分三层。

第一层是 HTTP 缓存层，由浏览器、CDN 或反向代理参与，负责避免重复传输相同内容。

第二层是 Spring Cache 层，由服务端本地缓存参与，负责避免重复执行数据库查询和对象组装。

第三层是 Redis 层，由分布式缓存参与，负责在多个服务实例之间共享缓存结果。

三层的边界很清楚：HTTP 缓存解决“客户端到服务端”的传输问题，Spring Cache 解决“服务端内部”的计算问题，Redis 解决“多实例之间”的共享问题。

收益是：命中 HTTP 缓存时，服务端甚至可以不执行任何业务逻辑。

代价是：需要为每个资源设计稳定的验证器生成策略，否则可能返回错误的 304。

适用条件是：数据变化频率低，且客户端能够存储和重新验证缓存。

对于实时性要求极高的接口，这套方案不适用。

> 三层像三道闸门
> 第一道挡住重复的字节
> 第二道挡住重复的计算
> 第三道挡住重复的跨实例查询

# 05、第一版实战

```text
环境：JDK 17 + Spring Boot 3.2 + WebFlux + R2DBC + PostgreSQL 15
配置：application.yml 开启缓存头
代码：PetTypeController 返回 ResponseEntity 并带 ETag
启动：mvn spring-boot:run
验证：curl 第一次 200，第二次 304
```

先写第一版，只做 HTTP 缓存层。

在 `pom.xml` 中确认依赖：

```xml
<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.postgresql</groupId>
    <artifactId>r2dbc-postgresql</artifactId>
</dependency>
```

在 `application.yml` 中配置数据源：

```yaml
spring:
  r2dbc:
    url: r2dbc:postgresql://localhost:5432/petclinic
    username: postgres
    password: postgres
```

创建 PetType 实体：

```java
public record PetType(Long id, String name) {}
```

创建 Repository：

```java
public interface PetTypeRepository extends ReactiveCrudRepository<PetType, Long> {
}
```

创建 Controller，手动生成 ETag：

```java
@RestController
@RequestMapping("/api/pet-types")
public class PetTypeController {

    private final PetTypeRepository repository;

    public PetTypeController(PetTypeRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public Mono<ResponseEntity<List<PetType>>> list() {
        return repository.findAll()
                .collectList()
                .map(petTypes -> {
                    String etag = Integer.toHexString(petTypes.hashCode());
                    return ResponseEntity.ok()
                            .eTag(etag)
                            .cacheControl(CacheControl.maxAge(60, TimeUnit.SECONDS))
                            .body(petTypes);
                });
    }
}
```

启动应用：

```bash
mvn spring-boot:run
```

第一次请求：

```bash
curl -i http://localhost:8080/api/pet-types
```

示例输出：

```text
HTTP/1.1 200 OK
ETag: "7a3f9c2b"
Cache-Control: max-age=60
Content-Type: application/json
Content-Length: 482

[{"id":1,"name":"cat"},{"id":2,"name":"dog"}]
```

第二次请求，带上 If-None-Match：

```bash
curl -i -H 'If-None-Match: "7a3f9c2b"' http://localhost:8080/api/pet-types
```

示例输出：

```text
HTTP/1.1 304 Not Modified
ETag: "7a3f9c2b"
Cache-Control: max-age=60
```

成功标准：第二次请求返回 304，响应体为空。

但注意：这个版本仍然执行了数据库查询，因为 `repository.findAll()` 在 ETag 比较之前就执行了。

> 第一版像一座独木桥
> 桥的两端都站着人
> 一端说：数据没变
> 另一端却已经把河趟了一遍

# 06、排查

```text
诊断树：304 没生效 → 是没发条件请求，还是发了但服务端没短路？
分支一：客户端没发 If-None-Match → 检查 Cache-Control 和 ETag 是否真的返回
分支二：客户端发了 If-None-Match 但服务端返回 200 → 检查 ETag 生成逻辑是否稳定
分支三：返回 304 但数据库仍在查询 → 检查 Controller 是否在条件判断前就调用了 Repository
```

第一个问题：用 Postman 测试时，第二次请求没有自动带 If-None-Match。

现象是每次请求都返回 200，响应体完整。

怀疑是 Postman 默认不自动管理缓存。

检查方式：在 Postman 的请求头中手动添加 If-None-Match，值从第一次响应的 ETag 头复制。

证据：手动添加后，服务端返回 304。

根因：Postman 不是浏览器，不会自动存储和重新验证缓存。

修复：在 Apifox 中启用“自动缓存”或手动添加条件请求头。

第二个问题：ETag 生成不稳定。

现象是同一个数据集合，两次请求的 ETag 不同。

怀疑是 `List.hashCode()` 依赖元素顺序，而数据库返回顺序不稳定。

检查方式：连续两次请求，对比 ETag 值。

证据：两次 ETag 分别是 `7a3f9c2b` 和 `9d1e4f8a`，但响应体完全相同。

根因：`findAll()` 没有指定排序，PostgreSQL 返回顺序可能变化。

修复：在 Repository 中增加排序。

```java
public interface PetTypeRepository extends ReactiveCrudRepository<PetType, Long> {
    Flux<PetType> findAllByOrderByIdAsc();
}
```

**错误尝试：** 我一开始以为 304 会自动跳过数据库查询，于是在 Controller 里只加了 ETag，没有做任何短路逻辑。

结果用 SQL 日志一看，每次 304 请求都还在执行 SELECT。

这说明 HTTP 缓存层和计算层是分离的，不能指望 304 自动省掉查询。

> 我踩过的坑像路上的石子
> 每一颗都硌脚
> 但捡起来看
> 上面刻着：缓存分层不是魔法

# 07、优化

```text
V1：只加 ETag，304 时仍查库
证据：SQL 日志显示每次 304 请求都执行 SELECT
V2：在 Controller 中先比较 If-None-Match，命中则直接返回 304，不查库
```

优化目标：让 304 请求真正短路，不执行数据库查询。

在 Controller 中注入一个本地缓存，存储 ETag 和数据。

```java
@RestController
@RequestMapping("/api/pet-types")
public class PetTypeController {

    private final PetTypeRepository repository;
    private final Map<String, List<PetType>> localCache = new ConcurrentHashMap<>();
    private final Map<String, String> etagCache = new ConcurrentHashMap<>();

    public PetTypeController(PetTypeRepository repository) {
        this.repository = repository;
    }

    @GetMapping
    public Mono<ResponseEntity<List<PetType>>> list(
            @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch) {

        String cachedEtag = etagCache.get("pet-types");
        if (cachedEtag != null && cachedEtag.equals(ifNoneMatch)) {
            return Mono.just(ResponseEntity.status(HttpStatus.NOT_MODIFIED)
                    .eTag(cachedEtag)
                    .build());
        }

        return repository.findAllByOrderByIdAsc()
                .collectList()
                .map(petTypes -> {
                    String etag = Integer.toHexString(petTypes.hashCode());
                    etagCache.put("pet-types", etag);
                    localCache.put("pet-types", petTypes);
                    return ResponseEntity.ok()
                            .eTag(etag)
                            .cacheControl(CacheControl.maxAge(60, TimeUnit.SECONDS))
                            .body(petTypes);
                });
    }
}
```

这样，当 If-None-Match 命中时，直接返回 304，不执行 `repository.findAllByOrderByIdAsc()`。

验证：

```bash
curl -i -H 'If-None-Match: "7a3f9c2b"' http://localhost:8080/api/pet-types
```

示例输出：

```text
HTTP/1.1 304 Not Modified
ETag: "7a3f9c2b"
```

同时观察 SQL 日志，确认没有执行 SELECT。

> 优化像给独木桥加了一道闸
> 闸门看到熟人
> 直接放行
> 不再让桥另一端的人白跑一趟

# 08、演进

```text
V2：HTTP 缓存短路 + 本地缓存
能力：304 请求不查库，传输层和计算层都省了
遗留：本地缓存只在单实例有效，多实例部署时各存一份
```

用 V1 同一组请求验证前后差异。

V1 时，连续 10 次条件请求，数据库执行 10 次 SELECT，响应体传输 10 次。

V2 时，连续 10 次条件请求，数据库执行 1 次 SELECT，响应体传输 1 次，其余 9 次都是 304 空响应。

收益：带宽占用下降约 90%，数据库查询次数下降约 90%。

代价：本地缓存占用少量堆内存，且需要处理缓存失效。

适用条件：单实例部署或对跨实例一致性要求不高的场景。

遗留问题：如果部署多个实例，每个实例都有自己的本地缓存，数据更新后可能不一致。

下一步需要引入 Redis 作为分布式缓存，解决多实例共享问题。

> 演进像爬楼梯
> 每一级都看到更远的风景
> 但回头一看
> 楼梯本身也需要加固

# 09、洞见

```text
从现象到判断：带宽涨了、接口不慢、Redis 没上，问题到底在哪一层
```

## 很多读接口的第一层优化不是 Redis，而是 HTTP 缓存

```text
浏览器 → 服务端：84KB 重复传输
服务端 → 数据库：重复 SELECT
Redis → 服务端：内存读取
```

如果客户端和服务端之间还在重复传输相同内容，Redis 再快也救不了网络延迟。

HTTP 缓存直接消除传输开销，这是 Redis 做不到的。

## 304 不会自动省掉数据库查询

```text
请求 → Controller → Repository → DB → 比较 ETag → 304
```

这是反直觉判断。

很多人以为返回 304 就代表服务端什么都没做。

实际上，如果不显式短路，数据库查询在 ETag 比较之前就执行了。

## ETag 的稳定性比生成速度更重要

```text
List.hashCode() → 顺序敏感 → ETag 漂移
排序后 hashCode() → 顺序稳定 → ETag 稳定
```

这是反直觉判断。

ETag 生成得再快，如果不稳定，就会导致客户端永远无法命中 304。

稳定性优先于性能。

## 三层缓存解决的是三个不同的问题

```text
HTTP Cache → 传输层
Spring Cache → 计算层
Redis → 共享层
```

不要用 Redis 解决传输问题，也不要用 HTTP 缓存解决跨实例共享问题。

层次错了，优化就是白费。

> 洞见像深夜的灯
> 照亮一层又一层
> 每一层都有自己的问题
> 每一层都需要自己的答案

# 10、系统落地

```text
入口：浏览器/Postman/Apifox → 条件请求 → WebFlux Controller → 短路判断 → 本地缓存 → R2DBC → PostgreSQL
未实现：Redis 分布式缓存、缓存失效策略、多实例一致性
```

原来系统只有最基础的查询接口，每次请求都全量查库、全量返回。

本篇增加了 HTTP 缓存协商和本地短路缓存。

现在系统能做到：数据未变化时，客户端收到 304，服务端不查库。

下一篇需要补上 Redis 分布式缓存，解决多实例部署时的缓存一致性问题。

官方文档可参考 Spring Framework 的 WebFlux 文档首页：https://docs.spring.io/spring-framework/reference/web/webflu

x.html

> 系统像一棵树
> 今天长出了新的枝丫
> 但根还不够深
> 风大的时候还会摇晃

# 11、小结

```text
三问三答：
冲突：为什么数据没变还要重复传输？→ 因为缺少缓存协商机制
选择：HTTP Cache、Spring Cache、Redis 先上哪个？→ 先上 HTTP Cache，再上 Spring Cache，最后上 Redis
选错后果：先上 Redis 会怎样？→ 传输层浪费依旧，多了一个故障点，性能提升有限
```

当前状态：PetType 接口已经具备 ETag、Last-Modified、条件请求和 304 短路能力。

Specialty 和 Vet 接口可以用同样的模式快速复制。

下一步是引入 Redis，把本地缓存升级为分布式缓存。

> 三个问题像三把钥匙
> 打开了三层缓存的门
> 门后是同一个结论
> 层次对了，优化才有效

# 12、作业

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

## 理解题：HTTP Cache、Spring Cache、Redis 三者分别解决什么问题？

HTTP Cache 解决客户端到服务端的传输问题，通过 304 避免重复传输相同响应体。

Spring Cache 解决服务端内部的计算问题，通过本地缓存避免重复查库和组装。

Redis 解决多实例之间的共享问题，通过分布式缓存保证各实例看到同一份数据。

## 实战题：为 Specialty 接口实现 ETag 和条件请求，并用 Apifox 验证 304

复制 PetTypeController 的模式，为 Specialty 创建 Repository 和 Controller。

在 Apifox 中发送第一次请求，从响应头复制 ETag。

发送第二次请求，在请求头中添加 If-None-Match，值为复制的 ETag。

验证响应状态码为 304，响应体为空。

## 排障题：ETag 一直变化，导致 304 永远不命中，如何定位和修复？

先连续两次请求，对比 ETag 值是否相同。

如果不同，检查数据集合的排序是否稳定。

在 Repository 中增加明确的排序条件，例如 `findAllByOrderByIdAsc()`。

重新验证两次请求的 ETag 是否一致。

## 架构判断题：一个多实例部署的读接口，数据变化频率低，但每次请求都全量返回，应该先上 Redis 还是先上 HTTP 缓存？

应该先上 HTTP 缓存。

因为问题首先表现为重复传输，而不是跨实例共享。

HTTP 缓存可以直接消除传输开销，且实现成本低。

Redis 只有在多实例需要共享缓存结果时才有必要引入。

> 作业像四块磨刀石
> 每一块都磨出不同的刃
> 理解、实战、排障、判断
> 四刃齐了，刀才快

# 13、升华

```text
工程结论：缓存优化不是“上 Redis”，而是“先判断问题在哪一层”
```

有依据的结论是：对于低变化读接口，HTTP 缓存协商是第一层优化，Spring Cache 是第二层，Redis 是第三层。

层次顺序错了，优化收益会大打折扣。

下一篇将引入 Redis，把本地缓存升级为分布式缓存，并处理缓存失效和多实例一致性问题。

> 优化不是堆砌工具
> 而是看清问题的层次
> 每一层都有它的位置
> 位置对了，工程才稳

**系列项目：** Reactive Petclinic 宠物医院平台

**已完成：** WebFlux 基础、Mono/Flux、EventLoop、DispatcherHandler、Controller/Binding/Codec、Error/Config、Functional Endpoint、WebClient、CORS/Security、Range/Cache/API Version、WebTestClient/StepVerifier、JMeter、性能瓶颈、证据调优、生产排障

**本篇：** HTTP Cache、ETag、Last-Modified、条件请求、304 短路

**下一篇：** Redis 分布式缓存与多实例一致性

以下按示例系列设计，已有能力为示例前置能力，待与前文核对。

我是老李，在深圳南山科技园做架构支持，经常看到项目把 Redis 当万能缓存，却忽略了浏览器和网关已经在重复传输同一份响应。

《SpringWebFlux7实战》第15招 HTTP Cache比Redis更靠近客户端

用 PetType、Specialty、Vet 三个低变化接口，把 HTTP Cache、Spring Cache、Redis 三层缓存一次讲透，并给出可复现的

架构师

编程语言

后端

架构设计

WebFlux缓存分层实战：从HTTP缓存协商到Redis的工程判断。针对PetType等低频变化数据，通过ETag与304状态码实现传输层短路，避免重复传输84KB响应体。本文揭示关键反直觉点：304不会自动跳过数据库查询，需显式短路；ETag稳定性优先于生成速度。提供从单实例本地缓存到多实例Redis的演进路径，帮助团队避免盲目上Redis的常见陷阱。

网络延迟

数据接口

代码解释

PostgreSQL

数据库

Redis

JSON

CDN免费试用


2026上云采购 | AI焕新·智启新局

coding

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

WebFlux缓存分层实战：从HTTP缓存协商到Redis的工程判断。针对PetType等低频变化数据，通过ETag与304状态码实现传输层短路，避免重复传输84KB响应体。本文揭示关键反直觉点：304不会自动跳过数据库查询，需显式短路；ETag稳定性优先于生成速度。提供从单实例本地缓存到多实例Redis的演进路径，帮...

《SpringWebFlux7实战》第15招 HTTP Cache比Redis更靠近客户端-腾讯云开发者社区-腾讯云

《SpringWebFlux7实战》第15招 HTTP Cache比Redis更靠近客户端

《SpringWebFlux7实战》第15招 HTTP Cache比Redis更靠近客户端

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐