1. 当Feign告诉你“找不到”一次典型的404异常现场还原大家好我是老张在微服务这块摸爬滚打十来年了用Feign做服务间调用那真是家常便饭。今天想和大家聊聊一个几乎每个用Feign的开发者都会踩的坑——FeignException$NotFound: [404]。这玩意儿说大不大但真遇到了尤其是新手看着日志里那个冷冰冰的404心里那叫一个慌。别急今天我就带你从根儿上把它捋明白。咱们先来还原一个最经典的“案发现场”。想象一下你手头有两个Spring Boot服务一个叫“商品分类服务”category-service跑在8080端口另一个叫“订单服务”order-service跑在8081端口。订单服务需要通过Feign去调用商品分类服务里的一个简单测试接口。商品分类服务那边代码清爽得很RestController RequestMapping(/category) public class CategoryController { GetMapping(/test) public String test() { return Hello from Category Service!; } }访问http://localhost:8080/category/test妥妥的能返回“Hello from Category Service!”。订单服务这边你定义了一个Feign客户端接口想着去调用上面的接口FeignClient(url http://localhost:8080/category, name categoryService) public interface CategoryService { GetMapping(/test) String test(); }然后在你的订单服务Controller里你注入了这个CategoryService信心满满地调用了test()方法。结果呢控制台给你抛了个大大的异常feign.FeignException$NotFound: [404] during [GET] to [http://localhost:8080/category/test/test]看到没日志里打印的最终请求URL是http://localhost:8080/category/test/test。路径里多了一个/test这就是今天我们要揪出来的“元凶”——路径拼接错误。很多朋友一开始会疯狂检查服务是否启动、端口是否正确、依赖有没有引入折腾半天最后发现是这种细节问题真是让人哭笑不得。接下来我们就一层层剥开Feign调用的“洋葱”看看这个多余的路径是怎么来的又该怎么避免。2. 深入Feign的“内心戏”路径是如何被拼接起来的要解决问题光看表面错误可不行咱们得钻进Feign的肚子里看看它到底是怎么处理我们写的那些注解的。很多人觉得Feign用起来简单FeignClient一写GetMapping一标就能调了。但恰恰是这种“简单”容易让我们忽略背后的机制一旦出问题就抓瞎。2.1FeignClient注解你的服务“名片”首先看FeignClient这个注解。它就像是这个Feign客户端接口的“名片”告诉Spring“嗨我要定义一个远程调用的客户端啦”。里面的url和name属性是关键。url属性这是最直接指定目标服务地址的方式。像我们例子里的url http://localhost:8080/category它指明了请求的基础路径Base URL。Feign会把这个地址作为请求的起点。name属性这个通常用于服务发现。如果你用了Eureka、Nacos这类注册中心name一般对应的是服务在注册中心里的名称。Feign会通过这个名称去注册中心找到服务的真实地址IP和端口。我们例子中为了简化直接用了url所以name在这里更多是起一个标识符的作用。这里有个非常重要的理解当你同时指定了url和name并且url是一个完整的HTTP地址时Feign会**优先使用url**作为请求的基础地址。它不会再用name去走服务发现那一套了。所以我们的请求起点就是http://localhost:8080/category。2.2 方法上的注解请求的“具体指令”定义好客户端要找谁之后接下来就是告诉它“具体要干什么”。这就是接口方法上那些注解GetMapping,PostMapping,RequestMapping等的作用。以GetMapping(/test)为例。这个注解做了两件事指定HTTP方法告诉Feign这是一个GET请求。指定请求路径这里的/test是一个相对路径。它需要被拼接到某个“基础路径”后面才能形成完整的URL。那么问题来了这个“基础路径”是谁很多人会误以为是FeignClient注解里的url。逻辑上好像没错但Feign的实际行为需要更精确的理解。2.3 路径拼接的“潜规则”一个容易踩坑的细节Feign在构造最终请求URL时遵循一套拼接规则。我把它拆解成三步第一步确定“服务基础路径”。这个来自FeignClient的url属性如果用了服务发现则是从注册中心获取的地址服务本身的context-path。在我们的例子里就是http://localhost:8080/category。第二步确定“接口方法路径”。这个来自方法上的映射注解比如GetMapping(/test)里的/test。第三步拼接。注意Feign是简单地将“接口方法路径”追加到“服务基础路径”的末尾。它不会智能地判断url末尾是否已经有斜杠/或者方法路径开头是否有斜杠。它就是做字符串拼接。让我们回头看看异常日志里的URLhttp://localhost:8080/category/test/test。服务基础路径http://localhost:8080/category接口方法路径/test简单拼接http://localhost:8080/category/testhttp://localhost:8080/category/test哎不对啊按这个算法应该是/category/test怎么日志里是/category/test/test多了一个test坑就在这里我见过很多朋友包括我团队里的新人会这样写Feign接口FeignClient(url http://localhost:8080/category, name categoryService) public interface CategoryService { GetMapping(/test) String test(URI uri); // 注意这里有个URI参数 }然后在调用的时候像使用RestTemplate一样传入一个完整的URIURI uri new URI(http://localhost:8080/category/test); String result categoryService.test(uri);心里想的是“我把完整地址都传给你了你GetMapping里的路径应该用不上了吧” 大错特错Feign会忽略你传入的URI对象中用于构建最终请求的路径部分吗不会实际上对于FeignClient中指定了url的情况你方法参数里的URI或Url对象Feign通常只用来覆盖主机名、端口和协议或者在一些特定配置下用于动态URL。而方法注解上的路径依然会被拼接到FeignClient的url之后。所以在这个最经典的错误案例中实际发生的拼接是FeignClient.url:http://localhost:8080/categoryGetMapping:/test传入的URI参数:http://localhost:8080/category/test(这个地址里的路径/category/test可能被整体当作一个路径段或者在某些情况下与前面的路径发生重复拼接导致最终路径错乱变成/category/test/test)。真相就是FeignClient的url和方法上的GetMapping路径是叠加关系而不是替代关系。你想着传一个URI去指定完整路径但Feign的机制却可能给你做了“加法”导致了路径重复。这是我们排查404时第一个要检查的重灾区。3. 实战排查手册从日志到代码一步步揪出404元凶知道了原理排查就有了方向。下次再看到FeignException$NotFound别慌按我下面这个步骤来像侦探破案一样一步步缩小范围绝大多数问题都能快速定位。3.1 第一步紧盯异常日志解码错误信息Feign的异常信息其实非常友好它把关键线索都告诉你了。我们再看一遍feign.FeignException$NotFound: [404] during [GET] to [http://localhost:8080/category/test/test][404]: HTTP状态码明确告诉你服务器返回了“未找到”。这说明请求确实发出去了并且到达了某个服务不一定是目标服务但那个服务说“你要的东西我这儿没有”。during [GET]: 请求方法是GET。to [http://localhost:8080/category/test/test]:这是黄金线索这是Feign最终尝试请求的完整URL。你的首要任务就是仔细审视这个URL。排查动作把这个URL复制出来。手动在浏览器或者用Postman、curl等工具直接访问这个URL。观察结果如果也返回404恭喜问题大概率不在网络、服务发现等复杂环节就是路径拼错了。你的目标服务category-service上根本没有这个接口/category/test/test。你需要对比这个URL和你期望的URLhttp://localhost:8080/category/test。如果返回正常那问题更诡异了说明Feign构造的请求可能和直接访问的请求有细微差别比如Header、Body等但这种情况相对较少我们聚焦在路径问题上。3.2 第二步对照检查三处路径定义是否一致路径拼错无非是定义这些路径的地方出了偏差。你需要像一个校对员一样核对以下三个地方服务提供方Provider的Controller路径检查RequestMapping注解在类上的值。比如RequestMapping(/category)。检查具体方法上的GetMapping等注解的值。比如GetMapping(/test)。计算期望的完整路径类路径 方法路径 /category/test。确保这个路径是你能通过工具直接访问成功的。服务消费方Consumer的FeignClient接口路径检查FeignClient注解的url属性。确认它指向的是服务的基础地址而不是完整的方法地址。比如应该是http://localhost:8080或者http://localhost:8080/如果服务有server.servlet.context-path还要加上而不是http://localhost:8080/category。这是一个超级常见的错误很多人会把Controller上的路径也写到url里。检查方法上的GetMapping等注解的值。它应该等于服务提供方Controller方法上的路径即/test而不是包含Controller类路径的完整路径。全局配置路径如果有检查服务提供方的application.yml中是否有server.servlet.context-path配置。例如context-path: /api那么所有接口的访问路径前都会加上/api。检查服务消费方是否在FeignClient的url或配置中需要显式地加上这个context-path。一个正确的对照案例服务提供方8080端口# application.yml server: port: 8080 servlet: context-path: /api # 全局上下文路径RestController RequestMapping(/category) // 类路径 public class CategoryController { GetMapping(/test) // 方法路径 public String test() { ... } }该接口的真实完整访问路径是http://localhost:8080/api/category/test服务消费方FeignClient正确定义// 正确url指向服务地址全局context-path FeignClient(url http://localhost:8080/api, name categoryService) public interface CategoryService { // 方法路径对应Controller的方法路径 GetMapping(/category/test) String test(); }拼接过程http://localhost:8080/api(url) /category/test(GetMapping) http://localhost:8080/api/category/test。完美匹配3.3 第三步开启Feign详细日志让请求过程“裸奔”如果上面两步还找不到问题那就需要更强大的工具——Feign的完整日志。默认情况下Feign的日志级别是NONE不输出任何细节。我们需要把它打开。操作步骤在消费服务的application.yml中配置Feign客户端的日志级别为FULL。FULL级别会记录请求和响应的头部、正文和元数据信息最全。logging: level: # 你的FeignClient接口的全限定名 com.yourcompany.order.service.CategoryService: DEBUG或者如果你想为所有Feign客户端开启logging: level: feign.Client: DEBUG # 或者使用更通用的 org.springframework.cloud.openfeign: DEBUG重启服务再次触发Feign调用。查看控制台日志你会看到类似这样的详细输出[CategoryService#test] --- GET http://localhost:8080/api/category/test HTTP/1.1 [CategoryService#test] --- END HTTP (0-byte body) [CategoryService#test] --- HTTP/1.1 404 Not Found (15ms) [CategoryService#test] connection: keep-alive [CategoryService#test] content-type: application/json [CategoryService#test] date: Wed, 01 Jan 2025 12:00:00 GMT [CategoryService#test] transfer-encoding: chunked [CategoryService#test] [CategoryService#test] {timestamp:2025-01-01T12:00:00.00000:00,status:404,error:Not Found,path:/api/category/test} [CategoryService#test] --- END HTTP (136-byte body)从--- GET这一行你可以100%确认Feign发出的请求URL到底是什么。把它和你期望的URL、服务提供方真实的接口URL进行精确比对任何差异都无所遁形。是/api漏了还是/category重复了一眼就能看出来。4. 解决方案汇总对症下药根治路径拼接问题排查出问题根源解决起来就有的放矢了。下面我针对几种常见的路径错误场景给出具体的解决方案。4.1 场景一FeignClient的url包含了Controller路径这是最经典的错误也就是我们开篇案例的情况。错误示例// 服务提供方Controller路径是 /category FeignClient(url http://localhost:8080/category, name categoryService) // url里包含了/category public interface CategoryService { GetMapping(/test) // 这里又定义了一次路径 String test(); }结果Feign拼接出http://localhost:8080/category/test而服务提供方的真实路径可能只是/test如果url被误当作完整基础路径或者拼接重复。解决方案 将FeignClient的url修正为服务的基础地址IP:端口或者基础地址全局上下文路径。// 方案A如果服务提供方没有配置context-path FeignClient(url http://localhost:8080, name categoryService) public interface CategoryService { GetMapping(/category/test) // 这里需要写上完整的、相对于服务根路径的接口路径 String test(); } // 方案B如果服务提供方配置了 server.servlet.context-path/api FeignClient(url http://localhost:8080/api, name categoryService) public interface CategoryService { GetMapping(/category/test) // 同样这里是从 /api 之后的路径开始 String test(); }核心原则FeignClient的url属性应该指向服务实例的根地址。接口方法上的GetMapping等注解的路径应该从该根地址之后开始算起并且需要包含服务提供方Controller上定义的所有路径片段。4.2 场景二使用RequestMapping而非GetMapping等且路径定义不统一有些同学喜欢在Feign接口方法上用RequestMapping因为它可以指定method属性看起来更灵活。但这可能带来混淆。错误示例// 服务提供方 RestController RequestMapping(/api/v1) public class MyController { GetMapping(/users) public ListUser getUsers() { ... } } // 服务消费方FeignClient FeignClient(url http://localhost:8080) public interface UserService { RequestMapping(value /users, method RequestMethod.GET) // 路径只写了/users ListUser getUsers(); }结果Feign请求的URL是http://localhost:8080/users但实际接口在http://localhost:8080/api/v1/users导致404。解决方案 保持Feign接口方法与目标Controller方法的完整路径一致性。FeignClient(url http://localhost:8080) public interface UserService { // 必须包含Controller类上的路径 /api/v1 RequestMapping(value /api/v1/users, method RequestMethod.GET) ListUser getUsers(); // 或者更推荐使用专用的注解更清晰 GetMapping(/api/v1/users) ListUser getUsers(); }建议在Feign接口中尽量使用GetMapping、PostMapping等专用注解而不是通用的RequestMapping这样可读性更好也能减少因忘记指定method而导致的错误。4.3 场景三服务提供方使用了server.servlet.context-path这是微服务中常见的配置用于为所有接口添加统一前缀。如果消费方不知道或不处理这个前缀必然404。解决方案硬编码到url中不推荐如上文方案B所示将context-path直接写入FeignClient的url。缺点是不够灵活如果提供方的context-path改了所有消费方都要改。通过配置中心管理推荐将服务的基础地址包括context-path作为配置项。例如在Nacos配置中心中为category-service定义一个配置项service.url: http://localhost:8080/api然后在FeignClient中通过${}引用。FeignClient(url ${feign.client.category-service.url}, name categoryService) public interface CategoryService { GetMapping(/category/test) String test(); }# application.yml feign: client: category-service: url: http://localhost:8080/api # 这里包含了context-path使用服务发现并统一context-path最佳实践如果使用了Eureka/NacosFeignClient通常只写name不写url。此时context-path的问题需要确保服务提供方注册到注册中心时其元数据或实例地址是包含context-path的或者约定所有服务使用相同的context-path如/api这样消费方只需关心服务名和接口相对路径。4.4 场景四路径中的斜杠/处理不当路径拼接时开头和结尾的斜杠容易让人困惑。示例与建议FeignClient(url http://host:port/)(末尾有/)GetMapping(test)(开头没有/)Feign通常会做规范化处理但为了清晰和避免意外建议遵循一个固定风格在FeignClient的url中结尾不要加斜杠。例如url http://localhost:8080/api在方法映射注解的路径中开头总是加斜杠。例如GetMapping(/category/test)这样拼接起来就是http://localhost:8080/api/category/testhttp://localhost:8080/api/category/test非常清晰。5. 进阶避坑与最佳实践解决了基本的路径拼接问题我们再来看看一些更隐蔽的坑和如何建立好的习惯从源头上减少404的发生。5.1 警惕Fallback与路径配置的联动问题如果你为Feign客户端配置了Fallback类服务降级需要注意Fallback类本身不会执行Feign的路径拼接逻辑。Fallback类只是一个普通的Spring Bean它实现Feign接口在调用失败时返回预设值。但是定义Fallback时Feign接口的路径配置依然必须正确否则连正常的远程调用都会失败直接触发Fallback让你误以为服务不稳定而实际上是配置错误。5.2 使用PathVariable、RequestParam时的路径匹配当接口路径包含路径变量或查询参数时更要小心。// 服务提供方 GetMapping(/users/{id}) public User getUser(PathVariable Long id) { ... } // 消费方FeignClient正确定义 FeignClient(url http://localhost:8080) public interface UserService { GetMapping(/users/{id}) // 路径模板必须完全一致 User getUser(PathVariable(id) Long userId); // PathVariable的value要对应 }关键点Feign接口方法上的GetMapping(/users/{id})中的{id}必须和提供方Controller中的定义一模一样。PathVariable注解的value属性或参数名也必须匹配这个占位符名称。任何不匹配都可能导致路径无法映射从而404。5.3 推荐实践建立清晰的接口契约定义独立的API模块创建一个独立的Maven/Gradle模块如xxx-api将所有的服务API接口包括DTO定义在其中。服务提供方实现这个接口服务消费方依赖这个模块并直接使用其中的FeignClient接口。这样可以强制保证双方路径定义的一致性从物理上杜绝拼写错误或路径不一致。// 在 api 模块中定义 FeignClient(name category-service) // 使用服务发现name对应服务名 public interface CategoryServiceApi { GetMapping(/api/category/test) Response test(); } // 服务提供方实现这个接口Controller实现该接口 // 服务消费方直接注入 CategoryServiceApi 使用统一使用服务发现尽量使用FeignClient(name service-name)而不是硬编码url。让注册中心来管理服务的网络位置这样即使服务端口或IP变了消费方也无需修改代码。路径的关注点就集中在context-path和Controller路径上。编写集成测试为Feign客户端编写简单的集成测试在测试环境中实际发起调用验证是否能收到正常响应。这是发现配置问题最有效的手段之一。善用Spring Cloud OpenFeign的配置在application.yml中可以对所有Feign客户端进行全局配置比如连接超时、重试策略、日志级别等。将日志级别默认设为BASIC或HEADERS可以在不输出大量Body信息的情况下看到请求的基本信息和响应状态便于日常监控。5.4 一个完整的、健壮的配置示例假设我们有一个用户服务user-service配置了context-path/api注册到Nacos服务名为user-service。服务提供方 (user-service):# application.yml server: port: 8081 servlet: context-path: /api spring: application: name: user-service cloud: nacos: discovery: server-addr: localhost:8848// Controller RestController RequestMapping(/v1/users) public class UserController { GetMapping(/{userId}) public UserDTO getUser(PathVariable String userId) { // ... 业务逻辑 } } // 真实接口路径http://localhost:8081/api/v1/users/{userId}服务消费方 (order-service):# application.yml spring: application: name: order-service cloud: nacos: discovery: server-addr: localhost:8848 logging: level: com.example.order.feign.UserServiceApi: DEBUG # 按需开启Feign日志// 在独立的api模块中或消费方内部定义 // 使用服务发现name必须与提供方的spring.application.name一致 FeignClient(name user-service) public interface UserServiceApi { // 路径 context-path Controller类路径 方法路径 GetMapping(/api/v1/users/{userId}) UserDTO getUser(PathVariable(userId) String id); }调用RestController public class OrderController { Autowired private UserServiceApi userServiceApi; // 直接注入 GetMapping(/order/{orderId}) public OrderDetail getOrder(PathVariable String orderId) { // Feign会自动从Nacos找到user-service的实例并拼接路径发起调用 UserDTO user userServiceApi.getUser(123); // ... 业务逻辑 } }经过这样一番从现象到本质从排查到解决的梳理相信你再遇到Feign 404问题尤其是路径问题应该能从容应对了。记住关键就是仔细核对日志中的最终URL并理解Feign逐级拼接路径的规则。微服务开发中这类接口契约的细节就是质量的基石多花一分钟检查能省下后面一小时的调试时间。