Java 后端 / 知识点
Spring Cloud 微服务速查手册
手册条目
确认 Spring Boot、Spring Cloud 与 Java 版本之间的兼容关系。
选择 Spring Cloud 版本组合
用于新建项目或升级前确认 Spring Boot、Spring Cloud 与 Java 是否处于同一兼容区间。先按 Spring Boot 主版本选择 Cloud Release Train,再选择该列车最新的补丁版本,最后用实际启动验证,避免只看依赖能否下载。
快速选择
截至 2026-08-05,官方兼容表显示:Spring Cloud 2025.1.x 支持 Spring Boot 4.0.x,从 Cloud 2025.1.2 起同时支持 Boot 4.1.x;Boot 4.1.0 最低要求 Java 17。新项目可采用 Java 21/25 + Spring Boot 4.1.0 + Spring Cloud 2025.1.2,生产环境仍应以组织已认证的 JDK 发行版为准。:contentReference[oaicite:0]{index=0}
| 约束 | 选择方法 |
|---|---|
| Java 已固定 | 先确认目标 Boot 是否支持该 JDK |
| Boot 已固定 | 查官方 Release Train 映射后选择 Cloud |
| Cloud 已固定 | 反向确认支持的 Boot 代际,不跨代试配 |
| 新建项目 | 用 Spring Initializr 生成一次基准工程并对照版本 |
检查当前版本
以下命令适用于使用 Spring Boot Parent 和 spring-cloud.version 属性的 Maven 项目:
java -version
./mvnw -q help:evaluate -Dexpression=project.parent.version -DforceStdout
./mvnw -q help:evaluate -Dexpression=spring-cloud.version -DforceStdout预期输出:
openjdk version "21.0.<PATCH>" <DATE>
4.1.0
2025.1.2<PATCH> 与 <DATE> 会随 JDK 补丁变化。若项目没有继承 spring-boot-starter-parent,第二条可能返回其他父 POM 版本;此时改查 mvn help:effective-pom 中的 Boot 插件或 spring-boot-dependencies BOM。
启动验证
版本号看起来匹配后,仍要启动一次应用,让 Spring Cloud 的兼容性检查和自动配置真正执行。先准备好项目依赖的配置中心、注册中心,或在本地配置中关闭不需要的外部连接。
./mvnw -Dspring-boot.run.arguments=--spring.main.web-application-type=none spring-boot:run预期输出:
... Started <APPLICATION_NAME> in <SECONDS> seconds看到 Started 且日志中没有 Spring Boot ... is not compatible with this Spring Cloud release train,表示组合通过基础启动验证。端口、耗时和应用名属于动态值。
风险与边界
不要在版本不匹配时直接设置 spring.cloud.compatibility-verifier.enabled=false。触发条件是 Boot 与 Cloud 跨越官方支持区间;关闭检查后可能在启动或流量运行阶段出现 NoSuchMethodError、类缺失或自动配置失效。安全替代方案是调整 Boot 或 Cloud 到官方映射区间,并在同一分支完成编译、测试和启动验证。
版本表会随补丁发布变化。升级当天重新核对 Spring Cloud 官方兼容表,并优先选择同一 Release Train 的最新 GA 补丁,不使用 SNAPSHOT、M 或 RC 构建进入生产。
使用 Spring Cloud BOM 统一管理组件依赖版本。
导入 Spring Cloud BOM
用于在 Maven 项目中统一管理 Spring Cloud Config、Gateway、OpenFeign、LoadBalancer 等组件版本。BOM 只负责提供受测试的版本集合,具体能力仍需通过对应 starter 引入;被 BOM 管理的依赖不要重复写 <version>。
Maven 配置
下面是可直接保存为 pom.xml 的最小依赖管理示例。Spring Boot Parent 管理 Boot 生态依赖,spring-cloud-dependencies BOM 管理 Cloud Release Train 中各组件版本。官方当前示例使用 Cloud 2025.1.2,并建议通过该 BOM 管理 Spring Cloud 组件。:contentReference[oaicite:1]{index=1}
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.1.0</version>
<relativePath/>
</parent>
<groupId>com.example</groupId>
<artifactId>cloud-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>21</java.version>
<spring-cloud.version>2025.1.2</spring-cloud.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>生效行为:OpenFeign starter 不写版本,Maven 会从 Cloud BOM 注入对应组件版本;Boot 自身及常用第三方库继续由 Boot Parent 管理。
验证解析结果
生成 Effective POM,确认 starter 已获得版本,而不是仅检查原始 pom.xml:
mvn help:effective-pom -Doutput=target/effective-pom.xml
grep -A 5 -n "spring-cloud-starter-openfeign" target/effective-pom.xml预期输出:
[INFO] Effective-POM written to: <PATH>/target/effective-pom.xml
[INFO] BUILD SUCCESS
<LINE>: <artifactId>spring-cloud-starter-openfeign</artifactId>
<LINE>: <version><MANAGED_VERSION></version><PATH>、<LINE> 和 <MANAGED_VERSION> 由本机目录及 BOM 内容决定。若 Effective POM 中 starter 仍无版本,检查 BOM 是否位于 <dependencyManagement>、type 是否为 pom、scope 是否为 import。
常见错误
把 BOM 放进普通 <dependencies> 不会导入版本约束;给每个 Spring Cloud starter 手写版本则会绕过列车统一管理。出现依赖收敛问题时,先运行 mvn dependency:tree -Dverbose,查找显式版本、其他 BOM 或父 POM 对同一组件的覆盖。
风险与边界
触发风险的典型条件是升级 Boot 却保留旧 Cloud BOM,或为单个 Cloud 组件强行覆盖版本。后果可能是编译通过但启动时出现类或方法不兼容。安全替代方案是整体升级 Release Train、删除非必要的单组件版本覆盖,并用 Effective POM、依赖树和应用启动三步验证。
BOM 不会自动加入任何运行依赖,也不会替代仓库、插件或配置文件;它只统一版本。需要什么能力,就单独添加对应 starter,并保持 starter 不写版本。
初始化一个具备 Web、Actuator 和配置能力的微服务项目。
创建基础服务
用于从零生成一个可启动的 Spring Cloud 服务,默认具备 HTTP 接口、Actuator 健康检查和 Config Client 配置接入能力。示例通过 Spring Initializr 自动选择兼容的 Spring Boot 与 Spring Cloud 依赖组合,避免手工拼接版本。
前置条件
本机需要 Java 21、curl 和 unzip,并能访问 Maven 仓库与 Spring Initializr。示例使用项目自带的 Maven Wrapper,不要求预先安装 Maven;执行目录中不能已有 order-service 或 order-service.zip。
初始化与验证
下面的命令生成 Maven 项目,补充一个探活接口和可选配置中心地址,然后启动服务并验证 Web 与 Actuator。optional: 使本地没有 Config Server 时仍可启动,生产环境可去掉该前缀以强制依赖配置中心。
set -euo pipefail
test ! -e order-service
test ! -e order-service.zip
curl -fsSL "https://start.spring.io/starter.zip?type=maven-project&language=java&baseDir=order-service&groupId=com.example&artifactId=order-service&name=order-service&packageName=com.example.orderservice&packaging=jar&javaVersion=21&dependencies=web,actuator,cloud-config-client" -o order-service.zip
unzip -q order-service.zip
cd order-service
cat > src/main/resources/application.yml <<'YAML'
spring:
config:
import: optional:configserver:http://localhost:8888
management:
endpoints:
web:
exposure:
include: health,info
YAML
cat > src/main/java/com/example/orderservice/PingController.java <<'JAVA'
package com.example.orderservice;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
class PingController {
@GetMapping("/ping")
String ping() {
return "pong";
}
}
JAVA
./mvnw spring-boot:run > app.log 2>&1 &
APP_PID=$!
trap 'kill "$APP_PID" 2>/dev/null || true' EXIT
for i in $(seq 1 60); do
curl -fsS http://localhost:8080/actuator/health >/dev/null && break
kill -0 "$APP_PID" 2>/dev/null || { tail -n 80 app.log; exit 1; }
sleep 1
done
curl -fsS http://localhost:8080/actuator/health
printf '\n'
curl -fsS http://localhost:8080/ping
printf '\n'预期输出
{"status":"UP"}
pongUP 表示应用上下文、Web 容器和健康端点已正常工作;pong 表示控制器已被扫描并可通过 HTTP 访问。实际启动耗时、进程号和日志时间会不同。
关键文件
pom.xml 应包含 Web、Actuator 和 Config Client 三类依赖,并由 Initializr 写入兼容的依赖管理。application.yml 负责配置中心导入和端点暴露;业务代码放在启动类所在包或其子包中,避免组件扫描不到。
风险与边界
不要把 management.endpoints.web.exposure.include 设置为 * 后直接暴露到公网,否则可能泄露环境、Bean 或配置数据。安全替代方案是只开放 health,info,并通过内网、鉴权或独立管理端口访问。
去掉 optional: 后,配置中心不可用会导致服务启动失败;这适合必须依赖远程配置的生产环境,但不适合单机开发。若 8080 端口被占用,使用 server.port=<PORT> 更换端口,并同步修改验证地址。
排障速查
启动失败先查看 tail -n 100 app.log。依赖解析错误通常是网络、代理或版本混用;端口冲突会出现 Port 8080 was already in use;健康接口返回 404 时,检查 Actuator 依赖、端点暴露范围和请求路径。
配置稳定的应用名称,供注册发现、配置和监控系统识别。
设置服务名称
用于为微服务配置稳定的逻辑名称,使注册中心、配置中心、日志、指标和服务调用使用同一标识。名称应代表服务职责,而不是某个实例、环境或主机。
基本配置
在 src/main/resources/application.yml 中设置 spring.application.name。推荐使用小写字母和短横线,例如 order-service,并在开发、测试、生产环境保持一致。
spring:
application:
name: order-service配置生效后,Config Client 会用该名称匹配远程配置的 {application} 部分;注册发现组件通常也把它作为默认服务 ID。环境差异应通过 Profile、命名空间或配置中心标签表达,不要改成 order-service-prod。
覆盖优先级
容器或流水线临时覆盖时可设置 SPRING_APPLICATION_NAME=order-service-canary;本地一次性启动可追加 --spring.application.name=order-service-canary。命令行参数和环境变量会覆盖配置文件,因此排障时不能只检查 application.yml。
名称若参与 Config Client 的远程配置定位,应在远程配置加载前可用。把它放在本地配置、环境变量或启动参数中最稳妥,不要只在配置中心里定义用于定位配置中心的名称。
自动化验证
下面的测试从应用上下文读取最终属性,适合防止重构或环境变量误改服务名。文件路径为 src/test/java/com/example/orderservice/ApplicationNameTest.java。
package com.example.orderservice;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.test.context.SpringBootTest;
import static org.assertj.core.api.Assertions.assertThat;
@SpringBootTest(properties = "spring.main.web-application-type=none")
class ApplicationNameTest {
@Value("${spring.application.name}")
private String applicationName;
@Test
void keepsStableApplicationName() {
assertThat(applicationName).isEqualTo("order-service");
System.out.println("APPLICATION_NAME=" + applicationName);
}
}执行测试:
./mvnw -Dtest=ApplicationNameTest test预期输出中的关键行:
APPLICATION_NAME=order-service
[INFO] BUILD SUCCESS如果执行环境预先设置了 SPRING_APPLICATION_NAME,它会覆盖 application.yml 并使断言失败。这种失败通常能直接暴露流水线或容器注入了错误名称。
命名规则
名称应保持短、稳定、可读,例如 order-service、inventory-service。同一逻辑服务的不同实例必须共用名称;实例唯一性由注册中心的 instance ID、Pod 名或主机信息承担,不要给 spring.application.name 添加随机后缀。
不要把环境写进名称,否则调用方、配置文件和监控规则需要为每个环境维护不同服务 ID。环境隔离应使用独立注册中心、命名空间、Profile 或配置标签。
风险与边界
服务上线后改名会被注册中心视为新的逻辑服务,调用方可能找不到实例,配置中心会改查另一组配置,监控看板和告警也会出现数据断层。安全做法是先让调用方兼容新名称,双轨验证后再下线旧名称。
排障速查
配置中心读取了错误文件时,先检查最终的 spring.application.name、激活 Profile 和配置标签。注册中心出现同一业务的多个服务名时,搜索镜像、Helm values、环境变量和启动参数中的覆盖项;大小写、下划线与短横线不一致也会形成不同标识。
使用 Profile 管理开发、测试、预发布和生产环境配置。
划分运行环境
用 Spring Profile 将开发、测试、预发布和生产配置分开,同时保留一份公共默认配置。最终应做到:同一制品通过激活不同 Profile 启动,不修改代码,也不把密码写进仓库。
推荐划分
固定使用 dev、test、staging、prod 四个名称,并让它们只表达运行环境。功能开关、灰度批次和客户差异应使用独立配置项,避免 Profile 数量随业务组合膨胀。
公共配置放在 application.yml 的默认文档中,环境差异使用 spring.config.activate.on-profile。下面是可直接放入 Spring Boot 2.4+ 项目的单文件配置示例。
spring:
application:
name: order-service
server:
port: 8080
app:
payment-base-url: http://localhost:9001
---
spring:
config:
activate:
on-profile: dev
logging:
level:
com.example.order: DEBUG
app:
payment-base-url: http://payment-dev.internal
---
spring:
config:
activate:
on-profile: test
app:
payment-base-url: http://payment-test.internal
---
spring:
config:
activate:
on-profile: staging
app:
payment-base-url: https://payment-staging.example.com
---
spring:
config:
activate:
on-profile: prod
logging:
level:
com.example.order: INFO
app:
payment-base-url: https://payment.example.com配置生效后,公共项先加载,匹配当前 Profile 的文档再覆盖同名属性。prod 文档只保留生产差异,不重复复制端口、应用名等公共值。
启动与验证
本地或临时排障可用命令行激活 Profile;部署平台通常改用环境变量。以下命令假设已构建 target/order-service.jar。
java -jar target/order-service.jar --spring.profiles.active=dev预期输出中应出现类似日志;时间、线程名和类名会因版本而不同。
<TIME> INFO <THREAD> --- [main] <CLASS> : The following 1 profile is active: "dev"生产环境可设置 SPRING_PROFILES_ACTIVE=prod 后启动同一 JAR。发布流程应校验该变量,避免未激活 Profile 时意外使用默认地址。
风险与边界
将数据库密码、令牌或证书写入 application-prod.yml 会在代码仓库、构建产物或日志中泄露。安全替代方案是使用密钥管理服务、Kubernetes Secret,或通过 spring.config.import 挂载外部密钥文件。
不要同时激活语义冲突的 Profile,例如 dev,prod。后加载配置可能覆盖前值,导致日志级别、外部地址或安全开关混用;确需组合时,应定义明确的 Profile Group 并在发布前做配置测试。
排障清单
遇到“配置没有切换”时,依次检查启动日志中的 active profile、Profile 名称拼写、YAML 缩进和文件是否被打进 JAR。再检查是否有命令行参数、环境变量或远程配置中心覆盖了本地值。
可用以下命令确认 JAR 内是否包含配置文件;未列出时应检查 Maven 或 Gradle 的资源过滤与打包规则。
jar tf target/order-service.jar | grep -E 'application.*\.ya?ml'预期输出类似:
BOOT-INF/classes/application.yml兼容性
spring.config.activate.on-profile 适用于 Spring Boot 2.4 及以上版本。更早版本常用 spring.profiles 标记 YAML 文档;升级后应改用新属性。application-{profile}.yml 文件命名方式在 Boot 2.x 和 3.x 中仍可使用。
通过环境变量、命令行参数和配置文件覆盖服务启动配置。
配置启动参数
通过配置文件、环境变量和命令行参数为同一服务注入不同启动值,并明确谁覆盖谁。排障时先确认最终值来自哪个来源,再决定修改部署配置还是应用默认值。
覆盖优先级
只比较本条涉及的三类来源时,优先级从高到低为:命令行参数、环境变量、配置文件。也就是说,--demo.message=from-cli 会覆盖 DEMO_MESSAGE,而环境变量又会覆盖 application.yml。
| 来源 | 示例 | 适合场景 |
|---|---|---|
| 配置文件 | demo.message: from-file |
稳定默认值和可版本化配置 |
| 环境变量 | DEMO_MESSAGE=from-env |
容器、CI/CD 和平台注入 |
| 命令行参数 | --demo.message=from-cli |
临时覆盖、单次排障 |
Spring Boot 的宽松绑定会把 DEMO_MESSAGE 映射到 demo.message。环境变量通常使用大写字母和下划线,不要在名称中依赖点号或连字符。
最小验证示例
下面的类是片段示例,放入已有 Spring Boot 项目后会在启动时打印最终属性值。它依赖项目已包含 spring-boot-starter。
package com.example.demo;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.ApplicationArguments;
import org.springframework.boot.ApplicationRunner;
import org.springframework.stereotype.Component;
@Component
public class StartupConfigReporter implements ApplicationRunner {
@Value("${demo.message:from-default}")
private String message;
@Override
public void run(ApplicationArguments args) {
// 只打印非敏感示例值,用于确认属性覆盖来源。
System.out.println("demo.message=" + message);
}
}在 application.yml 中设置默认值:
demo:
message: from-file高频用法
仅使用配置文件启动:
java -jar target/demo.jar预期输出:
demo.message=from-file使用环境变量覆盖配置文件:
DEMO_MESSAGE=from-env java -jar target/demo.jar预期输出:
demo.message=from-env同时传入环境变量和命令行参数,验证命令行优先:
DEMO_MESSAGE=from-env java -jar target/demo.jar --demo.message=from-cli预期输出:
demo.message=from-cli实际启动日志还会包含 Spring Boot 横幅和其他日志;这里只列出验证覆盖结果所需的关键行。
常用参数
--server.port=<PORT> 临时修改监听端口,--spring.profiles.active=prod 激活运行环境,--spring.config.additional-location=<PATH> 追加外部配置位置。使用 additional-location 时默认配置仍会加载,再由外部配置覆盖同名项。
需要完全替换默认搜索位置时才使用 --spring.config.location=<PATH>。路径写错会导致应用找不到预期配置,因此生产环境更适合固定挂载目录并在启动脚本中先检查文件存在。
风险与边界
密码或令牌放在命令行参数中,可能被 shell 历史、进程列表和诊断工具读取;放在环境变量中,也可能出现在容器描述、崩溃转储或运维平台中。安全替代方案是使用云密钥服务、Kubernetes Secret 挂载文件,或 configtree: 导入。
不要用命令行长期维护大量业务配置。参数过多会让发布记录难以审计,并增加拼写错误概率;稳定配置应进入受控配置文件或配置中心,命令行只保留少量启动级覆盖。
排障清单
最终值不符合预期时,先搜索启动脚本和部署清单中的同名命令行参数,再检查环境变量是否残留。随后检查外部配置目录、Profile 配置和配置中心,避免只修改 application.yml 却被更高优先级来源覆盖。
PowerShell 设置环境变量时语法不同,且变量会保留在当前会话中。验证完成后应显式清理,防止下一次启动继续继承旧值。
$env:DEMO_MESSAGE = "from-env"
java -jar target/demo.jar
$env:DEMO_MESSAGE = $null预期输出中的关键行:
demo.message=from-env开放 Actuator 健康端点并检查服务及其依赖状态。
启用健康检查
使用 Spring Boot Actuator 的 /actuator/health 判断实例是否可用,并查看已注册依赖检查项的状态。生产环境建议公开总体状态和组件状态,详细连接信息只对授权运维人员开放。
前置配置
在现有 Spring Boot 项目的 pom.xml 的 <dependencies> 中加入以下片段示例:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>在 application.yml 中显式保留健康端点,并只显示组件状态,不公开组件详情:
management:
endpoints:
web:
exposure:
include: "health"
endpoint:
health:
show-components: always
show-details: never重启服务后,默认地址为 /actuator/health。组件名称由项目依赖和自定义 HealthIndicator 决定,例如数据库、Redis、磁盘空间或消息中间件检查项。
验证与读取
curl -sS -w '\nHTTP %{http_code}\n' http://127.0.0.1:8080/actuator/health预期输出;<COMPONENT_NAME> 代表当前应用实际注册的检查项:
{"status":"UP","components":{"<COMPONENT_NAME>":{"status":"UP"}}}
HTTP 200status 是聚合结果,components 是各依赖检查项。通常 UP 返回 HTTP 200;关键组件为 DOWN 或 OUT_OF_SERVICE 时,整体状态通常返回 HTTP 503。
高频用法
监控平台只需轮询总体健康地址;排查依赖故障时再查看 components。在 Kubernetes 中可启用 management.endpoint.health.probes.enabled=true,分别使用 /actuator/health/liveness 和 /actuator/health/readiness。
活性检查只判断进程是否需要重启,不要加入数据库、注册中心等外部依赖;就绪检查可包含这些依赖,用于决定实例是否继续接收流量。
风险与边界
将 show-details 设为 always 且端点可被公网访问时,可能泄露数据库类型、磁盘路径、异常信息或下游地址。安全替代方案是保持 never,或使用 when-authorized 并配合 Spring Security、网关鉴权和网络访问控制。
把外部依赖加入活性检查后,短暂网络故障可能触发容器反复重启,形成重启风暴。应把外部依赖放入就绪检查,并为健康探测设置合理的超时、失败阈值和初始延迟。
排障清单
- 返回 404:确认已引入 Actuator、
base-path未被修改、health未被exclude排除。 - 返回 401 或 403:检查 Spring Security、网关策略和运维账号权限。
- 只有
{"status":"UP"}:通常是组件或详情被隐藏,不代表依赖检查未注册。 - 返回 503:查看具体组件状态和对应下游连接,先修复依赖或临时摘除实例,不要直接关闭健康检查。
兼容性
上述核心配置适用于 Spring Boot Actuator 3.x 和 4.x 的常见项目。自动注册的健康组件随依赖、驱动和自定义检查实现变化,不能用固定组件清单判断配置是否生效。
按需开放指标、配置、日志级别和线程信息等管理端点。
暴露管理端点
通过 Actuator 白名单开放指标、配置绑定、日志级别和线程快照端点,便于生产排障。只开放当前需要的端点,并将管理端口置于受控网络,避免把完整管理面直接暴露到公网。
推荐配置
以下 application.yml 将管理端点放到独立端口,并使用明确白名单。configprops 的值保持隐藏,只用于确认配置项是否绑定:
management:
server:
port: 9001
endpoints:
web:
base-path: /actuator
exposure:
include: "health,info,metrics,configprops,loggers,threaddump"
endpoint:
configprops:
show-values: never独立端口不等于安全隔离。生产环境仍需通过防火墙、安全组、Kubernetes NetworkPolicy、网关或 Spring Security 限制访问,并为运维账号配置最小权限。
常用端点
/actuator/metrics:列出指标名称;追加指标名可查看测量值和标签。/actuator/configprops:检查@ConfigurationProperties绑定结果,默认应隐藏敏感值。/actuator/loggers:查看日志器及当前级别;修改级别属于写操作,应单独授权。/actuator/threaddump:获取线程快照,用于定位死锁、阻塞和线程池耗尽。/actuator/health与/actuator/info:用于存活检查和版本、构建信息确认。
验证端点
以下命令假设管理端已由现有安全配置启用 Basic Auth;若使用令牌或网关鉴权,应替换认证参数:
export ACTUATOR_USER='<USER>'
export ACTUATOR_PASSWORD='<PASSWORD>'
for path in health info metrics configprops loggers threaddump; do
code=$(curl -sS -u "$ACTUATOR_USER:$ACTUATOR_PASSWORD" -o /dev/null -w '%{http_code}' "http://127.0.0.1:9001/actuator/$path")
printf '%-12s %s\n' "$path" "$code"
done预期输出;已正确暴露且认证通过时各端点返回 200:
health 200
info 200
metrics 200
configprops 200
loggers 200
threaddump 200若当前环境未启用 Basic Auth,可在受控的本机开发环境移除 -u 参数;生产环境不要使用匿名访问替代认证。
风险与边界
使用 include: "*" 时,可能同时暴露 env、beans、mappings、heapdump 等高敏感或大体积端点,导致配置泄露、攻击面扩大或内存文件被下载。安全替代方案是白名单开放,并对高风险端点按故障窗口临时启用、处理后立即关闭。
允许远程修改 loggers 时,误设全局 DEBUG 或 TRACE 可能造成日志洪泛、磁盘写满、性能下降,并把请求参数或凭据写入日志。应限制到指定包名、设置回滚时间,并保留变更审计。
频繁请求 threaddump 会生成较大响应并增加实例负担。只在定位线程问题时按需采集,避免被监控系统高频轮询。
排障清单
/actuator可访问但缺少某端点:检查include、exclude;exclude优先级更高。- 返回 404:确认访问的是管理端口和正确
base-path,并检查端点是否因依赖或访问策略不可用。 - 返回 401 或 403:检查认证角色;写操作还需检查 CSRF、令牌或网关方法限制。
- 连接被拒绝:确认 9001 端口已监听,并在容器端口、Service、安全组和防火墙中放行受控来源。
prometheus不存在:除暴露端点外,还需引入对应 Micrometer Prometheus registry。
兼容性
management.server.port、management.endpoints.web.base-path 和 management.endpoints.web.exposure.* 是 Spring Boot Actuator 3.x、4.x 的常用配置。跨版本升级时应核对端点访问控制属性和安全自动配置,避免只改暴露清单却遗漏认证规则。
将服务实例注册到注册中心并上报地址与健康状态。
注册服务实例
将 Spring Boot 服务注册到 Eureka 时,核心结果是注册中心能够按 spring.application.name 看到实例地址、端口和状态。客户端依赖在类路径中并配置 Eureka 地址后会自动注册,通常不需要再写 @EnableDiscoveryClient。

