Java 后端 / 知识点
Spring Cloud 微服务速查手册
手册条目
将远程服务的状态码和错误响应转换为统一异常模型。
统一调用错误
当 Feign 调用返回非 2xx 状态时,在客户端边界读取远程错误体,转换为统一异常,再由全局异常处理器输出稳定的错误结构。这样业务代码无需分别处理 400、404、500 或各服务自定义 JSON。Spring Cloud OpenFeign 会从应用上下文或指定的 Feign 配置中查找 ErrorDecoder Bean。:contentReference[oaicite:0]{index=0}
转换链路

统一模型至少保留内部错误码、可展示消息、上游状态码和链路 ID。上游原始响应只用于受控日志,不应直接返回给外部调用方。
基本实现
下面是 Spring Boot 3、Java 17 的片段示例,依赖 spring-cloud-starter-openfeign。该配置注册为全局 ErrorDecoder;只想作用于单个客户端时,将配置类放入对应 @FeignClient(configuration = RemoteErrorConfig.class),并避免被全局组件扫描。
package com.example.remote;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import feign.Response;
import feign.codec.ErrorDecoder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.nio.charset.StandardCharsets;
@Configuration
class RemoteErrorConfig {
private static final int MAX_ERROR_BODY_BYTES = 16 * 1024;
@Bean
ErrorDecoder errorDecoder(ObjectMapper mapper) {
return (methodKey, response) -> {
String body = readBody(response);
String upstreamCode = "UNKNOWN";
String message = "远程服务调用失败";
String traceId = firstHeader(response, "X-Trace-Id");
// 只读取约定字段;解析失败时返回通用消息,避免泄露原始响应。
try {
JsonNode node = mapper.readTree(body);
upstreamCode = node.path("code").asText(upstreamCode);
message = node.path("message").asText(message);
traceId = node.path("traceId").asText(traceId);
} catch (Exception ignored) {
message = "远程服务返回不可解析错误";
}
return new RemoteCallException(
methodKey, response.status(), upstreamCode, message, traceId);
};
}
private static String readBody(Response response) {
if (response.body() == null) {
return "";
}
try (var input = response.body().asInputStream()) {
return new String(input.readNBytes(MAX_ERROR_BODY_BYTES), StandardCharsets.UTF_8);
} catch (Exception ignored) {
return "";
}
}
private static String firstHeader(Response response, String name) {
return response.headers().entrySet().stream()
.filter(entry -> entry.getKey().equalsIgnoreCase(name))
.flatMap(entry -> entry.getValue().stream())
.findFirst()
.orElse(null);
}
}
record ApiError(
String code,
String message,
int upstreamStatus,
String upstreamCode,
String traceId) {
}
final class RemoteCallException extends RuntimeException {
private final String methodKey;
private final int upstreamStatus;
private final String upstreamCode;
private final String traceId;
RemoteCallException(
String methodKey,
int upstreamStatus,
String upstreamCode,
String message,
String traceId) {
super(message);
this.methodKey = methodKey;
this.upstreamStatus = upstreamStatus;
this.upstreamCode = upstreamCode;
this.traceId = traceId;
}
String methodKey() {
return methodKey;
}
int upstreamStatus() {
return upstreamStatus;
}
String upstreamCode() {
return upstreamCode;
}
String traceId() {
return traceId;
}
}
@RestControllerAdvice
class RemoteCallExceptionHandler {
@ExceptionHandler(RemoteCallException.class)
ResponseEntity<ApiError> handle(RemoteCallException exception) {
ApiError body = new ApiError(
"REMOTE_CALL_FAILED",
exception.getMessage(),
exception.upstreamStatus(),
exception.upstreamCode(),
exception.traceId());
// 对外统一为 502;是否映射业务型 4xx,应由显式规则决定。
return ResponseEntity.status(HttpStatus.BAD_GATEWAY).body(body);
}
}假设上游返回:
HTTP/1.1 404 Not Found
X-Trace-Id: trace-7f2
Content-Type: application/json
{"code":"ORDER_NOT_FOUND","message":"订单不存在","traceId":"trace-7f2"}预期结果:
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
{"code":"REMOTE_CALL_FAILED","message":"订单不存在","upstreamStatus":404,"upstreamCode":"ORDER_NOT_FOUND","traceId":"trace-7f2"}读取时先看 code 判断本系统异常类型,再看 upstreamStatus 与 upstreamCode 定位远程服务语义,最后使用 traceId 串联双方日志。methodKey 只用于内部日志定位 Feign 接口,不应直接返回给外部调用方。
风险与边界
不要把所有上游 4xx 原样透传。触发条件是远程服务错误码语义与当前 API 不一致,后果是调用方依赖错误的状态码或暴露内部资源信息;安全替代方案是维护明确映射表,未命中的状态统一返回 502。
不要直接返回原始响应体。触发条件是上游包含堆栈、SQL、账号或内部地址,后果是敏感信息泄露;替代方案是只提取白名单字段,并限制日志长度、脱敏后记录。
读取响应体后不能再次读取同一流。若后续组件仍需原始体,应在解码器内一次性缓存并显式传递,否则会出现空体或二次读取失败。
排障清单
- 未进入
ErrorDecoder:确认异常确实来自 Feign 非 2xx 响应,并检查该 Bean 是否被目标客户端配置加载。 - 错误体始终为空:检查网关或上游是否已消费、压缩或替换响应体,并确认字符集。
traceId丢失:统一约定响应头名称,并在网关、客户端和服务端全链路透传。- 业务 404 被统一成 502:为可信且稳定的业务错误建立显式映射,不要按状态码范围批量透传。
根据路径、主机或请求属性将外部流量转发到目标服务。
创建网关路由
在 Spring Cloud Gateway 中为外部请求定义匹配条件、目标服务和路径处理规则。Path、Host、Header 等谓词按 HTTP 请求属性匹配;同一路由配置多个谓词时按逻辑 AND 组合。:contentReference[oaicite:1]{index=1}
路由关系

