Spring Cloud OpenFeign集成Consul调用异常：路径需以/v1/开头问题排查

问题现象 #

编写Spring Cloud与Consul集成Demo时，通过OpenFeign从consul-client调用consul-server出现404异常，报错提示：

Invalid URL path: if attempting to use the HTTP API, ensure the path starts with '/v1/'

排查发现请求实际指向Consul Agent（8500端口）而非业务服务（8080端口）。切换至Nacos注册中心时Feign调用正常，Consul以consul agent -dev模式启动。

服务端配置（consul-server） #

application.yml #

server:
  port: 8080

spring:
  application:
    name: consul-server
  cloud:
    consul:
      discovery:
        service-name: ${spring.application.name}
        hostname: localhost
        port: 8500
        heartbeat:
          enabled: true

控制器代码 #

@RestController
@RequestMapping("/check")
public class CheckFeignController {

    @GetMapping("/demo")
    public String demo() {
        return "demo";
    }
}

客户端配置（consul-client） #

application.yml #

server:
  port: 9090

spring:
  application:
    name: consul-client
  cloud:
    consul:
      discovery:
        service-name: ${spring.application.name}
        hostname: localhost
        port: 8500
        heartbeat:
          enabled: true

Feign接口 #

@FeignClient(name = "consul-server", path = "/check")
public interface CheckFeign {

    @GetMapping("/demo")
    String demo();
}

控制器与启动类 #

@RestController
@RequestMapping("/demo")
public class DemoController {

    @Resource
    private CheckFeign checkFeign;

    @GetMapping("/hello")
    public String hello() {
        return checkFeign.demo();
    }
}

@Slf4j
@EnableFeignClients
@SpringBootApplication
public class ClientApplication {
    public static void main(String[] args) {
        SpringApplication.run(ClientApplication.class, args);
        log.info("ClientApplication start success");
    }
}

依赖配置 #

子项目Maven依赖 #

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--consul-->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-consul-discovery</artifactId>
</dependency>
<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>org.projectlombok</groupId>
    <artifactId>lombok</artifactId>
</dependency>

父项目Maven pom #

<groupId>com.bt.game</groupId>
<artifactId>cloud-demo</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>pom</packaging>
<modules>
    <module>consul-server</module>
    <module>consul-client</module>
</modules>

<properties>
    <maven.compiler.source>21</maven.compiler.source>
    <maven.compiler.target>21</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring-cloud.version>2023.0.3</spring-cloud.version>
    <spring-cloud-alibaba.version>2023.0.1.2</spring-cloud-alibaba.version>
    <spring-boot-starter-parent.version>3.3.6</spring-boot-starter-parent.version>
    <hutool.version>5.8.33</hutool.version>
    <lombok.version>1.18.30</lombok.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-parent</artifactId>
            <version>${spring-boot-starter-parent.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba.cloud</groupId>
            <artifactId>spring-cloud-alibaba-dependencies</artifactId>
            <version>${spring-cloud-alibaba.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>cn.hutool</groupId>
            <artifactId>hutool-all</artifactId>
            <version>${hutool.version}</version>
        </dependency>
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>${lombok.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

错误日志 #

2025-01-06T14:55:34.164+08:00 ERROR 4488 --- [consul-client] [nio-9090-exec-2] o.a.c.c.C.[.[.[/].[dispatcherServlet]    : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: feign.FeignException$NotFound: [404 Not Found] during [GET] to [http://consul-server/check/demo] [CheckFeign#demo()]: [Invalid URL path: if attempting to use the HTTP API, ensure the path starts with '/v1/'
]] with root cause

feign.FeignException$NotFound: [404 Not Found] during [GET] to [http://consul-server/check/demo] [CheckFeign#demo()]: [Invalid URL path: if attempting to use the HTTP API, ensure the path starts with '/v1/'
]
    at feign.FeignException.clientErrorStatus(FeignException.java:228) ~[feign-core-13.3.jar:na]
    ...（省略其余栈信息）

解决建议 #

• 修正服务注册端口配置：当前服务端和客户端的spring.cloud.consul.discovery.port都配置为Consul Agent的8500端口，导致服务注册时错误地将业务服务端口设置为8500，Feign调用直接请求Consul Agent而非业务服务。需修改为业务服务自身端口：

  • consul-server的spring.cloud.consul.discovery.port改为8080
  • consul-client的spring.cloud.consul.discovery.port改为9090
    或直接删除该配置，Spring Cloud Consul会自动使用server.port的值作为服务注册端口。

• 验证服务注册状态：启动服务后访问Consul控制台（http://localhost:8500/ui），确认consul-server服务的端口为8080，确保注册信息正确。

• 确认Loadbalancer依赖生效：Spring Cloud 2020+版本默认移除Ribbon，需确保spring-cloud-starter-loadbalancer依赖正确引入，否则Feign无法正确解析服务名到实际业务地址。

内容的提问来源于stack exchange，提问作者Baozi