依赖与配置
片段示例:项目应已通过 Spring Cloud BOM 管理版本,在 pom.xml 中加入 Eureka Client;需要把应用健康状态上报到注册中心时同时加入 Actuator。
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
</dependencies>在 application.yml 中设置稳定的服务名和注册中心地址。defaultZone 是区分大小写的映射键;健康检查开关应放在 application.yml,不要放进 bootstrap.yml,否则可能以 UNKNOWN 状态注册。
spring:
application:
name: order-service
server:
port: 8081
management:
endpoints:
web:
exposure:
include: health,info
eureka:
client:
service-url:
defaultZone: ${EUREKA_URL:http://localhost:8761/eureka/}
healthcheck:
enabled: true配置生效后,启动应用:
./mvnw spring-boot:run预期输出会包含启动完成日志,耗时和进程号因环境而异:
Started OrderServiceApplication in <TIME> seconds (process running for <TIME>)验证注册结果
等待首次注册完成后,从 Eureka API 查询实例。示例依赖 curl 和 jq:
curl -fsS -H 'Accept: application/json' http://localhost:8761/eureka/apps/ORDER-SERVICE | jq '.application.instance[] | {instanceId,status,hostName,ipAddr,port}'预期输出中的主机、IP 和实例 ID 会随部署环境变化,status 为 UP 才表示该实例可被正常发现:
{
"instanceId": "<INSTANCE_ID>",
"status": "UP",
"hostName": "<HOST>",
"ipAddr": "<IP>",
"port": {
"$": 8081,
"@enabled": "true"
}
}关键配置
spring.application.name:注册服务 ID;调用方按此名称发现服务。eureka.client.service-url.defaultZone:Eureka Server 地址,可通过EUREKA_URL注入不同环境值。eureka.client.register-with-eureka:默认允许注册;设为false后实例只发现其他服务,不发布自己。eureka.instance.*:覆盖主机名、端口、实例 ID 和元数据,仅在默认推断不符合部署网络时使用。
风险与排障
容器或多网卡环境最常见的问题是注册了消费者不可达的地址。触发条件是 Eureka 中显示 UP,但其他服务连接超时;后果是流量持续打向错误 IP。先从调用方执行 curl http://<REGISTERED_HOST>:<PORT>/actuator/health 验证可达性,再按网络拓扑设置主机名、首选网段或忽略 docker0、veth 等接口,不要盲目启用 prefer-ip-address。
注册中心不可达时,检查 EUREKA_URL、DNS、代理、TLS 和防火墙;服务名不存在时,确认 spring.application.name 未被环境变量覆盖;状态长期不是 UP 时,直接检查 /actuator/health 及其依赖项。停机摘除存在传播窗口,发布期间应结合优雅停机和负载均衡重试,不能把注册中心状态当作瞬时强一致结果。
通过服务名称查询可用实例并避免硬编码服务地址。
发现服务实例
服务发现用于按逻辑服务名查询可用实例,避免在代码中固定 IP 和端口。排障时可直接使用 DiscoveryClient.getInstances() 查看实例清单;业务调用则优先交给 Spring Cloud LoadBalancer,从逻辑 URI 自动选择物理地址。

前置配置
发现端必须包含具体注册中心客户端,并连接到与服务提供方相同的 Eureka。实际使用负载均衡 URI 时,显式加入 LoadBalancer starter,避免只有 DiscoveryClient 而没有实例选择器。
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
</dependencies>消费者的 application.yml 至少需要服务名和 Eureka 地址:
spring:
application:
name: order-consumer
server:
port: 8082
eureka:
client:
service-url:
defaultZone: ${EUREKA_URL:http://localhost:8761/eureka/}查询可用实例
下面的完整示例暴露 /discovery/{serviceId},返回当前客户端缓存中的实例 URI、协议和元数据。它适合排障与管理接口,不应由业务代码自行随机选择实例。
package com.example.consumer;
import java.util.List;
import java.util.Map;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.ServiceInstance;
import org.springframework.cloud.client.discovery.DiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
@SpringBootApplication
public class ConsumerApplication {
public static void main(String[] args) {
SpringApplication.run(ConsumerApplication.class, args);
}
}
@RestController
class DiscoveryController {
private final DiscoveryClient discoveryClient;
DiscoveryController(DiscoveryClient discoveryClient) {
this.discoveryClient = discoveryClient;
}
@GetMapping("/discovery/{serviceId}")
List<Map<String, Object>> instances(@PathVariable String serviceId) {
return discoveryClient.getInstances(serviceId).stream()
.map(this::toView)
.toList();
}
private Map<String, Object> toView(ServiceInstance instance) {
// 只返回排障需要的字段,避免暴露注册中心内部对象。
return Map.of(
"serviceId", instance.getServiceId(),
"uri", instance.getUri().toString(),
"secure", instance.isSecure(),
"metadata", instance.getMetadata()
);
}
}启动消费者后查询 order-service:
curl -fsS http://localhost:8082/discovery/order-service | jq .预期输出可能包含多个实例,主机与端口按实际注册结果变化:
[
{
"serviceId": "ORDER-SERVICE",
"uri": "http://<HOST>:8081",
"secure": false,
"metadata": {}
}
]业务调用写法
生产请求不要先调用 getInstances() 再自行拼接 URL。声明带 @LoadBalanced 的 RestClient.Builder,然后直接使用逻辑服务名;LoadBalancer 会把 http://order-service 解析为选中的实例地址。
@Bean
@LoadBalanced
RestClient.Builder loadBalancedRestClientBuilder() {
return RestClient.builder();
}
// 调用时只写服务名,不写固定主机和端口。
String body = restClientBuilder.build()
.get()
.uri("http://order-service/orders/{id}", 42)
.retrieve()
.body(String.class);这是片段示例,需放入 Spring 配置类,并注入带 @LoadBalanced 限定符的 RestClient.Builder。生效后的验证方法是连续调用消费者接口,确认请求能在多个 UP 实例之间分配,而不是始终访问固定地址。
输出字段说明
serviceId:注册服务 ID,通常来自提供方的spring.application.name。uri:该实例对调用方公开的协议、主机和端口。secure:是否应通过 HTTPS 调用。metadata:注册时附带的自定义键值,可用于区域、版本或权重策略,但不会自动产生业务语义。
风险与排障
getInstances() 读取的是客户端服务目录,注册、下线和健康变化都可能存在同步延迟。触发条件是实例刚扩缩容或网络短暂分区;后果是短时间返回空列表或旧地址。安全做法是让 LoadBalancer、超时、重试和熔断共同处理瞬时失败,不要把一次空查询直接解释为服务永久不存在。Eureka 默认周期拉取注册表,并可只保留 UP 实例。
若结果为空,依次检查提供方是否已注册为 UP、双方 defaultZone 是否指向同一注册中心、服务名是否一致,以及 spring.cloud.discovery.enabled、eureka.client.fetch-registry 是否被关闭。若 URI 可见但访问失败,从消费者网络直接探测该 URI;这通常说明提供方注册了错误网卡、容器内地址或错误协议,而不是发现 API 本身失效。
兼容性
只要类路径中存在 DiscoveryClient 实现,现代 Spring Cloud 通常无需显式添加 @EnableDiscoveryClient。阻塞式应用可使用 RestClient 与 BlockingLoadBalancerClient;响应式链路使用 WebClient 与 Reactive LoadBalancer,避免在响应式线程中调用阻塞式 DiscoveryClient。
为注册实例添加版本、区域、环境和路由标识等元数据。
配置实例元数据
为注册实例补充版本、区域、环境和路由标签时,使用注册中心的元数据字段。以下以 Spring Cloud Netflix Eureka 为例:实例启动后会把键值对随注册信息上报,调用方可通过 ServiceInstance.getMetadata() 读取,但任意自定义标签不会自动改变路由。
配置示例
在 application.yml 中保持实例 ID 唯一,并让可变信息来自环境变量,避免为不同环境维护多份配置。
spring:
application:
name: order-service
eureka:
client:
service-url:
defaultZone: ${EUREKA_URL:http://127.0.0.1:8761/eureka/}
instance:
instance-id: ${spring.application.name}:${spring.application.instance_id:${random.value}}
prefer-ip-address: true
metadata-map:
version: ${APP_VERSION:v1}
zone: ${APP_ZONE:zone-a}
environment: ${APP_ENV:dev}
route-tag: ${ROUTE_TAG:stable}instance-id 用于区分同一服务的多个进程;metadata-map 的值最终按字符串传递。prefer-ip-address 只控制实例对外登记地址,与版本路由没有直接关系。
启动与验证
启动时注入本实例标签;生产环境通常由容器环境变量、部署清单或启动脚本提供这些值。
APP_VERSION=2.3.1 APP_ZONE=us-west-2a APP_ENV=prod ROUTE_TAG=canary java -jar order-service.jar预期结果:应用成功注册后,查询该服务可以看到实例状态和元数据。下面命令依赖 jq,服务名在 Eureka 响应中通常使用大写形式。
curl -fsS -H 'Accept: application/json' 'http://127.0.0.1:8761/eureka/apps/ORDER-SERVICE' | jq '.application.instance[] | {instanceId, status, metadata}'预期输出:
{
"instanceId": "<INSTANCE_ID>",
"status": "UP",
"metadata": {
"version": "2.3.1",
"zone": "us-west-2a",
"environment": "prod",
"route-tag": "canary"
}
}<INSTANCE_ID> 会随启动方式变化;多实例时命令会输出多个对象,应按 instanceId、端口或元数据继续筛选。
路由使用边界
版本、区域和 route-tag 只是描述信息。只有网关、负载均衡器或自定义 ServiceInstanceListSupplier 明确读取并筛选这些键时,流量才会按标签分配。灰度发布前先验证无标签调用方的回退策略,避免筛选后得到空实例列表。
不要把令牌、密码、用户信息或内部凭据写入元数据。注册中心管理端、其他客户端或运维接口可能读取这些值;敏感信息应放入密钥管理系统,并仅在请求鉴权阶段使用。
排障清单
- 查不到元数据:确认配置位于
eureka.instance.metadata-map,并检查实例是否重新注册成功。 - 多个实例相互覆盖:检查
instance-id是否唯一,尤其不要只使用固定服务名。 - 修改后未立即生效:实例信息和调用方注册表都有刷新周期;需要即时切流时,使用受控的实例状态变更并预留缓存传播时间。
- 路由标签无效:检查调用方是否实现了元数据过滤,而不是只完成了注册端配置。
速查:元数据负责“描述实例”,路由组件负责“解释并执行规则”,两者缺一不可。
在服务停止时主动注销实例并减少流量进入失效节点。
处理实例下线
计划停止实例时,先把实例标记为不接收新流量,再等待调用方缓存刷新,最后发送 SIGTERM 触发 Spring 容器关闭和 Eureka 注销。这样可减少请求继续进入失效节点,并为正在执行的请求保留完成窗口。
推荐下线顺序
- 将目标实例状态改为
OUT_OF_SERVICE,阻止基于 Eureka 状态的新选择。 - 等待至少一个调用方注册表刷新周期,并结合网关或负载均衡缓存调整排空时间。
- 向进程发送
SIGTERM,不要直接使用SIGKILL。 - 验证 Eureka 中实例已删除,同时检查活动请求、消费任务和连接是否清零。

应用配置
当前 Spring Boot 3.4、3.5 和 4.1 默认启用嵌入式 Web 服务器的优雅停机;显式配置可以固定团队预期。Eureka 客户端关闭时应保持主动注销开启。
server:
shutdown: graceful
spring:
lifecycle:
timeout-per-shutdown-phase: 30s
eureka:
client:
should-unregister-on-shutdown: truetimeout-per-shutdown-phase 是每个停机阶段允许完成工作的时间。它应大于主要请求、事务或消息处理的正常尾延迟;容器平台的终止宽限期还必须比它更长,否则进程会在注销或排空完成前被强制终止。
下线脚本
下面脚本适用于能访问 Eureka 管理接口并能向本机 Java 进程发送信号的主机。先设置 APP_ID、INSTANCE_ID 和 PID;DRAIN_SECONDS 默认取 35 秒,用于覆盖常见的 30 秒注册表拉取周期,实际值应按网关和客户端缓存调整。
#!/usr/bin/env bash
set -Eeuo pipefail
: "${EUREKA_URL:=http://127.0.0.1:8761/eureka}"
: "${APP_ID:?set APP_ID, for example ORDER-SERVICE}"
: "${INSTANCE_ID:?set INSTANCE_ID from Eureka}"
: "${PID:?set PID of the local Java process}"
: "${DRAIN_SECONDS:=35}"
instance_url="${EUREKA_URL%/}/apps/${APP_ID}/${INSTANCE_ID}"
# 先从服务发现流量中摘除,再等待调用方缓存传播。
curl -fsS -X PUT "${instance_url}/status?value=OUT_OF_SERVICE" >/dev/null
echo "instance marked OUT_OF_SERVICE"
sleep "${DRAIN_SECONDS}"
# SIGTERM 触发 Spring 上下文关闭、请求排空和 Eureka 注销。
kill -TERM "${PID}"
echo "SIGTERM sent to PID ${PID}"
for _ in $(seq 1 45); do
code="$(curl -sS -o /dev/null -w '%{http_code}' -H 'Accept: application/json' "${instance_url}" || true)"
if [[ "${code}" == "404" ]]; then
echo "instance deregistered"
exit 0
fi
sleep 1
done
echo "instance still visible in Eureka" >&2
exit 1预期输出:
instance marked OUT_OF_SERVICE
SIGTERM sent to PID <PID>
instance deregistered<PID> 是实际进程号。若 Eureka 启用了认证,需要为 curl 增加受限凭据;不要把长期密码直接写入脚本或命令历史。
风险与安全替代
仅调用 Eureka 的删除接口但不停止进程,实例可能在后续心跳中重新注册;安全做法是先摘流量,再优雅停止。直接执行 kill -9、强制删除 Pod 或让宿主机断电,会跳过 Spring 上下文关闭和主动注销,注册中心只能等待租约过期,期间客户端可能继续拿到失效地址。
不要盲目缩短租约过期时间。过短会让短暂网络抖动把健康实例误判为下线;更安全的方案是保留合理租约,通过 OUT_OF_SERVICE、就绪探针、预停止钩子和足够的终止宽限期完成计划下线。
排障清单
- 状态修改返回
401或403:检查 Eureka 安全策略和下线账号权限,不要临时关闭认证。 - 发送
SIGTERM后仍存在:确认进程确实退出、should-unregister-on-shutdown未关闭,并检查实例到 Eureka 的网络。 - Eureka 已删除但仍有流量:检查调用方注册表刷新、网关缓存、连接池复用和静态上游配置。
- 请求被中断:增加停机阶段超时和平台终止宽限期,并排查无法结束的长请求或后台任务。
- 只能使用
SIGKILL:先手工标记OUT_OF_SERVICE并等待排空,再强杀;随后持续验证实例从所有调用方缓存中消失。
兼容性提示:使用 Kubernetes 原生服务发现时,应以就绪探针、preStop 和 terminationGracePeriodSeconds 为主,不要照搬 Eureka REST 路径。
从外部配置中心加载服务配置并区分应用与环境。
接入配置中心
用于把服务配置从 Spring Cloud Config Server 注入 Spring Environment,并按应用名、运行环境和配置版本隔离。完成后,服务启动时会根据 {application}/{profile}/{label} 读取远端配置;生产环境应让配置中心不可用时启动失败,避免静默使用错误默认值。

前置条件
Config Server 已能访问后端仓库,客户端项目已使用与 Spring Boot 匹配的 Spring Cloud BOM。以下是 pom.xml 的依赖片段;版本由 BOM 统一管理,不要在单个 starter 上手写版本。
<!-- 版本由 Spring Cloud BOM 统一管理,避免 starter 版本漂移 -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-config</artifactId>
</dependency>该依赖生效后,客户端具备 Config Data 导入能力;它不会自动决定应用名、环境或服务器地址,仍需在本地启动配置中明确声明。
客户端配置
在客户端 application.yml 中配置应用名、环境和 Config Server 地址。生产环境不要加 optional:,这样服务器不可达、认证失败或配置不存在时,应用会直接启动失败。
spring:
application:
name: order-service
profiles:
active: prod
config:
# 生产环境不加 optional:,远端不可用时直接阻止启动
import: "configserver:http://config-server:8888"
cloud:
config:
# 对应 Git 分支、标签或提交标识
label: mainspring.application.name 对应 {application},spring.profiles.active 对应 {profile},spring.cloud.config.label 对应 {label}。仓库中可放共享的 application.yml、应用级 order-service.yml 和环境级 order-service-prod.yml;同名键以 Config Server 返回的属性源优先级为准。
环境文件示例:
# order-service-prod.yml:仅保存 prod 环境差异
order:
timeout-ms: 1500
feature:
banner: "stable"配置文件属于声明性片段,不产生控制台输出。启动后应验证远端值是否进入客户端,而不是只确认文件已提交。
验证解析结果
先直接查询 Config Server,确认应用、环境、标签和目标键均能解析。示例依赖 curl 与 jq。
# 直接检查 Config Server 的 application、profile、label 映射结果
curl -fsS http://config-server:8888/order-service/prod/main | jq '{name, profiles, label, timeout: ([.propertySources[].source["order.timeout-ms"] // empty] | first)}'预期输出:
{
"name": "order-service",
"profiles": [
"prod"
],
"label": "main",
"timeout": 1500
}若这里正确但服务仍使用旧值,再通过业务自检接口、受保护的 Actuator env 端点或启动日志验证客户端实际值。仅访问 Config Server 能证明服务器解析成功,不能证明客户端已经应用。
风险与边界
使用 optional:configserver: 的触发条件是远端连接或加载失败;后果是应用可能继续使用本地默认值,造成环境串用。安全替代方案是生产环境使用强制导入,并为 Config Server 配置高可用、超时、重试和健康检查。
不要把数据库密码、令牌等明文提交到普通 Git 仓库,否则仓库历史、克隆副本和日志都可能泄露秘密。应改用 Vault、云秘密管理服务或 Config Server 的加密能力,并限制仓库和配置接口权限。
配置覆盖冲突时不要凭文件名猜最终值,应检查返回结果中的 propertySources 顺序。共享配置只放真正通用的键,环境差异放到应用环境文件,避免一个全局键意外影响全部服务。
排障清单
- 返回
404或空属性源:核对应用名、激活环境、标签是否存在,以及仓库文件名是否匹配。 - 连接被拒绝或 TLS 失败:从客户端容器内测试 Config Server 地址、DNS、证书链和认证信息。
- 启动时出现两次配置请求:使用 Config Data 导入时,先加载
default再加载激活环境属于正常行为。 - 使用
bootstrap.yml仍不生效:Spring Boot 2.4 及以上优先使用spring.config.import;旧式 bootstrap 需要显式启用 bootstrap 上下文或引入对应 starter。
在不重启服务的情况下更新允许动态刷新的配置项。
刷新动态配置
用于在服务不停机的情况下重新加载远端配置,并让允许刷新的 Bean 读取新值。单实例通过 POST /actuator/refresh 触发;多实例应使用 Spring Cloud Bus 或受控滚动重启,避免只刷新到某一个节点。

前置配置
客户端需要 spring-boot-starter-actuator、Spring Cloud Config Client,并只暴露必要端点。以下配置开放 health 和 refresh;生产环境还必须通过防火墙、网关或 Spring Security 限制调用者。
management:
endpoints:
web:
exposure:
# 生产环境还需通过网络边界和 Spring Security 限制调用者
include: "health,refresh"对构造时读取的 @Value,将使用该值的 Bean 放入 @RefreshScope。下面是可直接放入标准 Spring Boot 项目的完整示例。
package com.example.demo;
import java.util.Map;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.context.config.annotation.RefreshScope;
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);
}
}
// 只把确实需要热更新的业务 Bean 放入刷新作用域
@RefreshScope // 刷新时清除代理缓存,下一次调用再创建目标 Bean
@RestController
class BannerController {
private final String banner;
BannerController(@Value("${feature.banner:default}") String banner) {
this.banner = banner; // 构造时取得当前 Environment 中的配置快照
}
@GetMapping("/banner")
Map<String, String> banner() {
return Map.of("banner", banner);
}
}预期结果:
应用启动后,GET /banner 返回 HTTP 200,响应体为 {"banner":"stable"}。单实例刷新
先把配置仓库中的 feature.banner 从 stable 改为 new-banner 并提交,再执行以下命令。示例假设应用监听本机 8080 端口。
# 先读取旧值,再触发当前实例刷新
curl -fsS http://localhost:8080/banner; echo
curl -fsS -X POST http://localhost:8080/actuator/refresh | jq 'map(select(. == "feature.banner"))'
# 再次读取,验证 RefreshScope Bean 已用新值重建
curl -fsS http://localhost:8080/banner; echo预期输出:
{"banner":"stable"}
["feature.banner"]
{"banner":"new-banner"}刷新响应是发生变化的键名列表;实际列表可能包含其他联动键。返回空数组通常表示服务读取到的远端值没有变化、请求命中了错误实例,或 Config Server 仍未解析到新提交。
多实例选择
| 场景 | 触发方式 | 适用边界 |
|---|---|---|
| 单个实例排障 | POST /actuator/refresh |
只影响收到请求的实例 |
| 同一服务多实例 | POST /actuator/busrefresh |
需要 Spring Cloud Bus 和 RabbitMQ 或 Kafka |
| 强一致变更 | 版本化配置后滚动重启 | 变更顺序可控,但会增加发布成本 |
busrefresh 会广播刷新事件,但各节点处理存在时间差,不能视为分布式原子提交。涉及数据库切换、协议变更或必须同时生效的参数时,应采用兼容性发布、双写或滚动重启,而不是依赖瞬时全量刷新。
风险与边界
将刷新端点暴露到公网会让未授权调用者反复重建 Bean,可能导致行为篡改、资源抖动或服务降级。安全替代方案是只在管理网络开放,配置强认证和审计,并限制调用频率。
普通单例、静态字段以及未进入刷新作用域的构造注入值不会自动更新。对可重绑定的业务配置优先使用 @ConfigurationProperties;需要重建对象时使用 @RefreshScope;连接池、线程池等有状态资源优先通过受控重启切换。
删除远端配置键后执行刷新,不一定会让旧键从当前环境中消失。应提交明确的新值或禁用值;必须验证“键不存在”语义时,采用重启或重新部署。
HikariDataSource 默认属于不可刷新的类型,强制动态切换可能造成旧连接与新配置混用。数据库地址、凭证和连接池核心参数应通过滚动重启更新。Spring AOT 和原生镜像也不支持运行时上下文刷新,应关闭刷新能力并使用重新部署。
排障清单
404 Not Found:检查 Actuator 依赖、management.endpoints.web.exposure.include和管理端口路径。- 返回变更键但接口值不变:检查读取该值的 Bean 是否处于
@RefreshScope,以及是否把值复制到静态字段或其他长生命周期对象。 - 只有部分节点更新:确认请求落到哪个实例;集群使用 Bus、逐实例刷新或滚动重启。
- 刷新后短时延迟升高:刷新作用域 Bean 在下一次调用时懒加载重建,提前预热关键路径或改用滚动发布。
避免在配置仓库中明文保存密码、令牌和密钥。
加密敏感配置
用于必须把敏感值放入 Spring Cloud Config 配置仓库、又不能保存明文的场景。做法是让 Config Server 持有加密密钥,仓库只提交以 {cipher} 开头的密文;客户端读取配置时由服务端解密。若平台已提供 Vault 或云 Secret Manager,应优先使用外部密钥系统。
配置加密能力
以下是片段示例,前置条件是该应用已经启用 Spring Cloud Config Server。部署平台应在进程启动前注入环境变量 ENCRYPT_KEY,它会映射到 encrypt.key;不要把密钥写入 Git、镜像或普通 ConfigMap。
server:
port: 8888
spring:
cloud:
config:
server:
git:
uri: ${CONFIG_GIT_URI}生效行为:Config Server 使用进程环境中的密钥处理 /encrypt、/decrypt,并在读取远程配置时识别 {cipher} 前缀。生产环境应使用高强度随机值,或改为 encrypt.key-store.* 配置非对称密钥库。

