黑河市all1. 为什么我不想再写 RestTemplate 了——从一个真实调用场景拆到“破防”为止
先交代一下背景：我负责的一个订单中台服务，高峰期日均要调用几百万次下游的库存、商品、用户积分服务。调用方式一直用的是 Spring 自带的 RestTemplate，配合 Ribbon 做负载均衡。
可能你要说，RestTemplate 不是挺成熟的吗？能用，但“能用”和“好用”是两码事。我先给你看一段我最不想维护的代码，这是真实项目中抽出来的简化版：
java复制public OrderDetailVO queryOrderDetail(String orderId) {
// 1. 拼接 URL，参数多的时候简直灾难
String url = "http://INVENTORY-SERVICE/inventory/check?"
+ "orderId=" + orderId
+ "&skuId=" + skuId
+ "&quantity=" + quantity;
// 2. 手动设置请求头
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("Authorization", "Bearer " + token);
// 3. 手动构造 HttpEntity
HttpEntity<String> entity = new HttpEntity<>(headers);
// 4. 手动发送请求，手动解析
ResponseEntity<String> response = restTemplate.exchange(
url, HttpMethod.GET, entity, String.class);
// 5. 手动把 JSON 字符串转成对象
InventoryResult result = objectMapper.readValue(response.getBody(), InventoryResult.class);
// 6. 手动判空、手动处理异常
if (result == null || result.getCode() != 0) {
throw new BizException("库存查询失败");
}
return convert(result);
}
你仔细品一下这段代码里有多少个“手动”：手动拼 URL、手动塞 Header、手动构建 HttpEntity、手动解析响应、手动判空。这些步骤本身没什么技术含量，但每个都可能出错，而且出错的位置全都在“我不关心”的地方——我只想调个接口拿到数据，为什么要把 HTTP 协议细节全暴露在我的业务代码里？
更难受的是，假如你有 30 个下游接口要调，每个接口都要写这么一遍，那将是成百上千行的样板代码。命名稍微不一致、拼写稍微出错、参数类型不小心多打了个空格，都要排查半天。维护这段代码的同事，看到这种片段第一反应不是改逻辑，而是先猜当初写的人想干嘛。
还有一类很隐蔽的坑：RestTemplate 的 URL 里如果带了特殊字符（比如参数里有 &、?、空格、中文），你没做 URLEncode，就会得到一堆莫名其妙的 400 或 500。我之前排查过一个线上问题，用户昵称里带了个 & 导致下单接口偶尔失败，查了半小时才发现是 URL 没编码的问题。
所以当项目进入 Spring Cloud 生态之后，我几乎毫不犹豫地切换到了 OpenFeign。它解决的痛点非常直接：把“调用一个 HTTP 接口”这件事，从“写一堆手动的拼装逻辑”简化成“声明一个 Java 接口，写上注解，完事”。你可以理解为：RestTemplate 是“你自己当快递员，一个个把包裹搬上楼”，OpenFeign 是“你填一张快递单，配送的事交给快递公司”，你只关心要什么，不关心怎么送。
这篇不是 OpenFeign 的官方文档翻译，而是我从 RestTemplate 迁移到 OpenFeign 后，把整个过程中的关键配置、负载均衡、熔断降级、性能调优和踩坑记录都整理出来，希望能帮准备迁移或正在迁移的人少走弯路。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. OpenFeign 声明式调用的核心套路：一个接口就算完事
2.1 三分钟接一个下游服务
OpenFeign 的用法简洁到让人怀疑是不是漏了什么。假设我要调用库存服务的 checkStock 接口，只需要定义一个接口：
java复制@FeignClient(name = "inventory-service")
public interface InventoryClient {
@GetMapping("/inventory/check")
InventoryResult checkStock(@RequestParam("orderId") String orderId,
@RequestParam("skuId") String skuId,
@RequestParam("quantity") Integer quantity);
}
然后在启动类上加上 @EnableFeignClients：
java复制@SpringBootApplication
@EnableFeignClients
public class OrderApplication {
public static void main(String[] args) {
SpringApplication.run(OrderApplication.class, args);
}
}
接着在 Service 里直接注入调用：
java复制@Service
public class OrderService {
private final InventoryClient inventoryClient;
public OrderService(InventoryClient inventoryClient) {
this.inventoryClient = inventoryClient;
}
public void check(OrderCreateRequest request) {
InventoryResult result = inventoryClient.checkStock(
request.getOrderId(), request.getSkuId(), request.getQuantity());
// 直接用 result，不需要手动解析
}
}
就这三步，调用就通了。对比一下开头那 30 行 RestTemplate 代码，这里没有任何 URL 拼接、没有任何 HttpEntity、没有任何 JSON 手动转换，连 try-catch 都省了，异常框架自动帮你转成 FeignException。
你可能会问：这接口里的方法我都没写实现，凭什么就能调用？这就是 OpenFeign 最核心的原理——动态代理。Spring 容器启动时，@EnableFeignClients 会扫描所有 @FeignClient 注解的接口，然后基于 JDK 动态代理生成一个代理对象，凡是调用接口方法，都会被代理拦截，然后根据方法上的注解解析出 URL、HTTP Method、参数、Header，拼装成一个真正的 HTTP 请求发出去。
2.2 注解到底是怎么变成 HTTP 请求的
我们入个门，看看注解的映射规则，这个理解了以后写接口就不会懵：
| 注解 | 作用 | 对应 RestTemplate 里的操作 |
|---|---|---|
@PathVariable("id") |
路径参数，替换 URL 里的 {} 占位符 |
手写拼接 URL 中的变量 |
@RequestParam("name") |
查询参数，拼到 URL 问号后面 | restTemplate.getForObject(url + "?name=" + name, ...) |
@RequestHeader("token") |
请求头参数 | headers.set("token", value) |
@RequestBody |
JSON 请求体 | HttpEntity + 手动序列化 |
@FeignClient(name = "服务名") |
声明这是哪个服务的客户端 | 手动写死服务名或域名 |
要注意的是，@PathVariable 必须显式指定参数名，比如 @PathVariable("id") Long id，因为编译的时候如果没加 -parameters 参数，Java 反射拿不到参数名，默认会直接用 arg0 这种名字，到时候映射不上，请求会 404 或者 500。这个问题踩的人特别多，后面我会专门展开讲。
接口定义好了之后，OpenFeign 会为每个方法生成一个 MethodMetadata，把 URL、请求方法、参数索引、请求体类型这些信息全部解析好缓存起来。真正发请求的时候，通过 MethodHandler（默认是 SynchronousMethodHandler）执行：
- 根据传入的参数，按元数据替换 URL 模板中的
{} - 把参数按约定编码到 Query / Header / Body
- 交给
Client实现去执行 HTTP 请求 - 拿到响应后，用
Decoder把响应体反序列化成接口的返回值类型
这也是为什么 OpenFeign 能做到“声明式”的关键——你在接口里写的每一个注解，最终都会被翻译成 HTTP 协议里的对应要素，框架帮你把协议细节消化了。
3. 从 demo 到生产：必须调好的几个关键配置
接口通了只能算 demo 阶段，生产环境还差得远。我这里按优先级列一下我每次接入 OpenFeign 都会调的配置，少一个线上大概率会出事。
3.1 超时与重试：不设超时就是让线程池等死
OpenFeign 的默认超时是 60 秒。你没看错，默认值就这么长。在微服务架构下，下游一旦慢查询或者线程池满，60 秒足够把你的服务线程全部拖死。
我一般根据接口的重要性分级设置，而不是一刀切：
yaml复制feign:
client:
config:
default:
# 连接超时：TCP 建立连接的最大等待时间
connectTimeout: 2000
# 读取超时：服务端处理完并返回响应的最大等待时间
readTimeout: 5000
inventory-service:
# 库存服务接口慢，单独放宽
connectTimeout: 3000
readTimeout: 8000
这里的逻辑是：default 作为兜底，优先级最低。inventory-service 这种按服务名指定的配置会覆盖 default。如果你想要更细粒度，还可以在方法上用 @FeignClient 加 configuration 属性指定单独的配置类，但一般不建议搞太细，会增加维护成本。
重试策略同样重要。OpenFeign 本身默认不重试，需要引入 spring-retry 才会真正生效。而且它的重试逻辑默认是跟随 Ribbon 或 Spring Cloud LoadBalancer 的配置走的。我的建议：
重试只对 GET 这种幂等请求开启，POST/PUT/DELETE 这类写操作建议保持不重试或者最多一次，否则下游可能出现重复下单、重复扣款这类幂等事故。
配置示例：
yaml复制spring:
cloud:
loadbalancer:
retry:
enabled: true
feign:
client:
config:
default:
# 重试次数，不包含第一次请求
requestInterceptors:
- com.example.feign.CustomRetryInterceptor
这个配置不完整，我实际更推荐在代码层面对特定场景显式控制重试，而不是全开。后面讲坑的时候会说。
3.2 日志级别：线上别开 FULL，但 NONE 也别用
OpenFeign 默认日志级别是 NONE，什么都不打印。调试问题的时候，简直两眼一抹黑。但如果你直接改成 FULL，生产环境会打出全部请求头和响应体，日志量暴增，而且可能把用户敏感信息打出去。
我的建议是：本地开发用 FULL，测试环境用 BASIC，线上至少用 HEADERS。配置方式：
java复制@Configuration
public class FeignLogConfig {
@Bean
Logger.Level feignLoggerLevel() {
return Logger.Level.BASIC; // 或 FULL / HEADERS / NONE
}
}
同时要在 application.yml 里指定哪个包输出日志：
yaml复制logging:
level:
com.example.order.client: debug
注意：com.example.order.client 是你的 FeignClient 接口所在的包路径，不是 services 包。这个容易搞混，我一开始就配错了，结果配了半天日志没输出。
BASIC 级别会打印请求方法、URL、响应状态码和耗时，大多数问题靠这个就能定位。如果发现响应内容不对，再临时调成 FULL 排查，排查完记得改回来。
3.3 拦截器塞 token：别再每个接口传一遍 Header
微服务之间调用，经常需要传递认证信息。如果你用 RestTemplate，每个调用方都要手动往 Header 里塞 token；用 OpenFeign 之后，只需要实现一个 RequestInterceptor：
java复制@Configuration
public class FeignAuthConfig {
@Bean
public RequestInterceptor authRequestInterceptor() {
return template -> {
// 从当前请求上下文里取 token，也可以从 Spring SecurityContext 取
RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
if (requestAttributes instanceof ServletRequestAttributes servletRequestAttributes) {
String token = servletRequestAttributes.getRequest().getHeader("Authorization");
if (token != null) {
template.header("Authorization", token);
}
}
};
}
}
这里有个小细节：把 RequestContextHolder.getRequestAttributes() 拿到之后一定要判空。因为 OpenFeign 不一定是在 Web 请求线程里执行的，如果被放到异步线程池、MQ 消费线程里执行，这里拿到的就是 null，直接调用会 NPE。
每次请求进来，这个拦截器都会自动把当前请求的 Authorization 头透传给下游，优雅得很。以后加新的下游服务，只需要定义接口，不用再关心认证头传递的问题。
3.4 编解码与错误处理：别让非 2xx 响应变成一堆异常堆栈
默认情况下，OpenFeign 用 Spring 的 HttpMessageConverter 做编解码，也就是把 @RequestBody 的对象序列化成 JSON，把响应 JSON 反序列化成你的返回类型。这有个隐患：如果下游返回的不是 2xx，OpenFeign 会直接抛 FeignException，而且不会执行反序列化。
也就是说，下游如果返回 {"code": 500, "msg": "库存不足"}，但 HTTP 状态码是 200，那没问题，响应体会正常解析成你的返回类型。但如果下游遵循 RESTful 规范，直接返回 500 状态码 + 错误详情 JSON，那你只能捕获 FeignException，然后从 e.contentUTF8() 里手动解析错误信息。
我的做法是自定义一个 ErrorDecoder：
java复制public class FeignErrorDecoder implements ErrorDecoder {
private final ObjectMapper objectMapper = new ObjectMapper();
@Override
public Exception decode(String methodKey, Response response) {
try {
String body = response.body() == null ? null : Util.toString(response.body().asReader(StandardCharsets.UTF_8));
// 尝试解析下游返回的业务错误信息
if (body != null) {
JsonNode node = objectMapper.readTree(body);
String code = node.path("code").asText();
String message = node.path("message").asText();
return new BizException(code, message);
}
} catch (IOException e) {
// ignore
}
return new FeignException.BadRequest(
response.status(),
methodKey,
response.request(),
response.body() == null ? null : response.body().asByteArray(),
response.headers());
}
}
然后注册到 Feign 配置里：
java复制@Configuration
public class FeignConfig {
@Bean
public ErrorDecoder errorDecoder() {
return new FeignErrorDecoder();
}
}
这样调用方就不用关心怎么解析 FeignException，统一拿到的是业务异常 BizException，处理逻辑就跟本地调用一样了。
4. 负载均衡：OpenFeign 到底集成了没有？怎么才能真正用起来
这个是很多人搞不清的点，也是热搜词里最常被问到的：OpenFeign 内部集成了负载均衡吗？
我的答案是：OpenFeign 本身没有，但 Spring Cloud OpenFeign 整合了。 这中间有个历史演变，我说清楚你就不会懵了。
feign-core 只是 OpenFeign 这个开源库的核心，它只负责把接口方法翻译成 HTTP 请求，它根本不知道什么叫“服务名”，更不知道什么叫“负载均衡”。你如果直接用原生 OpenFeign，那 @FeignClient(name = "inventory-service") 里的地址是无从解析的，它只会把它当成一个普通字符串，然后请求直接失败。
真正让 inventory-service 这种服务名被解析成实际 IP:Port 的，是 Spring Cloud 生态里的服务发现 + 负载均衡。在 Spring Cloud 早期版本，这个负载均衡组件是 Ribbon，OpenFeign 整合 Ribbon 之后，调用时先通过服务发现拿到 inventory-service 的所有实例列表，再按 Ribbon 的负载均衡策略（轮询、随机、权重等）选出一个实例，替换掉 URL 里的服务名，最后发起请求。
Spring Cloud 2020 年之后，Ribbon 进入维护模式并逐渐被移除，替换者就是 Spring Cloud LoadBalancer。所以现在的技术栈是这样的：
| 组件 | 职责 |
|---|---|
| OpenFeign | 把接口方法翻译成 HTTP 请求（声明式） |
| Spring Cloud LoadBalancer | 根据服务名从注册中心拿实例列表，按策略选一个实例 |
| Nacos / Eureka / Consul | 服务注册与发现，维护实例列表 |
如果你用的是 spring-cloud-starter-openfeign + spring-cloud-starter-loadbalancer + Nacos，那 @FeignClient(name = "inventory-service") 就能自动通过 Nacos 找到实例，再通过 LoadBalancer 做负载均衡。这也是当前 Spring Cloud 微服务的主流搭配。
所以那个问题的准确版本是：“OpenFeign 并没有内置负载均衡，但 Spring Cloud OpenFeign 通过整合 Spring Cloud LoadBalancer，让 FeignClient 天然具备负载均衡能力。你在使用 Spring Cloud 的 OpenFeign 时，不用额外写负载均衡代码，但必须引入 loadbalancer 依赖，才能让服务名解析生效。”
一个典型依赖长这样：
xml复制<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>
<dependency>
<groupId>com.alibaba.cloud</groupId>
<artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
</dependency>
Nacos 负责把 inventory-service 实例注册进去，LoadBalancer 负责挑一个，OpenFeign 负责把请求发出去。三者各司其职。
如果你要自定义负载均衡策略，比如某个服务想用“最少并发数”策略，Spring Cloud LoadBalancer 的实现方式是写一个 ServiceInstanceListSupplier：
java复制@Configuration
public class LoadBalancerConfig {
@Bean
public ServiceInstanceListSupplier serviceInstanceListSupplier(
ConfigurableApplicationContext context) {
return ServiceInstanceListSupplier.builder(context)
.withDiscoveryClient() // 使用注册中心实例
.withHealthChecks() // 跳过不健康实例
.withHints() // 可按 zone 优先
.build();
}
}
这个属于进阶玩法，大部分场景默认的轮询已经够用。
5. 线上环境：熔断、降级、连接池一个都不能少
5.1 Fallback 降级：写错了咋不生效
接入 OpenFeign 之后，你肯定想实现失败降级：下游挂了，返回一个兜底数据，别把错误打给用户。Spring Cloud OpenFeign 支持 fallback 和 fallbackFactory 两种方式，很多新手在这容易踩坑。
先看正确写法：
java复制@FeignClient(name = "inventory-service", fallback = InventoryClientFallback.class)
public interface InventoryClient {
@GetMapping("/inventory/check")
InventoryResult checkStock(@RequestParam("orderId") String orderId,
@RequestParam("skuId") String skuId);
}
Fallback 类实现接口，并且要让 Spring 管理：
java复制@Component
public class InventoryClientFallback implements InventoryClient {
@Override
public InventoryResult checkStock(String orderId, String skuId) {
return InventoryResult.fail("库存服务暂不可用，请稍后重试");
}
}
这里有几个坑：
第一，必须开启 feign.circuitbreaker.enabled=true，否则 fallback 不生效。Spring Cloud 默认是关闭的，你不开启它就直接把异常抛给你，根本不走 fallback。
yaml复制feign:
circuitbreaker:
enabled: true
第二，fallback 类必须被 Spring 管理（加 @Component），否则 Bean 注入不到代理对象里。
第三，fallback 方法返回的数据要想清楚，数据流的业务方要能区分“这是真实结果还是降级结果”。我建议在返回类型里加一个 degraded 标志位，或者统一走错误码，否则下游拿到降级数据当真数据用，会引发严重的数据一致性问题。
fallbackFactory 比 fallback 更强大，它能在降级时拿到具体的异常原因，方便排查：
java复制@Component
public class InventoryFallbackFactory implements FallbackFactory<InventoryClient> {
@Override
public InventoryClient create(Throwable cause) {
return new InventoryClient() {
@Override
public InventoryResult checkStock(String orderId, String skuId) {
log.error("inventory-service degrade, cause:", cause);
return InventoryResult.fail("inventory unavailable");
}
};
}
}
我的建议是：线上项目一律用 fallbackFactory，这样既能降级又能留痕。用 fallback 的时候，你只知道被降级了，但不知道原因，给排查增加难度。
5.2 HTTP 客户端换成 OkHttp / HttpClient
OpenFeign 默认用的是 java.net.HttpURLConnection，这玩意儿问题是：没有连接池、没有 HTTP/2、性能一般、不支持重试。在高并发下，它会成为瓶颈。
好在 OpenFeign 支持替换底层 Client 实现。常见的有两种：Apache HttpClient 和 OkHttp。我以 OkHttp 为例，因为它在连接复用、HTTP/2、请求取消上表现更好，而且代码简单。
先引入依赖：
xml复制<dependency>
<groupId>io.github.openfeign</groupId>
<artifactId>feign-okhttp</artifactId>
</dependency>
然后禁用默认的 HttpURLConnection，配置：
java复制@Configuration
public class FeignOkHttpConfig {
@Bean
public okhttp3.OkHttpClient okHttpClient() {
return new okhttp3.OkHttpClient.Builder()
.connectTimeout(2, TimeUnit.SECONDS)
.readTimeout(5, TimeUnit.SECONDS)
.connectionPool(new ConnectionPool(50, 5, TimeUnit.MINUTES))
.build();
}
}
配置里：
yaml复制feign:
httpclient:
enabled: false
okhttp:
enabled: true
换成 OkHttp 之后，你会发现性能有明显的提升，尤其是连接复用的场景。之前每请求新建连接的开销省掉了，接口 RT（响应时间）能下降一截。我做过一个压测，同时 200 并发调下游接口，RestTemplate + HttpURLConnection 的线程等待明显加剧，而 OpenFeign + OkHttp 的连接复用让吞吐量稳定很多。
Apache HttpClient 路线也类似，引入 feign-httpclient 依赖并开启配置即可。选哪个？我的经验是：如果服务已经引入了 OkHttp 或者对 HTTP/2 有需求，选 OkHttp；如果团队更熟悉 Apache HttpClient 的配置体系，选 HttpClient 也没毛病。两者的能力边界在这个场景下相差不大。
5.3 连接池参数怎么给才合理
OkHttp 的连接池参数不能乱填。maxIdleConnections 表示每个目标主机最多保持多少空闲连接；keepAliveDuration 表示空闲连接最多保留多久。太大会导致连接长时间占着不释放，太小会导致频繁建连。
我的经验值：单个下游实例的 maxIdleConnections 设为 50，keepAliveDuration 设为 5 分钟。如果下游实例很多（比如 20 个实例），那单个 FeignClient 的配置可能要放大一点，但不用夸张，连接池是按目标主机维度去统计的。
还有一点很容易忽略：连接池配置之后，一定要在压测环境观察连接数曲线。如果发现连接数持续涨到上限且不回落，说明有连接泄漏，大概率是响应流没有关闭。OkHttp 的 Response.body().string() 会关闭流，但如果你的 ErrorDecoder 里读取 body 的方式不对，可能泄漏连接。
6. 转型路上最常踩的 6 个坑（含完整排查链路）
这一节全部来自真实项目经验，大多是迁移过程中踩出来的，按踩坑频率排序。
6.1 @PathVariable 不写参数名的 404 噩梦
现象：接口定义没问题，服务也起来了，但调用老是 404，日志里显示的路径是 /inventory/check/arg0。
排查链路：
- 先看 OpenFeign 自动生成的 URL，把日志级别调成 FULL，发现 URL 路径上带着
arg0。 - 意识到
@PathVariable("orderId")这种显式参数名没写。 - 查编译配置，确认项目的
pom.xml里是否开启了-parameters参数，或者用了 Lombok@ParametersAreNonnullByDefault。
最终结论：OpenFeign 在解析 @PathVariable时，需要一个 *参数名*，如果 JDK 编译时没把参数名信息保留在字节码里，反射拿到的就是arg0、arg1，于是 URL 模板占位符 ` 无法匹配，请求直接打到错误的路径上。
修复很简单：每个 @PathVariable 都显式写明参数名。别依赖编译参数，这是最稳妥的做法：
java复制@GetMapping("/inventory/check/{orderId}")
InventoryResult checkStock(@PathVariable("orderId") String orderId);
6.2 GET 请求传对象：@SpringQueryMap vs @RequestBody
有次写 GET 请求，参数有七八个，不想拆散在方法签名里，于是想用对象接收。我一开始直接：
java复制@GetMapping("/inventory/check")
InventoryResult checkStock(InventoryQuery query);
结果发现 query 对象的字段全都没传过去，下游拿到的全是 null。
原因：OpenFeign 默认对 GET 请求的 POJO 参数是不会自动转 Query 参数的。它有两个选择：
@RequestBody：序列化成 JSON 请求体——但 GET 请求通常不带 Body，很多服务端框架默认不解析 GET 的 body。@SpringQueryMap：专门处理这种“GET 参数用对象组织”的场景，把对象字段展开成 query 字符串。
正确写法：
java复制@GetMapping("/inventory/check")
InventoryResult checkStock(@SpringQueryMap InventoryQuery query);
注意 @SpringQueryMap 只对 GET 有效，POST 用 @RequestBody 依然最合适。
6.3 下游返回非 2xx 时，OpenFeign 抛异常而不是走 ErrorDecoder
前面 3.4 节提到了 ErrorDecoder，但有同学会问：我明明注册了 ErrorDecoder，为什么调用方还是收到 FeignException，而不是我自定义的 BizException？
排查链路：
- 检查
ErrorDecoder是否被 Spring 管理 —— 如果只写在自定义配置类里但没加@Bean或者没被@FeignClient(configuration = XxxConfig.class)指定，它根本不会生效。 - 检查是否有多个 Feign 配置，可能存在“局部配置覆盖全局配置”的问题。
- 查看异常堆栈，如果是
FeignException而非BizException，说明decode方法根本没有被调用。
ErrorDecoder 不是 Spring Bean 就一定会生效的，你必须通过 @FeignClient 的 configuration 属性指定配置类，或者把配置类放到 @EnableFeignClients(defaultConfiguration = ...) 里面。而且这个配置类不要加 @Configuration——加了会导致所有 FeignClient 都加载这个配置，容易冲突。
6.4 Fallback 不生效，到底哪里配置错了
Fallback 不生效的原因，我遇到的有三种：
feign.circuitbreaker.enabled没开。- fallback 类没有
@Component注解。 @FeignClient里没写fallback = Xxx.class，只写了个 fallbackFactory。
注意：如果一个 FeignClient 同时配置了 fallback 和 fallbackFactory，fallback 优先级更高。如果你的目的是在降级时打日志，那必须用 fallbackFactory，并把它配在 fallbackFactory 属性里，而不是 fallback 里。
还有一个容易忽略的：Fallback 只对 Feign 调用异常生效，如果被调用的服务返回了 200 但业务上失败了（比如 {code: 500}），它不会进 fallback，因为 OpenFeign 看到的是 HTTP 2xx 成功响应。这类“业务错误”需要在 ErrorDecoder 或者你的业务逻辑里自行判断。
6.5 OpenFeign 与注册中心断开后，调用失败但异常信息不明确
生产环境有一次 Nacos 短暂不可用，结果所有 Feign 调用开始报错，但异常堆栈只显示 No instances available for inventory-service，没有具体的 IP、端口，排查起来很费劲。
这个其实是 Spring Cloud LoadBalancer 找不到可用实例时的标准异常。它出现的原因通常是：
- 下游服务所有实例都被下线/宕机。
- 注册中心与服务的健康检查有问题，实例被标记为不健康。
- 网络分区导致客户端拿不到实例列表。
排查链路的建议：
- 先看 Nacos 控制台，确认服务列表里有没有健康实例。
- 再看调用方的
spring.cloud.nacos.discovery配置，命名空间、分组、集群是否跟服务端一致。命名空间对不上是最常见的“服务名明明有实例但客户端找不到”的原因。 - 最后看 LoadBalancer 的
ServiceInstanceListSupplier是否被自定义覆盖了，有些团队配置了 zone-aware 策略，但消费方机器所在 zone 跟提供方不在一个区，导致过滤后实例为空。
6.6 服务名大小写、下划线导致的解析失败
Nacos 里注册的服务名一般是小写。如果你的 @FeignClient(name = "inventory-service") 跟注册名不一致，哪怕只是一个下划线或者一个大小写字母差别，都会导致“找不到实例”。
这个问题的坑在于：OpenFeign 在解析服务名时，如果服务名不存在，日志可能只是简单的报错，不会明确告诉你“这个服务名在注册中心不存在，你是不是拼错了”。所以排查这种问题，第一件事就是去注册中心确认精确的服务名。
7. 到底要不要全面替换 RestTemplate——我的建议
讲到这里，你可能会觉得 OpenFeign 这么香，是不是应该把所有 RestTemplate 的调用全部替换掉？
我的建议是：分情况，别搞一刀切。
适合用 OpenFeign 的场景：
- 服务间调用，且服务在注册中心中注册了。
- 调用方有多个下游服务，接口数量多，希望减少样板代码。
- 需要统一处理认证、日志、负载均衡、熔断降级的场景。
- 团队已经引用了 Spring Cloud 生态。
继续用 RestTemplate 的场景：
- 调用的是外部第三方 API（不经过注册中心，服务名解析没意义）。
- 调用频率极低、接口数量极少的场景，比如偶尔调一次内部工具接口。
- 需要非常底层的 HTTP 控制，比如自定义连接管理、流式下载大文件等，RestTemplate 反而更“见得着摸得着”。
如果你现在用的是 WebClient（响应式）， 那其实不需要迁移到 OpenFeign，WebClient 本身功能更全面，只是编程模型是响应式的，跟声明式是两种不同的风格。
我做迁移时的原则是：以注册中心为边界，凡是能通过服务名访问的内部服务，一律用 OpenFeign 声明式调用；凡是外部不可控的 HTTP 服务，保留 RestTemplate 或者直接用 OkHttp + 手动封装。这样既享受了声明式的红利，又不至于把项目变成“为了 Feign 而 Feign”。
另外建议新项目直接上 OpenFeign，不要再引入 RestTemplate 了。团队里新来的同事理解 FeignClient 接口的效率，比理解那一堆 HttpEntity、ResponseEntity 要快得多。
8. 迁移过程中的一点额外体会
最后分享一个我切换过程中的小技巧。如果你不想一次性把所有 RestTemplate 调用全替换完，可以并行运行，然后做流量灰度对比。
我当时是先写了新的 FeignClient 接口，然后在配置里用一个开关控制，让 10% 的流量走 OpenFeign，90% 流量走 RestTemplate，观察一段时间接口的 RT、成功率、异常量是否一致。确认没问题后再逐步加大比例，最后把 RestTemplate 调用代码删掉。
这个做法比“改完直接上线”稳妥得多，尤其是下游接口对请求头、参数名很敏感的时候，新旧实现之间可能有一些肉眼看不出来的差异，灰度对比能快速暴露问题。
在做灰度对比之前，要把日志级别调好。FeignClient 的 FULL 日志和 RestTemplate 的日志格式不一样，建议在灰度期间统一打到一个专门的日志文件，对比请求参数和响应结果。我实际做下来，很快发现了一个问题：旧代码里某个字段没传（因为 RestTemplate 代码里拼参数时漏了），新代码 OpenFeign 传了，下游的行为不一样。这种差异如果不灰度，直接在线上全量换，很难定位到底是哪一侧的锅。
还有一个体会：换了 OpenFeign 之后，接口定义变成了一个小型的 API 契约文档。每个下游服务都应该有对应的 FeignClient 接口，接口里方法名、参数名、路径都写得清清楚楚。后续新同事接手，只需要看接口签名就能知道下游服务提供了哪些能力，不需要翻调用代码去猜。这一点是 RestTemplate 永远给不了的。
如果你现在正处在“要不要从 RestTemplate 迁移到 OpenFeign”的纠结期，我的态度是：可以迁，但别小看配置细节。把这篇文章里提到的超时、日志、拦截器、ErrorDecoder、熔断、连接池都配好，然后走一遍灰度，你会明显感觉到声明式调用的爽快。