每条路由由唯一 id、目标 uri、一个或多个 predicates、可选 filters 和优先级 order 组成。lb://服务名 表示通过服务发现与负载均衡选择实例。
配置路由
下面使用当前 Spring Cloud Gateway 5.0 WebFlux 配置前缀 spring.cloud.gateway.server.webflux.routes。:contentReference[oaicite:2]{index=2}
spring:
cloud:
gateway:
server:
webflux:
routes:
- id: orders-by-path
uri: lb://order-service
order: 10
predicates:
- Path=/api/orders/**
filters:
# /api/orders/42 转为 /orders/42
- StripPrefix=1
# 仅建议在测试环境保留,用于确认命中的路由
- AddResponseHeader=X-Gateway-Route, orders-by-path
- id: admin-by-host
uri: lb://admin-service
order: 20
predicates:
- Host=admin.example.com
- Path=/api/admin/**
filters:
- StripPrefix=1
- AddResponseHeader=X-Gateway-Route, admin-by-host
- id: tenant-by-header
uri: lb://tenant-service
order: 30
predicates:
- Header=X-Tenant-Id, [a-z0-9-]+
- Path=/api/tenant/**
filters:
- StripPrefix=1
- AddResponseHeader=X-Gateway-Route, tenant-by-header生效行为:网关按路由顺序检查谓词;同一路由的全部谓词都满足后执行过滤器,并把请求转发到对应服务。StripPrefix=1 删除第一个路径段 /api。
验证命中结果
先确保三个服务已注册且目标端点返回 2xx,再替换 <PORT> 为网关实际端口。以下命令只打印测试响应头中的路由标记。
curl -sS -o /dev/null -D - http://localhost:<PORT>/api/orders/42 | grep -i '^X-Gateway-Route:'
curl -sS -o /dev/null -D - -H 'Host: admin.example.com' http://localhost:<PORT>/api/admin/health | grep -i '^X-Gateway-Route:'
curl -sS -o /dev/null -D - -H 'X-Tenant-Id: tenant-a' http://localhost:<PORT>/api/tenant/profile | grep -i '^X-Gateway-Route:'预期输出:
X-Gateway-Route: orders-by-path
X-Gateway-Route: admin-by-host
X-Gateway-Route: tenant-by-header若命令无输出,先查看 HTTP 状态码;后端连接失败通常不会产生预期业务结果,但路由仍可能已匹配。排障时可临时保留标记头,验证完成后删除,避免暴露内部路由名称。
常用判断条件
Path:按路径模板匹配,适合公开 API 前缀分流。Host:按请求Host匹配,适合多域名或管理域名分流。Header:按请求头名称和正则匹配,适合可信网关注入的租户、版本或灰度标记。- 多个谓词:同一路由内是 AND;需要 OR 时通常拆成多条指向同一目标的路由。
风险与边界
路由范围过宽或 order 设置错误会让前面的规则吞掉后续流量,表现为请求进入错误服务。安全做法是让路径尽量互斥,为兜底路由设置更大的 order,上线前覆盖冲突用例。
不要把客户端可随意伪造的 X-Tenant-Id 当作鉴权依据。否则攻击者可选择其他租户路由;替代方案是在认证后由可信网关写入内部头,并先删除外部同名头。
StripPrefix 数量错误会让下游收到错误路径并返回 404。发布前同时核对外部路径、删除段数和下游真实上下文路径,复杂改写优先使用明确的 RewritePath。
lb:// 依赖服务发现和负载均衡。出现 503 时检查服务名大小写、注册中心实例健康状态、网关是否引入负载均衡依赖,以及目标服务是否处于同一命名空间。
兼容性
Spring Cloud Gateway 5.0 的 WebFlux 文档使用 spring.cloud.gateway.server.webflux.routes;较早 4.x 文档常见 spring.cloud.gateway.routes。:contentReference[oaicite:3]{index=3} 两种前缀不要同时配置,应按项目实际 Spring Cloud 版本选择。
使用路径、方法、请求头和参数等条件匹配网关请求。
配置路由断言
用于让 Spring Cloud Gateway 只转发满足指定路径、HTTP 方法、请求头和查询参数的请求。把多个断言写在同一路由下时,它们按逻辑 AND 组合;任一条件不满足,该路由就不会被选中。:contentReference[oaicite:0]{index=0}
常用断言
| 断言 | 典型写法 | 匹配内容 |
|---|---|---|
Path |
Path=/api/orders/** |
请求路径 |
Method |
Method=GET,POST |
HTTP 方法 |
Header |
Header=X-Client-Id, ^mobile-[0-9]+$ |
请求头名称和值的正则表达式 |
Query |
`Query=debug, ^(true | false)$` |
Header 和 Query 的第二个参数使用 Java 正则表达式。生产配置建议使用 ^、$ 限定完整值,避免 mobile-17-extra 之类的意外匹配。Path 支持路径模板和通配符,当前 WebFlux 文档中 matchTrailingSlash 默认值为 true。:contentReference[oaicite:1]{index=1}
主配置
下面的路由仅接受 GET /api/orders/**,同时要求 X-Client-Id 符合规则且 debug 为 true 或 false。示例使用 Spring Cloud Gateway 5.x 的 WebFlux 配置前缀,并转发到公开回显服务;生产环境应把 uri 替换为内部服务地址。
spring:
cloud:
gateway:
server:
webflux:
routes:
- id: order-query
uri: https://httpbin.org
predicates:
- Path=/api/orders/**
- Method=GET
- Header=X-Client-Id, ^mobile-[0-9]+$
- Query=debug, ^(true|false)$
filters:
- RewritePath=/api/(?<segment>.*), /anything/$\{segment}命中后,/api/orders/42?debug=true 会被改写为下游的 /anything/orders/42?debug=true。YAML 中 RewritePath 的替换表达式需要把 $ 写成 $\{segment},否则可能被 YAML 解析器误处理。:contentReference[oaicite:2]{index=2}
验证匹配
假设网关监听 localhost:8080,先发送满足全部断言的请求:
curl -i \
-H "X-Client-Id: mobile-17" \
"http://localhost:8080/api/orders/42?debug=true"预期输出中的状态码为 200,响应体会回显最终路径、方法、请求头和查询参数;其他自动生成的头部可能不同。
HTTP/1.1 200 OK
{
"args": {"debug": "true"},
"headers": {"X-Client-Id": "mobile-17"},
"method": "GET",
"url": "https://httpbin.org/anything/orders/42?debug=true"
}去掉必需请求头后,同一路由不再匹配:
curl -i "http://localhost:8080/api/orders/42?debug=true"预期结果通常是网关返回 404 Not Found;若项目还有其他宽泛路由,请以实际被选中的路由为准。
HTTP/1.1 404 Not Found风险与边界
同一路由中的条件是 AND,不是 OR。需要“GET 或带特定请求头”这类分支时,应拆成两条路由并设置清晰的优先关系,而不是把互斥断言堆在一起。过宽的 Path=/** 可能抢先匹配请求,安全替代方案是缩小路径范围,并为重叠路由显式配置顺序。
不要用客户端可控的普通请求头直接判定用户身份、租户或权限。攻击者可以伪造这些值;安全做法是在网关完成认证后使用可信上下文生成内部头,并在转发前删除客户端同名头。
排障清单
- 启动时报找不到断言工厂:检查
Path、Method、Header、Query的名称拼写以及 Gateway 依赖是否为 WebFlux 版本。 - 请求返回 404:依次检查配置前缀、路径大小写、尾部斜杠、方法、正则表达式和查询参数;确认配置已刷新。
- 请求返回 502 或 503:通常表示路由已经命中,但下游连接、DNS、TLS 或服务发现失败,应转向检查
uri和下游健康状态。 - 多条路由都可能命中:查看网关调试日志或 Actuator 路由信息,确认实际路由 ID 和排序,不要只根据 YAML 位置推断。
兼容性
Spring Cloud Gateway 5.x WebFlux 使用 spring.cloud.gateway.server.webflux.routes;4.3.x 文档使用 spring.cloud.gateway.routes。升级时若配置完全不生效,先核对版本对应的属性前缀。Web MVC 使用 server.webmvc 路径,不能直接照搬 WebFlux 的 Java API。:contentReference[oaicite:3]{index=3}
在网关中重写路径并添加、删除或修改请求头。
修改转发请求
用于在请求发往下游之前重写路径,并添加、删除或替换请求头。路由断言负责决定“是否转发”,GatewayFilter 负责决定“以什么路径和请求头转发”。
常用过滤器
| 过滤器 | 作用 | 关键边界 |
|---|---|---|
RewritePath |
用 Java 正则重写请求路径 | YAML 中替换变量的 $ 需要转义 |
AddRequestHeader |
追加一个请求头值 | 同名头已存在时可能形成多值头 |
SetRequestHeader |
替换同名请求头的全部值 | 适合强制覆盖客户端值 |
RemoveRequestHeader |
转发前删除指定请求头 | 只影响下游请求,不代表网关从未接收该头 |
AddRequestHeader 接收名称和值,SetRequestHeader 会替换而不是追加同名头,RemoveRequestHeader 在发送下游请求前删除指定头。:contentReference[oaicite:4]{index=4}
主配置
下面的路由把外部路径 /edge/** 改写到下游 /anything/**,删除客户端传入的内部令牌,强制把客户端版本改成 v2,并添加网关标识。示例使用公开回显服务验证最终请求;生产环境应替换 uri。
spring:
cloud:
gateway:
server:
webflux:
routes:
- id: request-mutation
uri: https://httpbin.org
predicates:
- Path=/edge/**
filters:
- RewritePath=/edge/(?<segment>.*), /anything/$\{segment}
- RemoveRequestHeader=X-Internal-Token
- SetRequestHeader=X-Client-Version, v2
- AddRequestHeader=X-Gateway, spring-cloud-gateway请求 /edge/orders/42 最终发往 /anything/orders/42。X-Internal-Token 不会继续传递,客户端提交的任意 X-Client-Version 会被替换为 v2,X-Gateway 则被追加到下游请求。路径重写使用 Java 正则,YAML 中应保留 $\{segment} 的转义形式。:contentReference[oaicite:5]{index=5}
验证结果
假设网关监听 localhost:8080,发送包含待删除和待覆盖请求头的请求:
curl -sS \
-H "X-Internal-Token: client-secret" \
-H "X-Client-Version: v1" \
"http://localhost:8080/edge/orders/42"预期响应的相关字段如下;实际响应还会包含其他网络头。读取时确认 URL 已改写、版本为 v2、网关头存在,并且 X-Internal-Token 不在 headers 中。
{
"headers": {
"X-Client-Version": "v2",
"X-Gateway": "spring-cloud-gateway"
},
"method": "GET",
"url": "https://httpbin.org/anything/orders/42"
}选择添加还是覆盖
需要保留客户端原值并再追加一个值时使用 AddRequestHeader。需要保证下游只接收网关指定值时使用 SetRequestHeader。若只想在客户端未提供该头时补默认值,可使用 AddRequestHeadersIfNotPresent,避免产生重复值。:contentReference[oaicite:6]{index=6}
修改 Host 头时不要把普通请求头过滤器当作唯一方案。需要固定下游主机名时使用 SetRequestHostHeader;需要保留原始主机名时使用 PreserveHostHeader,并同时核对下游 TLS 与虚拟主机配置。:contentReference[oaicite:7]{index=7}
风险与边界
客户端可伪造身份、租户、角色和追踪类请求头。若下游信任这些头,触发条件是攻击者直接提交同名值,后果可能是越权或审计污染。安全做法是先删除客户端同名头,在认证成功后由网关重新设置,并限制网关只能通过受控网络访问下游。
AddRequestHeader 可能产生多值头;部分下游框架只读取第一个值或把多个值拼接,结果可能与预期不同。需要唯一值时使用 SetRequestHeader。重写规则过宽还可能把请求发送到错误端点,发布前应覆盖空路径、尾部斜杠、编码字符和多级路径测试。
排障清单
- 路径没有变化:检查正则是否命中原始路径,以及 YAML 中是否写成
$\{segment};错误转义常导致启动失败或替换结果异常。 - 下游仍收到被删除的头:确认请求命中了配置该过滤器的路由,并检查后续全局过滤器是否重新添加了同名头。
- 下游收到重复头:把
AddRequestHeader改为SetRequestHeader,或先RemoveRequestHeader再添加。 - 返回 404:若网关路由已命中,通常是改写后的下游路径不存在;返回 502 或 503 时检查下游连接、DNS、TLS 或服务发现。
- 本地验证与生产不同:代理、Ingress 或负载均衡器也可能增删头部,应同时检查网关前后的真实请求。
兼容性
Spring Cloud Gateway 5.x WebFlux 路由前缀为 spring.cloud.gateway.server.webflux.routes,4.3.x 使用 spring.cloud.gateway.routes。过滤器名称大体一致,但 Web MVC 与 WebFlux 的配置前缀和编程 API 不同,迁移时应按所用服务器实现核对官方版本文档。:contentReference[oaicite:8]{index=8}
集中配置网关 CORS 规则并正确响应预检请求。
处理跨域请求
当浏览器前端与 Spring Cloud Gateway 的协议、域名或端口不同,集中在网关声明允许的来源、方法和请求头,并让 OPTIONS 预检在未命中业务路由时也能得到正确响应。CORS 只解决浏览器跨域限制,不能替代认证、鉴权或 CSRF 防护。
网关配置
以下配置适用于基于 WebFlux 的 Spring Cloud Gateway。示例只允许 example.com 的 HTTPS 子域访问,允许携带 Cookie 或 Authorization,并统一去重网关与下游服务重复写入的 CORS 响应头。
spring:
cloud:
gateway:
server:
webflux:
globalcors:
add-to-simple-url-handler-mapping: true
cors-configurations:
'[/**]':
allowedOriginPatterns:
- "https://*.example.com"
allowedMethods:
- GET
- POST
- PUT
- DELETE
- OPTIONS
allowedHeaders:
- "*"
exposedHeaders:
- X-Request-Id
allowCredentials: true
maxAge: 3600
default-filters:
- DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin, RETAIN_FIRSTadd-to-simple-url-handler-mapping 让预检请求即使因 OPTIONS 未匹配路由谓词,也能由全局 CORS 处理器响应。maxAge 表示浏览器可缓存预检结果的秒数;规则有变化时,需要等待缓存失效或清理浏览器缓存后再验证。
验证预检请求
启动网关后,用与浏览器一致的 Origin、目标方法和请求头发起预检。该命令只验证网关返回的 CORS 头,不会真正调用 POST /api/orders。
curl -i -X OPTIONS 'http://localhost:8080/api/orders' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: POST' \
-H 'Access-Control-Request-Headers: Authorization,Content-Type'预期输出如下,响应头顺序和大小写可能因服务器版本不同而变化。
HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://app.example.com
Access-Control-Allow-Methods: GET,POST,PUT,DELETE,OPTIONS
Access-Control-Allow-Headers: Authorization,Content-Type
Access-Control-Allow-Credentials: true
Access-Control-Max-Age: 3600读取时先确认状态码不是 403,再核对 Access-Control-Allow-Origin 是否精确回显当前来源。浏览器仍报错时,在开发者工具的 Network 面板分别检查预检请求和实际请求,不要只看控制台摘要。
风险与边界
当 allowCredentials: true 时,不要把 allowedOrigins 配置为 *。该组合会被浏览器或框架拒绝;安全替代是列出可信来源,或使用受控的 allowedOriginPatterns。模式过宽会让任意匹配站点携带用户凭据调用接口,应按环境和前端域名收紧。
如果下游服务也写入 CORS 头,可能出现两个 Access-Control-Allow-Origin,浏览器会判定响应无效。优先统一由网关负责;暂时无法改造下游时保留 DedupeResponseHeader,并确认保留的值与网关策略一致。
排障清单
- 预检返回
404:确认已启用add-to-simple-url-handler-mapping,并检查配置缩进及路径键'[/**]'。 - 预检返回
403:核对Origin、请求方法和请求头是否命中允许列表;来源包含协议和端口,必须完整匹配。 - 预检成功但实际请求失败:检查实际响应是否也带 CORS 头,以及认证过滤器是否错误拦截了
OPTIONS。 - 仅部分路由异常:检查路由级 CORS、下游响应头或其他过滤器是否覆盖了全局规则。
兼容性
本示例按 Spring Cloud Gateway 5.x 的 Reactive/WebFlux 属性前缀 spring.cloud.gateway.server.webflux 编写。较早版本可能使用 spring.cloud.gateway 作为前缀;使用 Gateway Server MVC 时配置入口也不同。升级 Spring Boot 或 Spring Cloud 后,先核对本项目版本的配置元数据,再重新执行预检命令。
按用户、客户端或接口限制请求速率并返回明确结果。
配置网关限流
需要按登录用户、可信客户端或接口维度控制请求速率时,在 Spring Cloud Gateway 使用 RequestRateLimiter 与 Redis 令牌桶。限流命中后网关返回 429 Too Many Requests,客户端应把该状态码作为重试、退避或降级信号。
前置条件与限流键
项目需要 spring-cloud-starter-gateway 和 spring-boot-starter-data-redis-reactive,并保证网关能连接 Redis。限流键决定“谁共享同一个桶”:用户维度优先取认证主体;客户端维度只信任由认证层写入的客户端 ID;接口维度可使用请求方法与路径。
package com.example.gateway;
import java.security.Principal;
import org.springframework.cloud.gateway.filter.ratelimit.KeyResolver;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import reactor.core.publisher.Mono;
@Configuration
public class RateLimitKeyConfig {
@Bean
KeyResolver userKeyResolver() {
// 使用已认证主体,避免直接信任调用方伪造的用户请求头。
return exchange -> exchange.getPrincipal().map(Principal::getName);
}
@Bean
KeyResolver clientKeyResolver() {
// 仅当网关前置认证层会清洗并重写该请求头时使用。
return exchange -> Mono.justOrEmpty(
exchange.getRequest().getHeaders().getFirst("X-Client-Id"));
}
@Bean
KeyResolver apiKeyResolver() {
return exchange -> Mono.just(
exchange.getRequest().getMethod() + ":"
+ exchange.getRequest().getPath().value());
}
}没有登录主体或客户端 ID 时,解析结果为空。默认配置会拒绝空键请求;不要用固定兜底值把所有匿名流量合并到一个桶,除非这正是预期策略。
路由限流配置
下面按认证用户限制 /api/orders/**:每秒补充 5 个令牌,桶最多保存 10 个令牌,每次请求消耗 1 个。需要改为客户端或接口维度时,只替换 key-resolver 引用。
spring:
data:
redis:
host: localhost
port: 6379
cloud:
gateway:
server:
webflux:
routes:
- id: order-api
uri: http://localhost:8081
predicates:
- Path=/api/orders/**
filters:
- name: RequestRateLimiter
args:
key-resolver: "#{@userKeyResolver}"
redis-rate-limiter.replenishRate: 5
redis-rate-limiter.burstCapacity: 10
redis-rate-limiter.requestedTokens: 1replenishRate 是稳定补充速率,burstCapacity 是允许的短时突发上限,requestedTokens 是单次请求成本。必须满足 burstCapacity >= requestedTokens,否则所有请求都会被拒绝。高成本接口可提高 requestedTokens,但要同步评估正常调用是否还能通过。
验证限流结果
先保证下游 localhost:8081 可正常响应,再并发发送 20 个同一用户请求。初始桶最多放行 10 个,其余请求通常返回 429;执行期间补充的令牌可能让少量结果不同。
{
for _ in $(seq 1 20); do
curl -s -o /dev/null -w '%{http_code}\n' \
-H 'Authorization: Bearer <TOKEN>' \
http://localhost:8080/api/orders &
done
wait
} | sort | uniq -c预期结果以 200 和 429 为主。并发期间令牌仍会补充,因此具体数量按机器和下游耗时变化。
<COUNT_200> 200
<COUNT_429> 429查看单次完整响应时使用 curl -i。被限流的响应应为 HTTP/1.1 429 Too Many Requests;成功响应通常还包含 X-RateLimit-Remaining、X-RateLimit-Replenish-Rate 和 X-RateLimit-Burst-Capacity,具体头名受版本与配置影响。原生过滤器可能不返回 JSON 错误体,API 契约要求固定响应体时,应在网关统一错误响应层补充,而不是让各下游服务各自实现。
风险与边界
不要直接使用外部可伪造的 X-User-Id、X-Forwarded-For 作为限流键,否则攻击者可轮换值绕过限流。安全替代是使用认证后的 Principal,或由可信代理清洗并重写客户端标识。按完整原始路径限流还可能产生高基数 Redis 键,应先把动态 ID 归一为路由模板或固定接口分组。
Redis 不可用时,限流过滤器可能导致请求失败并放大网关故障。必须监控 Redis 连接、命令延迟和网关 5xx,并根据业务风险明确选择故障时拒绝还是降级放行;不要在未评审的情况下静默绕过限流。
排障清单
- 所有请求都被拒绝:检查
burstCapacity是否小于requestedTokens,以及 KeyResolver 是否返回空值。 - 完全不限流:确认路由实际命中、过滤器名称正确、Redis 可写,并检查是否每次请求都生成了不同键。
- 同一用户出现多个桶:检查认证主体名称是否稳定,避免把临时令牌、时间戳或动态查询参数写入键。
- 返回
500:先查 Redis 连接和超时,再检查 SpEL Bean 名userKeyResolver是否与配置一致。 - 多实例结果不一致:所有网关实例必须连接同一 Redis 逻辑库并使用一致的键解析规则。
兼容性
该配置按 Spring Cloud Gateway 5.x Reactive 的 spring.cloud.gateway.server.webflux 前缀编写,并依赖响应式 Redis 驱动。较早版本可能使用 spring.cloud.gateway 前缀;Gateway Server MVC、其他限流组件或不同发行版的参数也可能不同。升级后应重新验证速率、突发容量、空键行为和 429 响应契约。
仅对适合重复执行的失败请求设置次数、间隔和异常范围。
配置请求重试
请求重试只用于短暂网络故障、连接超时或可恢复的服务端错误。先限定可重试异常,再设置总尝试次数和等待间隔;max-attempts 包含第一次调用,不是额外重试次数。
适用边界
适合重试的请求必须可重复执行且结果一致,例如查询类 GET,或带幂等键、服务端已实现去重的写请求。支付、下单、发券等非幂等操作若直接重试,可能产生重复扣款、重复订单或重复消息。
安全做法是只记录网络异常和 5xx,明确排除参数错误、权限错误、业务校验失败等 4xx。写请求需要先落实幂等键、唯一约束或请求去重,再开启重试。
依赖与配置
以下为 Spring Boot 3 项目的 pom.xml 片段;注解方式依赖 Spring AOP。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-aop</artifactId>
</dependency>
<dependency>
<groupId>io.github.resilience4j</groupId>
<artifactId>resilience4j-spring-boot3</artifactId>
</dependency>
</dependencies>为名为 inventory 的调用设置最多 3 次尝试,每次间隔 300 ms,并且只对连接类异常重试。
resilience4j:
retry:
instances:
inventory:
max-attempts: 3
wait-duration: 300ms
retry-exceptions:
- org.springframework.web.client.ResourceAccessException配置生效后,可通过应用日志或 Resilience4j 指标确认实际尝试次数。生产环境还应把超时设置得短于调用方总截止时间,避免重试把线程长期占住。
可运行示例
下面的应用用计数器模拟前两次连接失败,第三次成功。@Retry 必须作用在由 Spring 管理的 Bean 上;同类内部直接调用被注解方法不会经过代理。
package com.example.retrydemo;
import java.util.concurrent.atomic.AtomicInteger;
import io.github.resilience4j.retry.annotation.Retry;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.ResourceAccessException;
@SpringBootApplication
public class RetryDemoApplication {
public static void main(String[] args) {
SpringApplication.run(RetryDemoApplication.class, args);
}
}
@RestController
class InventoryController {
private final InventoryService inventoryService;
InventoryController(InventoryService inventoryService) {
this.inventoryService = inventoryService;
}
@GetMapping("/inventory/{sku}")
String inventory(@PathVariable String sku) {
return inventoryService.query(sku);
}
}
@Service
class InventoryService {
private final AtomicInteger attempts = new AtomicInteger();
@Retry(name = "inventory", fallbackMethod = "fallback")
public String query(String sku) {
int current = attempts.incrementAndGet();
if (current < 3) {
// 模拟连接超时;该异常在 retry-exceptions 范围内
throw new ResourceAccessException("temporary timeout");
}
return "sku=" + sku + ", stock=12, attempts=" + current;
}
public String fallback(String sku, Throwable error) {
return "sku=" + sku + ", unavailable=" + error.getClass().getSimpleName();
}
}启动后调用接口:
curl -s http://localhost:8080/inventory/SKU-100预期输出:
sku=SKU-100, stock=12, attempts=3读取结果时重点看 attempts=3:第一次调用加两次重试后成功,因此没有进入降级方法。
关键参数
| 参数 | 读取方法 |
|---|---|
max-attempts |
总调用次数,包含首次调用;设为 3 表示最多重试两次 |
wait-duration |
相邻尝试之间的等待时间;过短会放大下游压力 |
retry-exceptions |
只有列出的异常才重试,建议采用白名单 |
ignore-exceptions |
即使满足其他规则也不重试,适合明确的业务异常 |
风险与排障
同时启用 Feign Retryer、HTTP 客户端重试和 Resilience4j Retry,会形成乘法次数。例如三层各尝试 3 次,最坏可能触发 27 次下游请求。安全替代方案是只保留一层重试,并在日志中输出请求 ID、尝试序号和最终异常。
出现“配置了但只调用一次”时,检查是否缺少 AOP 依赖、实例名是否与 @Retry(name = "inventory") 一致、方法是否由其他 Spring Bean 调用。出现“所有错误都在重试”时,收紧 retry-exceptions,不要把通用 Exception 或业务基类异常加入白名单。
速查结论:先保证幂等,再对白名单异常做少量、短间隔重试,并让总耗时始终受调用超时约束。
在下游持续失败时快速拒绝调用并等待自动恢复。
配置断路器
断路器用于下游持续失败或超时时快速拒绝新调用,避免线程、连接池和上游请求被拖垮。核心是设置统计窗口、最小样本数、失败率阈值和打开后的等待时间,并为拒绝调用准备可识别的降级结果。
状态与触发条件
CLOSED 状态正常放行并统计结果;达到最小调用数后,失败率超过阈值则进入 OPEN,新请求立即失败。等待期结束后进入 HALF_OPEN,只放行少量探测请求;探测成功则关闭,失败则重新打开。

依赖与配置
以下为 Spring Boot 3、Spring Cloud 项目的 pom.xml 片段。Spring Cloud 版本应通过 BOM 统一管理,不要单独给 starter 指定随机版本。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-circuitbreaker-resilience4j</artifactId>
</dependency>
</dependencies>下面为名为 payment 的断路器配置:最近 10 次调用作为统计窗口,至少积累 5 次才计算,失败率达到 50% 后打开,10 秒后允许 2 次半开探测。只把连接异常和 5xx 计为失败,避免参数错误等 4xx 错误误开断路器。
package com.example.circuitdemo;
import java.time.Duration;
import io.github.resilience4j.circuitbreaker.CircuitBreakerConfig;
import io.github.resilience4j.timelimiter.TimeLimiterConfig;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.circuitbreaker.CircuitBreakerFactory;
import org.springframework.cloud.client.circuitbreaker.Customizer;
import org.springframework.cloud.circuitbreaker.resilience4j.Resilience4JCircuitBreakerFactory;
import org.springframework.cloud.circuitbreaker.resilience4j.Resilience4JConfigBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.HttpServerErrorException;
import org.springframework.web.client.ResourceAccessException;
import org.springframework.web.client.RestClient;
@SpringBootApplication
public class CircuitDemoApplication {
public static void main(String[] args) {
SpringApplication.run(CircuitDemoApplication.class, args);
}
@Bean
RestClient restClient(RestClient.Builder builder) {
return builder.baseUrl("http://localhost:8080").build();
}
@Bean
Customizer<Resilience4JCircuitBreakerFactory> paymentCircuitBreaker() {
return factory -> factory.configure(builder ->
new Resilience4JConfigBuilder("payment")
.circuitBreakerConfig(CircuitBreakerConfig.custom()
.slidingWindowSize(10)
.minimumNumberOfCalls(5)
.failureRateThreshold(50)
.waitDurationInOpenState(Duration.ofSeconds(10))
.permittedNumberOfCallsInHalfOpenState(2)
// 仅网络错误和 5xx 进入失败率统计
.recordException(error ->
error instanceof ResourceAccessException
|| error instanceof HttpServerErrorException)
.build())
.timeLimiterConfig(TimeLimiterConfig.custom()
.timeoutDuration(Duration.ofSeconds(2))
.build())
.build(),
"payment");
}
}
@RestController
class PaymentController {
private final CircuitBreakerFactory<?, ?> factory;
private final RestClient restClient;
PaymentController(CircuitBreakerFactory<?, ?> factory, RestClient restClient) {
this.factory = factory;
this.restClient = restClient;
}
@GetMapping("/pay")
String pay() {
return factory.create("payment").run(
() -> restClient.get()
.uri("/downstream")
.retrieve()
.body(String.class),
error -> "fallback:" + error.getClass().getSimpleName()
);
}
@GetMapping("/downstream")
ResponseEntity<String> downstream() {
// 固定返回 503,用于观察断路器从 CLOSED 转为 OPEN
return ResponseEntity.status(503).body("temporarily unavailable");
}
}验证打开状态
应用启动后连续调用 6 次。前 5 次真实访问下游并记录失败,第 6 次应被断路器直接拒绝。
for i in 1 2 3 4 5 6; do
printf "%s " "$i"
curl -s http://localhost:8080/pay
printf "\n"
done预期输出:
1 fallback:ServiceUnavailable
2 fallback:ServiceUnavailable
3 fallback:ServiceUnavailable
4 fallback:ServiceUnavailable
5 fallback:ServiceUnavailable
6 fallback:CallNotPermittedException第 6 行出现 CallNotPermittedException,说明请求没有再到达 /downstream,而是由 OPEN 状态快速拒绝。等待约 10 秒后再次调用,会进入半开探测;实际切换时点可能略有差异。
关键参数
| 参数 | 读取方法 |
|---|---|
slidingWindowSize |
统计窗口大小;过小容易因短时波动误开 |
minimumNumberOfCalls |
计算失败率前的最小样本数,防止低流量误判 |
failureRateThreshold |
失败率达到该百分比时打开 |
waitDurationInOpenState |
打开后等待多久再允许探测 |
permittedNumberOfCallsInHalfOpenState |
半开状态最多放行的探测调用数 |
风险与排障
降级方法若返回看似成功的空对象,调用方可能把故障当成真实业务结果。安全替代方案是返回明确的降级标识、可识别状态码或缓存数据,并保留原始异常指标。断路器也不能替代超时控制;没有连接和读取超时时,单次调用仍可能长期阻塞。
出现“始终不开”时,检查最小调用数是否尚未达到、异常是否被 recordException 排除、断路器名称是否一致。出现“频繁开关”时,增大统计窗口或最小样本数,并确认下游是否存在周期性超时。多实例部署时,每个应用实例通常维护自己的本地断路状态,不能把它误认为全局共享状态。
重试与断路器组合时要明确顺序:重试放在断路器内部,通常由断路器记录一次最终结果;重试放在外部,则每次尝试都可能触发断路器并更快打开。生产配置应结合调用预算和下游容量压测后确定。
在依赖不可用时返回缓存、默认值或可识别的降级响应。
编写降级逻辑
当下游超时、拒绝连接或熔断器已打开时,用可识别的响应结束当前请求。降级结果必须显式标记来源和降级状态,优先返回仍在有效期内的缓存;没有可信缓存时,再返回受限默认值或 503,不要把错误伪装成正常实时数据。
处理路径

降级函数只负责可预期的依赖故障。参数校验失败、鉴权失败、数据损坏和代码缺陷不应被统一吞掉,否则调用方会收到“成功但错误”的结果,监控也难以发现真实故障。
基本写法
片段示例:放入已引入 spring-cloud-starter-circuitbreaker-resilience4j 的 Spring Boot 项目。示例用内存缓存演示返回顺序,生产环境应替换为带过期时间和版本信息的本地缓存或分布式缓存。
package com.example.demo;
import java.util.concurrent.atomic.AtomicReference;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.circuitbreaker.CircuitBreakerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
@RestController
class CatalogController {
private final CircuitBreakerFactory<?, ?> circuitBreakerFactory;
private final AtomicReference<String> cache =
new AtomicReference<>("cached-catalog-v1");
CatalogController(CircuitBreakerFactory<?, ?> circuitBreakerFactory) {
this.circuitBreakerFactory = circuitBreakerFactory;
}
@GetMapping("/catalog")
CatalogResponse catalog(@RequestParam(defaultValue = "false") boolean fail) {
return circuitBreakerFactory.create("catalog").run(
() -> loadPrimary(fail),
this::fallback
);
}
private CatalogResponse loadPrimary(boolean fail) {
// 真实项目中这里调用下游,并配置连接、读取和总超时。
if (fail) {
throw new IllegalStateException("upstream unavailable");
}
String data = "live-catalog-v2";
cache.set(data);
return new CatalogResponse(false, "primary", data, "none");
}
private CatalogResponse fallback(Throwable error) {
// 有可信缓存时返回旧数据,并让调用方明确知道已经降级。
String cached = cache.get();
if (cached != null) {
return new CatalogResponse(
true, "cache", cached, "upstream_unavailable");
}
return new CatalogResponse(
true, "default", "catalog-temporarily-unavailable", "no_cache");
}
}
record CatalogResponse(
boolean degraded,
String source,
String data,
String reason) {
}启动应用后执行:
curl -s "http://localhost:8080/catalog?fail=true"预期输出:
{"degraded":true,"source":"cache","data":"cached-catalog-v1","reason":"upstream_unavailable"}读取时先检查 degraded,再根据 source 判断数据来自主调用、缓存还是默认值。实际 JSON 字段顺序由序列化器决定,但字段和值应一致。
降级策略选择
| 条件 | 建议响应 | 关键约束 |
|---|---|---|
| 缓存存在且未过期 | 返回缓存并标记 source=cache |
携带缓存时间、版本或陈旧度 |
| 查询类非关键数据 | 返回受限默认值 | 默认值不能被误认为真实库存、余额或权限 |
| 强一致或写操作 | 返回 503 Service Unavailable |
不要假装写入成功,也不要自动重复非幂等请求 |
| 部分字段可缺失 | 返回部分结果并列出缺失字段 | 调用方必须能识别不完整结果 |
风险与边界
触发降级前必须先给下游调用设置超时;没有超时时,线程会长期阻塞,熔断和降级无法及时执行。缓存降级要校验 TTL、租户和数据版本,避免把过期或其他租户的数据返回给当前请求。
降级逻辑本身也可能失败。不要在 fallback 中继续调用同一个故障依赖,也不要执行慢 SQL、远程日志或复杂序列化。安全替代方案是返回小而固定的响应,并异步记录指标、异常类型和降级来源。
排障清单
- fallback 未执行:确认调用确实经过
CircuitBreakerFactory.create(...).run(...),异常没有在主调用内部被提前吞掉。 - 一直返回缓存:检查下游超时、熔断器状态和恢复探测,确认成功请求能够刷新缓存。
- 返回
200但业务不可接受:改为503,或让响应契约强制包含degraded、source和reason。 - 降级后延迟仍高:检查客户端超时是否过大,以及 fallback 是否又访问了慢依赖。
通过隔离舱限制单个依赖占用的线程或并发请求数量。
限制并发调用
当单个下游变慢时,用隔离舱限制同时进入该依赖的请求数,避免它占满应用线程、连接池和内存。对阻塞式调用,常用信号量隔离舱控制并发;配合零等待可让超额请求立即返回 429 或可识别的繁忙响应。
隔离方式与参数

| 参数 | 作用 | 生产建议 |
|---|---|---|
maxConcurrentCalls |
同时进入依赖的最大调用数 | 不高于下游容量和本地连接池可用连接数 |
maxWaitDuration |
获取许可时最多等待多久 | 延迟敏感接口通常设为 0,立即拒绝 |
| HTTP 返回 | 告知调用方当前过载 | 查询接口可返回 429 或 503,并携带稳定错误码 |
信号量隔离不会创建新线程,只限制进入临界区的并发数。需要把任务放入独立线程池、限制队列长度或隔离阻塞线程时,应使用线程池隔离,并单独评估队列等待和上下文切换成本。
可运行片段
片段示例:放入已引入 io.github.resilience4j:resilience4j-bulkhead 的 Spring Boot 项目。这里将并发上限设为 1,便于验证;生产值应根据下游容量、超时和实例数压测确定。
package com.example.demo;
import java.time.Duration;
import io.github.resilience4j.bulkhead.Bulkhead;
import io.github.resilience4j.bulkhead.BulkheadConfig;
import io.github.resilience4j.bulkhead.BulkheadFullException;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
@Configuration
class ResilienceConfiguration {
@Bean
Bulkhead inventoryBulkhead() {
BulkheadConfig config = BulkheadConfig.custom()
.maxConcurrentCalls(1)
// 零等待可防止请求在线程中排队并继续放大延迟。
.maxWaitDuration(Duration.ZERO)
.build();
return Bulkhead.of("inventory", config);
}
}
@RestController
class InventoryController {
private final Bulkhead inventoryBulkhead;
InventoryController(Bulkhead inventoryBulkhead) {
this.inventoryBulkhead = inventoryBulkhead;
}
@GetMapping("/inventory")
ResponseEntity<?> inventory() {
try {
InventoryResponse response = Bulkhead
.decorateSupplier(
inventoryBulkhead,
this::callSlowDependency)
.get();
return ResponseEntity.ok(response);
} catch (BulkheadFullException error) {
// 超额请求立即失败,不继续占用连接池和调用线程。
return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
.body(new BusyResponse(
"rejected", "inventory_bulkhead_full"));
}
}
private InventoryResponse callSlowDependency() {
try {
Thread.sleep(2000);
} catch (InterruptedException error) {
Thread.currentThread().interrupt();
throw new IllegalStateException("interrupted", error);
}
return new InventoryResponse("ok", "inventory-data");
}
}
record InventoryResponse(String status, String data) {
}
record BusyResponse(String status, String reason) {
}验证并发上限
先让第一个请求占用唯一许可,再发送第二个请求:
curl -s -o /tmp/first.out -w '%{http_code}' http://localhost:8080/inventory > /tmp/first.status &
first_pid=$!
sleep 0.2
curl -s -w '\nHTTP %{http_code}\n' http://localhost:8080/inventory
wait "$first_pid"
printf 'first HTTP '
cat /tmp/first.status
printf '\n'
cat /tmp/first.out
printf '\n'预期输出:
{"status":"rejected","reason":"inventory_bulkhead_full"}
HTTP 429
first HTTP 200
{"status":"ok","data":"inventory-data"}若机器调度极慢,第二个请求可能在第一个请求真正进入接口前获得许可;重复执行或把 sleep 0.2 调大即可。生产验证应同时观察隔离舱拒绝数、下游延迟、连接池占用和应用线程数。
风险与边界
maxConcurrentCalls 过大时隔离形同虚设,过小时会在下游健康时误拒绝请求。安全做法是从下游实例容量、调用超时和本服务实例数反推单实例上限,再通过压测逐步调整,而不是直接照搬固定数字。
隔离舱不能替代客户端超时。若下游调用永久阻塞,许可会一直被占用,随后所有请求都被拒绝。应同时设置连接超时、读取超时和总调用超时;对于非幂等写请求,不要在拒绝后自动无界重试。
排障清单
- 没有出现拒绝:确认所有调用都经过同一个
Bulkhead实例,不能每次请求都重新创建。 - 拒绝率突然升高:先检查下游延迟和连接池耗尽,再判断是否需要扩容或调整上限。
- 线程数仍持续上涨:信号量只限并发,不隔离线程;检查上游请求线程和 HTTP 客户端是否有界。
- 调大等待时间后超时更多:等待许可会累积排队延迟,优先恢复零等待或缩短等待,并让调用方执行退避。
为异步或长耗时操作设置最大执行时间并处理中断结果。
限制执行时间
当异步任务、批处理或远程调用可能长期阻塞时,要同时限制调用方等待时间和后台任务执行时间。超时后返回明确状态,并尽力取消任务;只抛出超时异常而不处理中断,任务仍可能继续占用线程或产生副作用。
基本语法
Future.get(timeout, unit) 只限制等待时间,到期会抛出 TimeoutException,不会自动停止任务。捕获超时后调用 cancel(true) 请求中断,并让任务在阻塞点或循环中正确响应 InterruptedException、Thread.currentThread().isInterrupted()。
CompletableFuture.orTimeout(...) 会让结果以超时异常完成,但同样不保证底层任务被中断。HTTP、数据库和消息客户端仍需分别配置连接、读取、查询或请求超时。
主示例
下面示例最多等待 300 毫秒,然后请求中断后台任务。任务捕获中断后恢复线程中断标记并退出。
import java.util.concurrent.*;
public class TimeoutDemo {
public static void main(String[] args) throws InterruptedException {
ExecutorService executor = Executors.newSingleThreadExecutor();
Future<String> future = executor.submit(() -> {
try {
Thread.sleep(2_000);
return "SUCCESS";
} catch (InterruptedException ex) {
// 保留中断语义,避免上层误判为正常结束
Thread.currentThread().interrupt();
System.out.println("worker=INTERRUPTED");
throw ex;
}
});
String result;
try {
result = future.get(300, TimeUnit.MILLISECONDS);
} catch (TimeoutException ex) {
result = future.cancel(true)
? "TIMEOUT_CANCEL_REQUESTED"
: "TIMEOUT_TASK_FINISHED";
} catch (ExecutionException ex) {
result = "FAILED:" + ex.getCause().getClass().getSimpleName();
} finally {
executor.shutdownNow();
executor.awaitTermination(2, TimeUnit.SECONDS);
}
System.out.println("result=" + result);
}
}编译并运行:
javac TimeoutDemo.java
java TimeoutDemo预期输出:
worker=INTERRUPTED
result=TIMEOUT_CANCEL_REQUESTED第一行表示任务实际响应了中断;第二行只表示取消请求已被接受,不代表数据库事务或外部系统副作用已经回滚。
Spring 服务落地
生产环境应注入统一管理的线程池,不要在每次请求中创建 ExecutorService。接口总截止时间应覆盖线程池排队、下游调用、重试退避和序列化,并给调用方预留返回时间。
调用链较长时传递绝对截止时间或剩余毫秒数。下游预算不足应快速失败,而不是继续使用固定超时。对于有副作用的操作,超时后的自动重试必须配合幂等键和状态查询。
风险与边界
cancel(true) 只是发送中断请求。任务若吞掉 InterruptedException、持续计算却不检查中断,或底层驱动不支持取消,任务仍会继续。安全替代方案是使用客户端原生超时、可取消 API,或将不可控任务隔离到独立进程。
调用方收到超时不等于业务失败。外部支付可能已经成功、本地响应却丢失;数据库事务也不会因网关超时自动回滚。此类结果应标记为“未知”,通过查询、Outbox 或补偿流程确认最终状态。
排障清单
- 已返回超时但线程仍占用:检查是否调用
cancel(true),以及任务是否正确处理中断。 - 超时不生效:检查是否在
get前同步阻塞,或使用了无超时的join()。 - 线程池持续满载:检查队列长度、任务耗时、拒绝策略和不可中断调用。
- 超时后出现重复数据:检查重试策略、幂等键、业务唯一约束和原任务状态查询。
- 大量请求同时超时:优先排查共享下游、连接池耗尽和线程池排队,不要只调大超时值。
速查结论:等待超时保护调用方,取消和下游超时保护资源,幂等与状态查询保护业务结果。
防止重试或重复提交造成重复扣款、创建或状态变更。
设计幂等接口
创建、扣款、发券或状态变更接口必须保证同一业务请求重复提交时只产生一次效果。推荐由客户端携带 Idempotency-Key,服务端通过数据库唯一约束抢占执行权、校验请求摘要,并重放首次完成的响应。
接口约定
幂等键应由调用方生成随机值,并在同一次重试中保持不变。唯一范围通常使用“租户或用户 + HTTP 方法 + 路由 + 幂等键”,避免不同用户或不同接口互相冲突。
同一键再次到达时:请求摘要一致且已成功,返回首次响应;摘要不同,返回 409 Conflict;首次请求仍处理中,返回 202 或 409 并提供查询方式;只有租约过期且确认业务未执行时,才允许重新抢占。

存储与原子性
幂等记录至少保存作用域、幂等键、请求摘要、状态、响应状态码、响应体、租约和过期时间。必须建立数据库唯一约束,不能只使用“先查询再插入”,否则并发请求可能同时查不到记录并各自执行一次。
CREATE TABLE api_idempotency (
scope_key varchar(200) NOT NULL,
idempotency_key varchar(100) NOT NULL,
request_hash char(64) NOT NULL,
status varchar(20) NOT NULL,
http_status integer,
response_body jsonb,
lease_until timestamptz,
expires_at timestamptz NOT NULL,
PRIMARY KEY (scope_key, idempotency_key),
CHECK (status IN ('PROCESSING', 'SUCCEEDED', 'FAILED'))
);预期结果:
CREATE TABLE处理时先执行带冲突检测的插入。插入成功者成为唯一执行者,在同一数据库事务内完成业务写入并保存响应;插入失败者读取已有记录,比较 request_hash 后返回缓存结果或冲突状态。业务表还应设置订单号、支付流水号等唯一约束作为第二道防线。
验证重复提交
服务部署到本机 <PORT> 后,连续发送两次相同请求。实际端口和订单 ID 会不同。
KEY="8a3b2df1-24fd-4e04-8a3c-10dd7c43d024"
curl -i -X POST "http://localhost:<PORT>/orders" -H "Content-Type: application/json" -H "Idempotency-Key: ${KEY}" -d '{"sku":"book-001","quantity":1}'
curl -i -X POST "http://localhost:<PORT>/orders" -H "Content-Type: application/json" -H "Idempotency-Key: ${KEY}" -d '{"sku":"book-001","quantity":1}'预期结果:
两次请求返回同一个订单 ID <ID>。
orders 表只新增 1 行。
第二次请求重放首次响应,不再次创建订单。将第二次请求的 quantity 改为 2 后,应返回 409 Conflict,防止同一幂等键承载不同业务意图。
风险与边界
幂等记录与业务写入不在同一事务时,可能出现业务成功但状态仍为 PROCESSING。数据库内操作应放在同一事务;调用支付或库存等外部系统时,应继续向下游传递幂等键,并使用 Outbox、状态查询或补偿流程处理跨系统不一致。
不能简单删除所有失败记录。稳定的 2xx 和不可重试 4xx 通常可以缓存;连接失败、超时和临时 5xx 应结合业务状态与租约决定是否重试。调用方超时后,原请求可能仍在执行。
TTL 过短会让迟到重试再次执行,过长会增加存储量并阻止合法新请求。过期时间至少覆盖客户端最大重试窗口和消息重复投递窗口,清理前还要确认业务唯一键仍可阻止重复效果。
排障清单
- 并发请求产生重复数据:检查数据库唯一约束和是否存在非原子的“查询后插入”。
- 同一键返回不同结果:检查响应是否在事务内保存,以及缓存是否被后续请求覆盖。
- 大量记录停在
PROCESSING:检查实例崩溃、事务超时、租约修复任务和外部调用状态。 - 正常重试收到 409:检查 JSON 规范化是否稳定,字段顺序、空值和默认值是否改变摘要。
- 键冲突跨用户出现:检查唯一范围是否包含租户或用户、方法和路由。
速查结论:幂等键识别同一次请求,唯一约束决定唯一执行者,请求摘要防止键被误用,响应快照让重试得到同一结果。
通过 Spring Cloud Stream 将领域事件发送到消息中间件。
发布业务事件
当业务动作由 HTTP、数据库事务或定时任务触发,而不是由 Supplier 周期产生消息时,使用 StreamBridge 把领域事件发送到 Spring Cloud Stream 输出绑定。固定绑定名和目标主题,能避免业务代码直接依赖 Kafka 或 RabbitMQ 客户端。
依赖与绑定配置
以下依赖片段放入已经由 Spring Cloud BOM 管理版本的 Spring Boot 项目。示例使用 Kafka Binder;改用 RabbitMQ 时只替换 Binder 依赖,Java 发送代码保持不变。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-stream-binder-kafka</artifactId>
</dependency>
</dependencies>显式声明 orderEvents-out-0,让绑定在应用启动时创建,并把它映射到中间件目标 order-events。
spring:
cloud:
stream:
output-bindings: orderEvents-out-0
bindings:
orderEvents-out-0:
destination: order-events
content-type: application/json
kafka:
binder:
brokers: localhost:9092
完整发送示例
下面的接口构造不可变事件,附加事件类型和版本头,再发送到固定输出绑定。send 返回 false 时立即返回 503,避免把未进入发送链路的请求误报为成功。
package com.example.publisher;
import java.math.BigDecimal;
import java.time.Instant;
import java.util.UUID;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.stream.function.StreamBridge;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.messaging.Message;
import org.springframework.messaging.support.MessageBuilder;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class EventPublisherApplication {
public static void main(String[] args) {
SpringApplication.run(EventPublisherApplication.class, args);
}
}
@RestController
@RequestMapping("/orders")
class OrderEventController {
private final StreamBridge streamBridge;
OrderEventController(StreamBridge streamBridge) {
this.streamBridge = streamBridge;
}
@PostMapping("/{orderId}/paid")
ResponseEntity<PublishResponse> publishPaid(
@PathVariable String orderId,
@RequestBody PayRequest request) {
OrderPaidEvent event = new OrderPaidEvent(
UUID.randomUUID().toString(),
orderId,
request.amount(),
Instant.now());
Message<OrderPaidEvent> message = MessageBuilder.withPayload(event)
.setHeader("eventType", "OrderPaid")
.setHeader("eventVersion", "1")
.build();
boolean accepted = streamBridge.send("orderEvents-out-0", message);
if (!accepted) {
throw new ResponseStatusException(
HttpStatus.SERVICE_UNAVAILABLE, "event send rejected");
}
return ResponseEntity.accepted()
.body(new PublishResponse(event.eventId(), true));
}
}
record PayRequest(BigDecimal amount) {
}
record PublishResponse(String eventId, boolean accepted) {
}
record OrderPaidEvent(
String eventId,
String orderId,
BigDecimal amount,
Instant occurredAt) {
}预期结果
Started EventPublisherApplication in <TIME> seconds调用与验证
启动 Kafka 和应用后发送一次支付事件。
curl -i -X POST http://localhost:8080/orders/O-1001/paid \
-H 'Content-Type: application/json' \
-d '{"amount":199.00}'预期结果
HTTP/1.1 202
Content-Type: application/json
{"eventId":"<ID>","accepted":true}再从目标主题读取一条消息;<ID> 和 <TIME> 每次运行都会变化。
kafka-console-consumer.sh \
--bootstrap-server localhost:9092 \
--topic order-events \
--from-beginning \
--max-messages 1预期输出
{"eventId":"<ID>","orderId":"O-1001","amount":199.00,"occurredAt":"<TIME>"}关键行为与边界
StreamBridge.send(bindingName, data) 的第一个参数是绑定名,不是必须等同于主题名;真正的目标由 spring.cloud.stream.bindings.<bindingName>.destination 决定。发送 POJO 或 Message 时,绑定的 content-type、消息头和 Binder 配置共同决定转换与投递行为。
send 返回 true 只说明消息被发送通道接受,不能证明 Broker 已持久化,更不能证明消费者已经处理完成。需要端到端确认时,应设计业务回执、状态查询或补偿流程,而不是把布尔返回值当作最终交付凭证。
风险与排障
数据库提交与消息发送是两个独立动作时,进程崩溃可能造成“订单已提交但事件未发送”或重复发送。核心业务优先使用事务 Outbox:同一数据库事务写业务数据和事件表,再由独立发布器可靠转发,并让消费者按 eventId 幂等处理。
排查时按顺序确认:绑定名与配置键完全一致;应用已加载正确 Binder;Broker 地址可达;主题或交换机允许创建;序列化没有异常;生产端日志不存在发送超时。不要把用户输入直接作为动态目标名,否则可能创建大量目标与绑定;确需动态路由时,应限制允许列表并监控绑定缓存。
示例采用函数式 Spring Cloud Stream 配置,不要与旧式 @EnableBinding、@Output 接口模型混用。
声明消息消费者并配置消费组、目标主题和内容转换。
消费业务消息
使用 Consumer<T> 声明无返回值的消息处理器,并通过函数名生成输入绑定。目标主题、消费组和内容类型全部放在配置中,业务代码只处理已经转换为领域事件的负载。
消费模型与配置
函数 handleOrderPaid 的默认输入绑定名是 handleOrderPaid-in-0。同一目标下,不同消费组各收到一份消息;同一组的多个实例竞争消费,每条消息只交给组内一个实例处理。
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-stream-binder-kafka</artifactId>
</dependency>下面配置把消费者绑定到 order-events,固定组名为 billing-service,启用三个并发消费者,并在处理失败三次后将消息送入指定 DLQ。
spring:
cloud:
function:
definition: handleOrderPaid
stream:
bindings:
handleOrderPaid-in-0:
destination: order-events
group: billing-service
content-type: application/json
consumer:
concurrency: 3
max-attempts: 3
back-off-initial-interval: 1000
kafka:
binder:
brokers: localhost:9092
bindings:
handleOrderPaid-in-0:
consumer:
enable-dlq: true
dlq-name: order-events.billing-service.dlq
完整消费者示例
泛型参数 Message<OrderPaidEvent> 让处理器同时取得领域对象和消息头。业务校验失败时抛出异常,交由 Binder 的重试与 DLQ 策略处理;不要在代码中捕获异常后静默返回,否则框架会把该消息视为消费成功。
package com.example.consumer;
import java.math.BigDecimal;
import java.time.Instant;
import java.util.function.Consumer;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.messaging.Message;
@SpringBootApplication
public class OrderMessageConsumerApplication {
public static void main(String[] args) {
SpringApplication.run(OrderMessageConsumerApplication.class, args);
}
@Bean
Consumer<Message<OrderPaidEvent>> handleOrderPaid() {
return message -> {
OrderPaidEvent event = message.getPayload();
// 失败必须抛出,让重试和 DLQ 能观察到处理结果。
if (event.amount() == null || event.amount().signum() <= 0) {
throw new IllegalArgumentException("amount must be positive");
}
// 真实系统应在这里执行带 eventId 唯一约束的幂等写入。
System.out.printf(
"consumed eventId=%s orderId=%s amount=%s%n",
event.eventId(), event.orderId(), event.amount());
};
}
}
record OrderPaidEvent(
String eventId,
String orderId,
BigDecimal amount,
Instant occurredAt) {
}预期结果
Started OrderMessageConsumerApplication in <TIME> seconds发送测试消息
应用启动后,用 Kafka 控制台生产者发送一条与领域类型匹配的 JSON。该命令成功时通常不打印业务输出,实际处理结果应查看消费者日志。
printf '%s\n' \
'{"eventId":"evt-1001","orderId":"O-1001","amount":199.00,"occurredAt":"2026-08-05T05:20:00Z"}' \
| kafka-console-producer.sh \
--bootstrap-server localhost:9092 \
--topic order-events预期输出
consumed eventId=evt-1001 orderId=O-1001 amount=199.00关键配置与边界
destination 决定读取哪个主题或交换机,group 决定广播还是组内竞争。生产环境应显式设置稳定组名;未设置组名会创建匿名独立组,多个实例可能各自收到消息,并且重启后的消费位置语义依 Binder 而异。
content-type: application/json 配合函数泛型完成 JSON 到 OrderPaidEvent 的转换。若启用 use-native-decoding,转换责任转交 Kafka 反序列化器,此时必须配置能生成目标类型的反序列化器,不能再依赖绑定的内容类型自动转换。
Kafka 的有效并行度受主题分区数限制;把 concurrency 设置得高于分区数不会获得等量吞吐,只会产生空闲消费者。扩容前同时检查分区数、单条处理耗时、下游数据库连接池和幂等约束。
风险与排障
消息系统通常允许重复投递。消费者必须以 eventId 建唯一键或处理记录,确保重复消息不会重复扣款、发货或记账。不要仅依赖内存集合去重,实例重启或横向扩容后会失效。
没有消费日志时,依次检查 spring.cloud.function.definition 是否指向 Bean 名、输入绑定名是否拼写一致、目标和组名是否正确、Broker 是否可达、组内是否已有其他实例取得消息。转换异常时核对 JSON 字段名、时间格式和数值类型;业务异常时检查重试日志及 order-events.billing-service.dlq。关闭自动建主题后,应提前创建主主题和 DLQ,并保证分区规划满足消费并发。
示例使用命令式函数消费者;响应式 Flux 消费者的异常、重试与背压处理模型不同,不应直接照搬这里的重试结论。
为消费异常配置重试、死信队列和人工补偿入口。
处理失败消息
消费方法抛出异常时,先让绑定层做有限重试;仍失败的消息进入死信队列,再由受控补偿入口重放。这样可避免无限阻塞消费线程,也能保留失败原因、原始消息和人工操作记录。

配置重试与死信队列
下面以 Spring Cloud Stream RabbitMQ Binder 为例。max-attempts 包含首次消费,因此配置为 4 表示最多执行 1 次初始调用和 3 次重试;退避间隔依次增长,超过上限后进入固定死信队列。
spring:
cloud:
function:
definition: orderConsumer
stream:
bindings:
orderConsumer-in-0:
destination: order.events
group: order-service
consumer:
max-attempts: 4
back-off-initial-interval: 1000
back-off-multiplier: 2.0
back-off-max-interval: 10000
rabbit:
bindings:
orderConsumer-in-0:
consumer:
auto-bind-dlq: true
republish-to-dlq: true
dead-letter-queue-name: order.events.order-service.dlq生效后,同一消息在消费异常时按约 1 秒、2 秒、4 秒退避重试;最终仍失败时,Binder 将消息发布到 order.events.order-service.dlq。实际间隔还会受线程调度和 Broker 延迟影响。
区分可重试与不可重试异常
网络超时、临时数据库锁等瞬时故障可以重试;参数缺失、业务状态非法等确定性错误不应反复执行。可在同一绑定下关闭默认重试,只显式放行瞬时异常。
spring:
cloud:
stream:
bindings:
orderConsumer-in-0:
consumer:
max-attempts: 4
default-retryable: false
retryable-exceptions:
java.net.SocketTimeoutException: true
org.springframework.dao.TransientDataAccessException: true生效行为:列表中的异常按退避策略重试,其他异常直接进入恢复流程。消费代码不要捕获异常后仅记录日志并正常返回,否则 Binder 会把消息视为成功,既不会重试也不会投递死信。
验证死信是否产生
先投递一条必然触发异常的测试消息,再在 RabbitMQ 节点执行队列查询。<COUNT> 是动态值,只要大于 0,说明死信已进入队列。
rabbitmqctl list_queues name messages_ready consumers | grep 'order.events.order-service.dlq'预期输出
order.events.order-service.dlq <COUNT> 0若使用 republish-to-dlq,还应检查死信消息中的异常说明、原交换机和原路由键等头信息,确认失败上下文可用于补偿判断。
人工补偿入口
补偿入口应按消息 ID 查询死信内容,重新校验当前业务状态,记录操作人、原因和次数,再发布到独立的重放通道。不要直接修改业务表后删除死信,否则无法审计,也可能遗漏原消息触发的其他副作用。
建议把重放设计为幂等操作:同一消息重复提交只生成一个补偿任务;达到重放上限后转入隔离区,由人工修复数据或代码,而不是继续循环投递。
风险与排障清单
- 重试次数过大或退避过短会长期占用消费线程并放大下游故障;优先使用有限重试、熔断和死信隔离。
- 应用若在异常后返回成功,死信链路不会触发;确认异常最终抛出到 Binder。
- 死信队列未创建时,检查绑定名、消费者组、Broker 权限和 Rabbit Binder 扩展配置是否对应。
- 同一毒消息反复从死信重放会形成循环;重放前必须做状态校验、次数限制和审计。
- Kafka Binder 的死信属性与 RabbitMQ Binder 不同,不能直接复制本例的
rabbit扩展配置。
通过业务键、去重记录或状态校验避免消息重复执行。
保证消息幂等
消息系统通常采用至少一次投递,消费成功但确认丢失时,同一消息可能再次到达。可靠做法是选取稳定业务键,并在同一数据库事务中完成“登记去重记录”和“更新业务状态”;重复消息应正常返回,而不是再次执行副作用。

选择稳定幂等键
优先使用上游生成且跨重试不变的 eventId。没有事件 ID 时,可使用能唯一代表一次业务效果的组合键,例如 orderId + eventType + version。不要在消费端临时生成 UUID,因为每次重投都会得到新值,无法识别重复消息。
幂等键的粒度必须与副作用一致。订单支付事件可按支付流水号去重;库存扣减则应按“业务单号 + 商品 + 操作版本”去重,避免把合法的多次操作误判为重复。
建立去重表
以下 PostgreSQL 表用消费者名称和消息 ID 组成主键。加入消费者名称后,同一事件可以被不同业务消费者各处理一次,而不会互相误判。
CREATE TABLE consumed_message (
consumer_name text NOT NULL,
message_id text NOT NULL,
processed_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (consumer_name, message_id)
);预期结果
CREATE TABLE在同一事务中登记并更新
下面是片段示例,依赖 Spring Boot、Spring Cloud Stream、spring-jdbc 和 PostgreSQL,函数绑定名为 orderPaid-in-0。TransactionTemplate 把去重登记与业务更新包在同一事务中,任一步失败都会整体回滚。
package com.example.message;
import java.time.OffsetDateTime;
import java.util.function.Consumer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.messaging.Message;
import org.springframework.transaction.support.TransactionTemplate;
@Configuration
public class OrderPaidBinding {
@Bean
Consumer<Message<OrderPaidEvent>> orderPaid(
JdbcTemplate jdbc,
TransactionTemplate transactions) {
return message -> transactions.executeWithoutResult(status -> {
OrderPaidEvent event = message.getPayload();
int inserted = jdbc.update(
"INSERT INTO consumed_message(consumer_name, message_id) " +
"VALUES (?, ?) ON CONFLICT DO NOTHING",
"order-paid", event.eventId()
);
// 重复消息正常返回,让 Broker 完成确认,避免无意义重试。
if (inserted == 0) {
return;
}
int updated = jdbc.update(
"UPDATE orders SET paid = true, paid_at = ? " +
"WHERE id = ? AND paid = false",
event.paidAt(), event.orderId()
);
// 状态冲突时抛错,去重记录会随当前事务一起回滚。
if (updated != 1) {
throw new IllegalStateException(
"order state conflict: " + event.orderId()
);
}
});
}
public record OrderPaidEvent(
String eventId,
long orderId,
OffsetDateTime paidAt
) {}
}生效行为:首次消息插入去重记录并更新订单;相同 eventId 再次到达时,inserted 为 0,消费者直接返回。若业务更新失败,数据库事务回滚,去重记录不会残留,后续重试仍可重新处理。
验证唯一约束
在测试库执行两次相同插入,第二次应被唯一约束忽略,最终只保留一条记录。
BEGIN;
INSERT INTO consumed_message(consumer_name, message_id)
VALUES ('order-paid', 'evt-1001')
ON CONFLICT DO NOTHING;
INSERT INTO consumed_message(consumer_name, message_id)
VALUES ('order-paid', 'evt-1001')
ON CONFLICT DO NOTHING;
SELECT count(*) FROM consumed_message
WHERE consumer_name = 'order-paid'
AND message_id = 'evt-1001';
ROLLBACK;预期输出
BEGIN
INSERT 0 1
INSERT 0 0
count
-------
1
(1 row)
ROLLBACK风险与排障清单
- 去重记录与业务更新分两次提交,会出现“已登记但业务未完成”或“业务已完成但未登记”;必须放进同一事务。
- 仅使用带过期时间的缓存去重,消息在 TTL 之后重投时仍会重复执行;关键业务应以持久化唯一约束为准。
- 重复消息应正常返回;若主动抛异常,Binder 会继续重试并增加积压。
- 条件更新返回 0 时,检查订单是否已完成、事件是否乱序、幂等键是否过粗,不要直接忽略状态冲突。
- 数据库事务无法回滚已经发出的 HTTP 请求或第三方扣款;外部副作用应继续传递幂等键,或通过 Outbox/Inbox 模式异步执行。
- 示例中的
record需要 Java 16 及以上;Java 8/11 可替换为带无参构造和访问方法的普通 DTO。 - 若重复仍被执行,检查唯一索引是否已部署、事务是否真正生效,以及消息每次重投时的
eventId是否保持一致。
使用事务消息、Outbox 或补偿机制协调数据库与消息状态。
避免数据库与消息双写不一致
当一次业务操作既要更新数据库又要发送消息时,不要按“先写库再发消息”或“先发消息再写库”直接串联。生产环境优先用 Outbox:业务数据和事件记录在同一个本地事务中提交,再由独立发布器把事件投递到消息系统;发布器允许重试,消费者必须按事件 ID 幂等。
一致性链路

关键点不是保证消息“只发送一次”,而是保证业务提交后事件不会丢失,并把重复投递收敛为无副作用。数据库事务只覆盖业务表和 Outbox 表,不能把 RabbitMQ、Kafka 或远程 HTTP 调用纳入同一个本地事务。
Outbox 最小实现
以下 PostgreSQL 示例可直接执行,用同一事务写入订单和待发布事件。event_id 应全局唯一,aggregate_id 用于同一业务对象的顺序控制,payload 保存消费者需要的最小事实数据。
CREATE TABLE orders (
order_id varchar(64) PRIMARY KEY,
status varchar(32) NOT NULL
);
CREATE TABLE outbox_event (
event_id varchar(64) PRIMARY KEY,
aggregate_id varchar(64) NOT NULL,
event_type varchar(128) NOT NULL,
payload jsonb NOT NULL,
status varchar(16) NOT NULL DEFAULT 'NEW',
created_at timestamptz NOT NULL DEFAULT now(),
published_at timestamptz
);
BEGIN;
INSERT INTO orders(order_id, status)
VALUES ('order-1001', 'CREATED');
INSERT INTO outbox_event(event_id, aggregate_id, event_type, payload)
VALUES (
'evt-1001',
'order-1001',
'OrderCreated',
'{"orderId":"order-1001","status":"CREATED"}'
);
COMMIT;
SELECT event_id, aggregate_id, event_type, status
FROM outbox_event
WHERE event_id = 'evt-1001';预期结果:
event_id | aggregate_id | event_type | status
----------+--------------+--------------+--------
evt-1001 | order-1001 | OrderCreated | NEW读到 NEW 表示业务事务和事件记录已经一起提交,但消息尚未被发布器确认。若订单存在而对应事件不存在,说明写入没有处于同一事务、异常被吞掉,或代码绕过了统一的业务入口。
发布与幂等
发布器每次领取一小批 NEW 事件,发送成功并收到 Broker 确认后再标记 SENT。进程可能在“Broker 已接收、数据库尚未更新”之间崩溃,因此重启后会重复发送;消息体必须携带 event_id,消费者用唯一键记录已处理事件。
下面是消费端去重表的核心 SQL,可在消费业务事务开始时执行:
CREATE TABLE consumed_event (
consumer_name varchar(128) NOT NULL,
event_id varchar(64) NOT NULL,
consumed_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (consumer_name, event_id)
);
INSERT INTO consumed_event(consumer_name, event_id)
VALUES ('inventory-service', 'evt-1001')
ON CONFLICT DO NOTHING;预期结果:
INSERT 0 1首次返回 INSERT 0 1 时继续执行业务更新;重复消息返回 INSERT 0 0,应直接确认消息,不再重复扣库存或创建记录。去重写入和消费者的业务变更也要处于同一个本地事务。
模式选择
| 场景 | 首选方案 | 边界 |
|---|---|---|
| 单库事务后可靠发消息 | Outbox + 轮询或 CDC | 默认至少一次投递,必须幂等 |
| Broker 明确支持事务消息且团队已标准化 | 事务消息 | 仍要处理回查、超时和重复消费 |
| 跨多个服务的长事务 | Saga/补偿 | 补偿不是数据库回滚,必须可重试和审计 |
不要用“捕获发送异常后删除业务数据”模拟分布式回滚。触发条件是消息系统超时、网络抖动或进程崩溃;后果可能是误删已对外可见的数据,且补偿本身仍可能失败。安全替代是持久化待处理状态,异步重试,并为不可自动恢复的事件进入人工处置队列。
排障清单
检查顺序应从数据库事实开始,再看发布器和消费者:
- 业务记录存在但 Outbox 记录缺失:核对是否共用同一数据源、同一事务管理器,方法是否经过 Spring 代理,是否发生自调用导致
@Transactional失效。 NEW长时间堆积:检查发布任务是否运行、数据库锁等待、批次大小、Broker 连通性和发布确认。SENT已增加但下游无结果:检查交换机或 Topic 路由、消费者组、死信队列和消费异常日志。- 同一事件被处理多次:检查消息中是否稳定携带
event_id,去重表唯一键是否正确,去重记录与业务更新是否同事务。 - 同一订单事件乱序:按
aggregate_id固定分区或串行化发布,不要只依赖全局时间戳排序。
速查结论:本地事务保证“业务数据与待发事件同时存在”,发布重试保证“最终送达”,消费幂等保证“重复送达不产生重复副作用”。
在网关验证访问令牌并拒绝未认证或权限不足的请求。
在网关保护接口
在 Spring Cloud Gateway 入口校验 Bearer Token,并按路由、HTTP 方法或 Scope 拒绝未认证和权限不足的请求。推荐把网关配置为 OAuth 2.0 Resource Server:签名无效、令牌过期或缺失返回 401;身份有效但权限不足返回 403。
请求校验链路

网关是第一道边界,不应只解析 JWT 后盲目信任声明。至少校验签名、iss、有效期,并限制可接受的算法。对高价值接口,下游服务仍应独立验证令牌;若只在网关验证,则必须保证下游仅能被网关通过受控网络或 mTLS 访问。
依赖与发行者配置
Maven 片段示例,放入网关项目的 <dependencies> 中。它依赖 Spring Cloud Gateway 的 WebFlux 技术栈,不能同时改成 Servlet 安全配置。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>在 application.yml 配置令牌发行者。issuer-uri 必须与 JWT 的 iss 完全一致,Spring Security 会通过发行者元数据定位 JWK,并在本地完成后续签名校验。
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://id.example.com/realms/prod生效行为:应用启动后构建 JWT 解码器;请求到达时校验签名、发行者和时间声明。若生产环境启动时不能访问发行者元数据,可改用固定 jwk-set-uri,但必须自行保证发行者校验和密钥轮换策略。
按接口授权
下面的配置类可直接用于 WebFlux 网关。scope 声明默认映射为带 SCOPE_ 前缀的权限,例如令牌中的 orders.read 对应 SCOPE_orders.read。
package com.example.gateway;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.HttpMethod;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.reactive.EnableWebFluxSecurity;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;
@Configuration
@EnableWebFluxSecurity
public class GatewaySecurityConfig {
@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
return http
// 网关提供无状态 API,不使用浏览器表单会话。
.csrf(ServerHttpSecurity.CsrfSpec::disable)
.authorizeExchange(exchanges -> exchanges
.pathMatchers("/actuator/health").permitAll()
.pathMatchers(HttpMethod.GET, "/api/orders/**")
.hasAuthority("SCOPE_orders.read")
.pathMatchers(HttpMethod.POST, "/api/orders/**")
.hasAuthority("SCOPE_orders.write")
.anyExchange().authenticated()
)
.oauth2ResourceServer(oauth2 ->
oauth2.jwt(Customizer.withDefaults())
)
.build();
}
}验证缺少令牌的请求:
curl -i https://gateway.example.com/api/orders/1001预期结果:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer再用仅含 orders.read Scope 的有效令牌请求写接口:
curl -i -X POST \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"orderId":"order-1001"}' \
https://gateway.example.com/api/orders预期结果:
HTTP/1.1 403 Forbidden实际响应日期、追踪头和正文可能不同;判断重点是状态码。有效令牌包含 orders.write 时,该请求才会进入路由并由下游返回业务状态码。
入口边界
不要把“能通过网关”视为拥有所有后端权限。触发风险的常见条件包括:管理端点被误设为 permitAll、宽泛的 /** 规则排在精确规则之前、下游端口可被公网直连、或直接信任客户端传入的 X-User-Id 和 X-Role。可能后果是认证绕过、水平越权和伪造身份。
安全替代方案是遵循最小权限:只公开健康探针所需路径;授权规则从具体到宽泛;入口删除可伪造的身份头;下游继续验证 JWT,或仅接受网关经 mTLS 建立的连接以及经过签名的内部身份信息。记录拒绝原因时不要打印完整令牌。
排障清单
- 全部请求都是
401:核对issuer-uri、系统时间、JWT 的iss、exp、签名算法和 JWKkid。 - 有效令牌仍返回
403:解码令牌检查scope或scp,确认权限映射结果是否为SCOPE_...,并核对 HTTP 方法和路径匹配。 - 网关启动失败:检查发行者元数据或 JWK 地址的 DNS、TLS 证书、代理和超时;不要用关闭 TLS 校验作为长期修复。
- 规则未命中:开启 Spring Security 调试日志进行短时定位,确认请求经过的是 WebFlux
SecurityWebFilterChain,而不是误配的 Servlet 过滤链。 - 下游仍可绕过:收紧安全组、Kubernetes NetworkPolicy 或服务网格策略,只允许网关访问业务服务入口。
速查结论:401 解决“你是谁或令牌是否可信”,403 解决“你是否有权访问该接口”;两者都应在路由转发前完成。
将业务服务配置为 OAuth 2.0 资源服务器并校验令牌。
保护资源服务
把 Spring Boot 业务服务配置成 OAuth 2.0 资源服务器后,请求必须携带可验证的访问令牌。下面示例使用 JWT、授权服务器的 issuer 元数据和基于权限的接口保护,适合纯 Bearer Token API。
最小配置
在已有 Spring Boot Web 项目中加入资源服务器依赖。若项目使用 Spring Boot 依赖管理,不要单独写版本号。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>配置令牌签发者地址。资源服务器会发现 JWKS,校验 JWT 签名,并检查 iss、exp、nbf 等标准声明。
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://id.example.com/realms/acme使用无状态安全链保护接口。只有纯 Bearer Token API 才应关闭 CSRF;同时使用 Cookie 登录的应用应保留 CSRF,或拆分独立的安全链。
package com.example.security;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.Customizer;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.web.SecurityFilterChain;
@Configuration
public class SecurityConfig {
@Bean
SecurityFilterChain apiSecurity(HttpSecurity http) throws Exception {
http
// 仅适用于不依赖浏览器 Cookie 的无状态 Bearer Token API
.csrf(AbstractHttpConfigurer::disable)
.sessionManagement(session ->
session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
.authorizeHttpRequests(auth -> auth
.requestMatchers("/actuator/health").permitAll()
.requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
.anyRequest().authenticated())
.oauth2ResourceServer(oauth2 ->
oauth2.jwt(Customizer.withDefaults()));
return http.build();
}
}默认情况下,JWT 的 scope 或 scp 会映射为带 SCOPE_ 前缀的权限。因此令牌包含 admin scope 时,才能访问 /api/admin/**。
验证保护是否生效
先对任意受保护接口发送不带令牌的请求。
curl -i http://localhost:8080/api/orders/42预期输出只需关注状态码和认证头,其他响应头可能不同。
HTTP/1.1 401
WWW-Authenticate: Bearer再使用授权服务器签发给本资源服务的访问令牌。
curl -i \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
http://localhost:8080/api/orders/42令牌有效且权限满足时,预期结果为业务接口自己的成功响应,例如:
HTTP/1.1 200
Content-Type: application/json
{"id":42,"status":"PAID"}<ACCESS_TOKEN> 必须替换为真实访问令牌;响应体取决于实际接口。若接口不存在,先用项目中已有的受保护接口验证,不要把 404 误判为令牌校验失败。
风险与边界
仅校验签名和签发者并不一定能阻止“发给其他 API 的令牌”被使用。授权服务器会为多个资源服务签发令牌时,应增加 aud 校验;否则可能接受受众不匹配但签名合法的令牌。
不要把不透明令牌当成 JWT 解析。令牌不是三段式 JWT 时,应改用 OAuth 2.0 introspection 的 opaque-token 配置,否则会持续返回 401 invalid_token。
不要为了排障关闭签名、过期时间或签发者校验。安全替代方案是核对令牌头中的 kid、声明中的 iss、aud、exp,并确认资源服务能访问授权服务器的元数据和 JWKS 地址。
排障清单
401 invalid_token:检查令牌是否过期、iss是否与issuer-uri完全一致、kid是否能在当前 JWKS 中找到。403 Forbidden:令牌通常已通过认证,但缺少SCOPE_admin等所需权限;检查 scope 与权限前缀。- 应用启动失败:检查
issuer-uri是否可访问、TLS 证书是否可信、元数据是否返回有效的 JWKS 地址。 - 经网关后始终
401:确认网关和反向代理没有删除或改写Authorization请求头。
速查结论:401 优先查令牌有效性,403 优先查授权规则与权限映射。
从安全上下文中获取用户、角色、租户和令牌声明。
读取用户身份
在资源服务器中,优先从 Spring Security 已验证的 Jwt 和 Authentication 读取身份,不要自行解码原始令牌。这样拿到的用户、权限、租户和声明都来自已通过签名与时效校验的安全上下文。
控制器中读取
下面接口读取主题标识、显示用户名、租户、权限和过期时间。字段名必须与授权服务器实际声明一致;示例假设令牌包含 preferred_username 和 tenant_id。
package com.example.identity;
import java.time.Instant;
import java.util.List;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.jwt.Jwt;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationToken;
import org.springframework.security.core.annotation.AuthenticationPrincipal;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api")
public class MeController {
@GetMapping("/me")
public MeView me(
@AuthenticationPrincipal Jwt jwt,
JwtAuthenticationToken authentication) {
// 权限来自认证转换结果,不直接信任任意 roles 字符串
List<String> authorities = authentication.getAuthorities().stream()
.map(GrantedAuthority::getAuthority)
.sorted()
.toList();
return new MeView(
jwt.getSubject(),
jwt.getClaimAsString("preferred_username"),
jwt.getClaimAsString("tenant_id"),
authorities,
jwt.getExpiresAt());
}
public record MeView(
String subject,
String username,
String tenantId,
List<String> authorities,
Instant expiresAt) {
}
}调用接口:
curl -sS \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
http://localhost:8080/api/me令牌包含相应声明时,预期结果类似:
{"subject":"<SUBJECT>","username":"<USERNAME>","tenantId":"<TENANT_ID>","authorities":["SCOPE_orders.read"],"expiresAt":"<TIME>"}<SUBJECT>、<USERNAME>、<TENANT_ID> 和 <TIME> 由实际令牌决定。若声明不存在,username 或 tenantId 会是 null;这应被视为身份契约不匹配,而不是自动使用不可信的请求头兜底。
常用读取入口
在 MVC 控制器中,@AuthenticationPrincipal Jwt 最直接;需要权限和认证名称时同时注入 JwtAuthenticationToken。jwt.getClaims() 可读取完整声明,但业务代码应优先白名单读取必需字段,避免把整个令牌内容写入日志或返回给前端。
在服务层中,优先把已经提取出的不可变 CurrentUser 参数传入业务方法。确需访问上下文时,可读取 SecurityContextHolder,但必须先判断认证类型和 isAuthenticated(),避免匿名认证或非 JWT 登录导致类型转换异常。
角色、Scope 与租户
默认 JWT 资源服务器通常把 scope 或 scp 转为 SCOPE_xxx 权限。令牌里的自定义 roles、嵌套角色或租户字段不会自动获得业务语义,必要时应通过 JwtAuthenticationConverter 映射,并保持统一前缀,例如角色使用 ROLE_、Scope 使用 SCOPE_。
租户 ID 只能作为已验证声明读取,不能直接信任 X-Tenant-Id。若请求头用于切换租户,必须校验该租户是否在当前用户令牌允许的租户集合中,否则会产生越权访问。
风险与边界
不要记录原始访问令牌或完整 claims。触发条件通常是调试日志、异常对象序列化或直接返回 jwt.getClaims();后果可能是邮箱、租户、权限和令牌标识泄露。安全替代方案是只记录 sub、请求追踪 ID 和必要的脱敏字段。
不要把 preferred_username、邮箱或昵称当作稳定主键。它们可能被修改或重复;持久化关联应使用授权服务器定义的稳定主体标识,通常是 sub,多签发者场景还应组合 iss 与 sub。
排障清单
jwt为null:确认接口已进入资源服务器安全链,且请求携带有效 Bearer Token。- 用户名为空:检查真实 claim 名称,常见值可能是
preferred_username、user_name或自定义字段。 - 权限只有
SCOPE_:这是默认 scope 映射;自定义角色需要显式转换。 - MVC 正常而 WebFlux 读取失败:响应式应用不要依赖线程本地
SecurityContextHolder,应使用参数注入或响应式安全上下文。
速查结论:身份主键优先用 iss + sub,授权判断使用已映射的 authorities,租户字段必须来自已验证声明并再次做业务范围校验。