生成并保存密文
在能访问 Config Server 管理端口的受控终端执行。read -s 避免把明文直接写进命令历史,--data-binary @- 从标准输入传值。
read -rsp "Secret: " SECRET_VALUE
printf '\n'
CIPHER_TEXT="$(
printf '%s' "$SECRET_VALUE" |
curl -fsS -X POST -H 'Content-Type: text/plain' --data-binary @- http://127.0.0.1:8888/encrypt
)"
printf '{cipher}%s\n' "$CIPHER_TEXT"
unset SECRET_VALUE CIPHER_TEXT预期输出:
{cipher}<CIPHER_TEXT><CIPHER_TEXT> 每次可能不同。把整行写入配置仓库,不要再次编码,也不要删除 {cipher}。
spring:
datasource:
username: app_user
password: "{cipher}<CIPHER_TEXT>"验证方法:提交配置后,让目标服务重新加载并执行一次真实但低风险的数据库连通性检查;不要通过日志、Actuator env 或命令行打印解密后的值。
风险与边界
/encrypt或/decrypt暴露到公网时,攻击者可能滥用端点或验证密文。安全替代是仅监听回环地址或管理网络,并叠加认证、网络策略和审计。- 密钥与密文同时进入仓库、镜像或备份时,加密等同失效,泄露后可批量还原。安全替代是把密钥放入 KMS、Vault、硬件密钥模块或受控 Secret 挂载。
- 直接替换密钥会让旧密文无法解密,导致应用启动或刷新失败。轮换前先准备新旧密钥并行窗口,重新加密全部值,再移除旧密钥。
- Config Server 解密后会向已授权客户端返回明文,因此访问控制、TLS、日志脱敏和客户端内存保护仍然必需。
排障清单
出现 Cannot decrypt、属性为空或应用启动失败时,依次确认:密文前缀是否完整;当前 Config Server 是否拿到正确密钥;密钥是否在启动早期加载;密文是否被 YAML 引号、换行或模板处理破坏;客户端访问的是预期环境和标签;服务端日志中是否有 invalid key、IllegalBlockSizeException 或密钥库别名错误。
在多个服务实例之间选择目标节点并分发请求。
配置负载均衡
用于调用同一服务名下的多个实例。Spring Cloud LoadBalancer 根据服务发现结果选择一个 ServiceInstance,再把 http://inventory-service/... 解析为具体地址。调用方只依赖服务名,不在代码里维护实例 IP。
依赖与实例来源
以下 Maven 片段依赖已由与 Spring Boot 匹配的 Spring Cloud BOM 管理,不要给 starter 单独写版本。
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>生产环境通常由 Eureka、Consul 或 Kubernetes Discovery 提供实例。快速本地验证可使用 SimpleDiscoveryClient:
spring:
cloud:
discovery:
client:
simple:
instances:
inventory-service:
- uri: http://127.0.0.1:8081
- uri: http://127.0.0.1:8082生效行为:服务名 inventory-service 对应两个候选实例;默认负载均衡策略按轮询方式选择。真实注册中心接入后,应删除这段静态实例配置,避免静态地址覆盖或混入发现结果。

最小调用代码
前置条件:两个 inventory-service 实例都提供 GET /whoami,分别返回 node-a 和 node-b。下面代码创建专用的负载均衡 RestClient.Builder,并暴露一个本地探测接口。
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClient;
@SpringBootApplication
public class GatewayApplication {
public static void main(String[] args) {
SpringApplication.run(GatewayApplication.class, args);
}
@Bean
@LoadBalanced
RestClient.Builder loadBalancedRestClientBuilder() {
return RestClient.builder();
}
}
@RestController
class InventoryProbeController {
private final RestClient inventoryClient;
InventoryProbeController(@LoadBalanced RestClient.Builder builder) {
// URI 中必须使用服务名,LoadBalancer 才会解析实例。
this.inventoryClient = builder.baseUrl("http://inventory-service").build();
}
@GetMapping("/probe-inventory")
String probeInventory() {
return inventoryClient.get()
.uri("/whoami")
.retrieve()
.body(String.class);
}
}启动调用方后连续请求:
for i in 1 2 3 4; do
curl -fsS http://127.0.0.1:8080/probe-inventory
printf '\n'
done预期输出:
node-a
node-b
node-a
node-b首次选中的节点可能相反,但健康实例稳定时应交替出现。若始终命中同一节点,先确认是否真的有两个实例、服务名大小写是否一致,以及请求是否经过标注了 @LoadBalanced 的 Builder。
关键边界
- 把基础地址写成
http://127.0.0.1:8081会绕过服务发现和负载均衡;需要固定地址的外部 API 应使用普通 Builder,避免被当作服务名解析。 - 负载均衡只负责选实例,不自动保证超时、重试、熔断或幂等。对 POST、扣款、下单等非幂等请求启用重试可能造成重复副作用,安全替代是关闭自动重试或使用幂等键。
- 注册中心状态存在传播延迟,实例刚下线时仍可能被选中。应同时配置连接与读取超时、健康检查、优雅下线,并用熔断器隔离持续失败节点。
- 默认不是会话粘滞。依赖本地 Session 的应用会出现用户状态漂移,应把会话外置到共享存储,或在明确评估后配置网关级粘滞策略。
排障清单
出现 No servers available for service 时,检查服务名、命名空间、注册中心连接和实例健康状态。出现 UnknownHostException: inventory-service 时,通常是请求使用了未加 @LoadBalanced 的客户端。出现调用分布失衡时,检查实例权重、自定义 ReactorLoadBalancer、缓存中的过期实例,以及是否有上游网关再次进行负载均衡。
使用服务名称发起同步 HTTP 请求而非固定主机地址。
调用内部服务
当调用方和目标服务都已接入服务发现时,把 URL 的主机部分写成注册中心中的服务名,例如 http://inventory-service。Spring Cloud LoadBalancer 会选择可用实例并补全真实主机与端口,业务代码不再固定 IP。
调用链路

inventory-service 是虚拟主机名,必须与服务注册时的 serviceId 对应。它不是普通 DNS 名;只有使用带 @LoadBalanced 的 HTTP 客户端构建器,才会在发送请求前解析为具体实例。
基本配置
下面是项目片段,依赖调用方已接入 Eureka、Consul、Zookeeper 或其他 DiscoveryClient 实现,并且目标服务提供 GET /api/stocks/{sku}。
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
</dependencies>版本由项目采用的 Spring Boot 与 Spring Cloud BOM 统一管理,不要为单个 starter 随意指定独立版本。
package com.example.order;
import org.springframework.boot.autoconfigure.web.client.RestClientBuilderConfigurer;
import org.springframework.cloud.client.loadbalancer.LoadBalanced;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestClient;
@Configuration
class InternalHttpConfiguration {
@Bean
@LoadBalanced
RestClient.Builder internalRestClientBuilder(RestClientBuilderConfigurer configurer) {
// 保留 Spring Boot 已注册的观测、消息转换等构建器定制。
return configurer.configure(RestClient.builder());
}
}
@Service
class InventoryGateway {
private final RestClient client;
InventoryGateway(@LoadBalanced RestClient.Builder builder) {
// 主机部分必须是注册中心中的服务名,而不是固定 IP。
this.client = builder.baseUrl("http://inventory-service").build();
}
StockResponse getStock(String sku) {
return client.get()
.uri("/api/stocks/{sku}", sku)
.retrieve()
.body(StockResponse.class);
}
}
@RestController
@RequestMapping("/debug")
class InventoryDebugController {
private final InventoryGateway gateway;
InventoryDebugController(InventoryGateway gateway) {
this.gateway = gateway;
}
@GetMapping("/stocks/{sku}")
StockResponse stock(@PathVariable String sku) {
return gateway.getStock(sku);
}
}
record StockResponse(String sku, int available) {
}启动调用方和目标服务后,通过调用方暴露的调试接口验证链路:
curl -s http://localhost:8080/debug/stocks/SKU-100预期输出(假设目标实例返回库存 12):
{"sku":"SKU-100","available":12}实际库存值、调用方端口和被选中的目标实例可能不同;只要响应结构正确且日志中没有固定目标地址,即表示服务名解析成功。
高频用法
路径变量使用 .uri("/api/stocks/{sku}", sku);查询参数使用 URI 构建器追加 queryParam;提交 JSON 时使用 .post().body(command).retrieve()。读操作适合直接返回 DTO,写操作应同时设计幂等键和明确的错误映射。
同步 RestClient 会占用请求线程,适合短耗时内部调用。需要流式响应、较高并发或端到端响应式链路时,改用带 @LoadBalanced 的 WebClient.Builder,不要在响应式线程中阻塞等待。
风险与边界
目标服务未注册、实例全部不健康或服务名拼写错误时,请求无法获得实际地址,可能直接失败或由上层映射为 5xx。安全做法是先检查注册中心实例,再设置超时、熔断和可观测指标,避免无限等待。
对非幂等写请求启用自动重试,可能重复扣款、重复创建或重复发送消息。安全替代方案是默认不重试写操作;确需重试时使用业务幂等键,并仅对连接失败、超时等明确的瞬时错误执行有限次数重试。
外部互联网地址不要复用带 @LoadBalanced 的构建器,否则主机名可能被当作服务 ID。项目同时访问内部服务和外部地址时,分别声明负载均衡与普通 RestClient.Builder,并用限定符明确注入。
排障清单
- 在注册中心确认
inventory-service至少有一个健康实例,并核对大小写和命名空间。 - 确认调用方同时包含 LoadBalancer starter 与实际使用的服务发现 starter。
- 核对注入的是带
@LoadBalanced的构建器,避免误用普通RestClient.Builder。 - 先区分无实例、连接拒绝、读取超时、404 和反序列化失败,再处理对应层级。
速查:服务名负责定位服务,LoadBalancer 负责选择实例;两者任一未生效,都不应退回到代码中硬编码 IP。
使用接口声明远程服务的请求路径、参数和返回类型。
声明 Feign 客户端
当内部 HTTP 接口较稳定、希望用 Java 接口统一描述路径、参数和返回类型时,使用 Spring Cloud OpenFeign。@FeignClient 生成代理对象,调用接口方法时再组装 HTTP 请求并通过服务发现定位目标实例。
声明关系

name 同时标识 Feign 命名客户端;未配置固定 url 时,它也作为服务 ID 参与负载均衡。path 适合放远程接口的公共前缀,方法上的 Spring MVC 注解继续描述 HTTP 方法、子路径、参数和请求头。
依赖与启用
下面是项目片段。OpenFeign starter 提供声明式客户端;若要按服务名选择实例,还要显式加入 LoadBalancer starter,并确保项目已有服务发现实现。
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
</dependencies>在启动类中明确列出客户端,能避免多模块项目因包扫描范围不一致而漏注册。
package com.example.order;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.openfeign.EnableFeignClients;
@SpringBootApplication
@EnableFeignClients(clients = InventoryClient.class)
public class OrderApplication {
public static void main(String[] args) {
SpringApplication.run(OrderApplication.class, args);
}
}客户端接口
接口方法必须与服务端契约逐项一致。路径变量建议显式写出名称,避免编译参数名未保留时出现绑定差异。
package com.example.order;
import java.util.UUID;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@FeignClient(name = "inventory-service", path = "/api/stocks")
interface InventoryClient {
@GetMapping("/{sku}")
StockResponse getStock(
@PathVariable("sku") String sku,
@RequestHeader("X-Request-Id") String requestId);
}
record StockResponse(String sku, int available) {
}
@RestController
@RequestMapping("/debug")
class InventoryFeignDebugController {
private final InventoryClient inventoryClient;
InventoryFeignDebugController(InventoryClient inventoryClient) {
this.inventoryClient = inventoryClient;
}
@GetMapping("/feign/stocks/{sku}")
StockResponse stock(@PathVariable String sku) {
// 每次调用生成请求 ID,便于跨服务关联日志。
return inventoryClient.getStock(sku, UUID.randomUUID().toString());
}
}启动两个服务后验证代理、负载均衡和反序列化是否同时生效:
curl -s http://localhost:8080/debug/feign/stocks/SKU-100预期输出(假设目标实例返回库存 12):
{"sku":"SKU-100","available":12}若收到 404,优先拼接检查 path 与方法路径;若收到 400,检查路径变量、查询参数和请求头;若代理调用成功但转换失败,检查 JSON 字段类型与 DTO。
超时与日志
为每个命名客户端单独配置连接超时、读取超时和日志级别,避免慢服务长期占用调用线程。示例值单位为毫秒,应按接口 SLA 调整。
spring:
cloud:
openfeign:
client:
config:
inventory-service:
connectTimeout: 1000
readTimeout: 2000
loggerLevel: basic配置生效后,可通过超时测试、Micrometer 指标或调用日志验证。生产环境不建议长期使用 full 日志级别,因为请求头和请求体可能包含令牌、手机号或业务敏感数据;排障时临时开启并配合脱敏。
风险与排障
在 @FeignClient 或配置中设置固定 url 时,请求会直接访问该地址,不再按 name 进行负载均衡。触发条件通常是本地联调地址被误带入生产;后果是绕过服务发现和故障实例摘除。安全替代是生产不设置 url,仅在隔离的本地配置中覆盖。
同一服务需要两套不同认证、超时或编码配置时,只复用相同 name 可能造成配置上下文冲突。应为每个客户端设置不同 contextId,同时保留相同服务名用于实例发现。
接口返回类型与远程 JSON 不一致会在解码阶段失败;路径、参数或 Content-Type 不一致则常见为 400、404 或 415。先用服务端契约核对方法签名,再检查 Feign 日志,不要通过把返回类型改成 Object 来掩盖契约错误。
不要假设写请求会被安全重试。显式启用重试前,先确认方法幂等;创建、扣款和消息发送类接口应使用幂等键、有限重试和明确的错误分类。
速查:name 定位服务,path 定义公共前缀,方法注解定义请求契约,DTO 定义响应契约;四处必须同时一致。
在服务调用链中传递认证、租户、语言和追踪信息。
传递请求头
在 OpenFeign 服务调用中,使用按客户端生效的 RequestInterceptor 复制白名单请求头。认证、租户、语言和业务请求标识可到达下游;链路追踪头应交给 Micrometer Tracing 自动注入,避免手工生成或覆盖 Trace ID。
调用链位置

拦截器位于“接收入站请求”和“Feign 发送出站请求”之间。只复制业务确实需要的字段;Host、Content-Length、Cookie、代理头和内部调试头应由 HTTP 客户端或网关重新计算,不得整包转发。
最小实现
片段示例:项目已引入 spring-cloud-starter-openfeign,并将配置类只绑定到可信的 inventory-service 客户端。示例使用 Servlet 请求上下文,不适用于 WebFlux 或已经切换线程的异步任务。
// TrustedHeaderForwardingConfig.java
package com.example.client;
import feign.RequestInterceptor;
import jakarta.servlet.http.HttpServletRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.web.context.request.RequestContextHolder;
import org.springframework.web.context.request.ServletRequestAttributes;
import java.util.List;
public class TrustedHeaderForwardingConfig {
private static final List<String> FORWARDED_HEADERS = List.of(
"Authorization", "X-Tenant-Id", "Accept-Language", "X-Request-Id");
@Bean
RequestInterceptor trustedHeaderForwardingInterceptor() {
return template -> {
var attributes = RequestContextHolder.getRequestAttributes();
if (!(attributes instanceof ServletRequestAttributes servletAttributes)) {
return; // 定时任务或线程切换后没有入站 Servlet 请求
}
HttpServletRequest request = servletAttributes.getRequest();
FORWARDED_HEADERS.forEach(name -> {
String value = request.getHeader(name);
if (value != null && !value.isBlank()) {
template.header(name, value);
}
});
};
}
}// InventoryClient.java
package com.example.client;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.GetMapping;
import java.util.Map;
@FeignClient(
name = "inventory-service",
configuration = TrustedHeaderForwardingConfig.class)
public interface InventoryClient {
@GetMapping("/internal/header-echo")
Map<String, Object> echoHeaders();
}验证
在测试环境让下游 /internal/header-echo 仅回显允许检查的字段,不要回显完整令牌。通过上游实际业务接口触发 Feign 调用:
curl -sS http://localhost:8080/orders/header-check \
-H 'Authorization: Bearer <TOKEN>' \
-H 'X-Tenant-Id: tenant-a' \
-H 'Accept-Language: zh-CN' \
-H 'X-Request-Id: req-001'预期输出:
{"authorizationPresent":true,"tenantId":"tenant-a","language":"zh-CN","requestId":"req-001","traceId":"<ID>"}<ID> 为运行时生成值。若业务字段齐全且调用链中出现新的下游 Span,说明业务头与追踪上下文均已生效。
风险与边界
- 复制全部入站请求头会在跨服务或跨域调用时泄露 Cookie、用户令牌和内部标记,并可能造成错误路由。安全替代方案是固定白名单,并针对目标服务单独配置。
- 用户
Authorization只有在下游属于同一信任边界且接受相同令牌受众时才能转发。跨系统调用应使用 OAuth2 客户端凭证或令牌交换,而不是复用用户令牌。 RequestContextHolder在线程池、@Async、消息消费和定时任务中通常为空。此时应显式传递调用上下文,或使用框架提供的上下文传播机制和服务身份。- 启用 Micrometer Tracing 后不要手工复制
traceparent、tracestate或 B3 头;重复注入或接受外部伪造值会污染链路。
排障清单
- 拦截器未执行:确认配置类已通过
@FeignClient(configuration = ...)绑定,且没有被误扫成所有客户端的全局配置。 - 上游能读到、下游收不到:检查网关、反向代理和服务网格是否删除了该字段,并核对实际调用是否走了目标 Feign 客户端。
- 同步调用正常、异步调用丢失:定位线程切换点,不要通过扩大 ThreadLocal 生命周期掩盖问题。
- 下游返回 401 或 403:检查令牌受众、作用域和过期时间;“头已传到”不代表“令牌可被下游接受”。
兼容性
该写法适用于阻塞式 Spring Cloud OpenFeign。WebFlux 应从 Reactor Context 读取上下文并通过 WebClient 过滤器注入;Spring HTTP Service Clients 则使用对应的 RestClient 或 WebClient 拦截器。OpenFeign 已进入功能完整阶段,新项目应评估 HTTP Service Clients。
分别控制连接与响应等待时间,防止远程调用长期阻塞。
设置调用超时
对 OpenFeign 分别设置连接超时和读取超时,可以限制连接建立失败与下游响应过慢造成的线程占用。超时值应按客户端单独配置,并与网关、熔断器、重试和上层接口总预算一起校准。
超时边界

connectTimeout 约束建立网络连接的等待时间;readTimeout 在连接建立后约束等待或读取响应的时间。DNS、连接池排队、TLS、底层客户端实现和重试都可能影响端到端耗时,因此两者不能简单相加后当作完整请求截止时间。
OpenFeign 配置
下面先给所有 Feign 客户端设置默认值,再为 inventory-service 设置更严格的覆盖值。connectTimeout 和 readTimeout 使用整数毫秒;客户端键应与 @FeignClient 实际使用的 name 或 contextId 对应。
spring:
cloud:
openfeign:
client:
config:
default:
connectTimeout: 1000
readTimeout: 3000
inventory-service:
connectTimeout: 500
readTimeout: 1500
loggerLevel: basic生效后,库存服务连接建立超过约 500 毫秒,或连接建立后响应等待超过约 1500 毫秒时,调用会失败并进入应用的异常处理、熔断或降级路径。实际时间会受调度、DNS 和底层 HTTP 客户端影响。
选值与验证
先从调用链预算倒推,而不是直接复制统一值。例如上层接口预算为 4 秒,可给关键下游约 1.5 秒读取预算,并为业务处理、序列化和异常转换保留余量。连接超时通常应明显小于读取超时,但跨地域、冷连接或复杂 TLS 场景需要单独压测。
验证时准备一个可控的测试下游:一个端口不监听用于验证连接失败,另一个接口故意延迟超过 readTimeout。记录 Feign 客户端计时、异常类型和上游状态码;若应用未统一映射异常,超时可能表现为 500,生产环境通常应转换为明确的 504 或业务降级结果。
风险与边界
- 连接超时过小会在 DNS 抖动、冷连接、TLS 握手或跨区网络中制造误失败,后果是错误率突增。安全做法是基于分环境的 P95/P99 建连数据设置余量。
- 读取超时过大会让工作线程、连接和上游请求长期占用,最终形成级联阻塞。替代方案是设置更短的下游预算,并配合隔离、熔断和有界队列。
- 自定义
Retryer会重复整个远程调用,可能把 1.5 秒超时放大为多倍延迟并增加下游压力。Spring Cloud OpenFeign 默认禁用重试;覆盖默认值前必须限定次数、退避和幂等范围。 - 读超时的精确定义受 Apache HC5、OkHttp 或其他底层客户端影响,流式响应也可能表现不同。需要完整截止时间时,应再设置上层总预算或 TimeLimiter。
排障清单
- 配置不生效:核对客户端键是否匹配
name或contextId,并检查客户端专属配置是否覆盖default。 - 数值差一个数量级:OpenFeign 这里使用整数毫秒,不要照搬 Spring Cloud Gateway 的 Duration 写法。
- 仍然等待很久:检查 DNS、连接池获取连接、代理、重试、熔断器和线程池排队,超时未必覆盖这些阶段。
- 比配置更早失败:可能是连接被拒绝、网关超时、TimeLimiter、负载均衡实例切换或上游客户端先终止。
- 超时后仍持续压测下游:检查是否启用了重试,或服务端任务在客户端断开后仍未取消。
兼容性
Spring Cloud Gateway 使用不同配置键,且全局 response-timeout 使用 Duration;不要与 OpenFeign 的客户端配置混用。
spring:
cloud:
gateway:
httpclient:
connect-timeout: 1000
response-timeout: 5sWebClient、RestClient 和 Spring HTTP Service Clients 的超时由底层 HTTP 客户端或连接器配置。OpenFeign 已进入功能完整阶段,新项目应评估 HTTP Service Clients,并重新验证对应客户端的超时语义。