文章目录OpenFeign 使用指南一、OpenFeign 是什么二、依赖2.1 版本管理2.2 调用方Consumer2.3 接口模块*-api2.4 提供方Provider2.5 依赖关系三、启用 Feign四、接口定义4.1 基本写法4.2 FeignClient 常用属性4.3 参数注解4.4 契约对齐五、接口模块打包5.1 为什么抽成独立 jar5.2 模块结构5.3 打包 api 模块5.4 调用方引入 api jar5.5 构建顺序六、扫描 jar 包中的 Feign 接口6.1 默认扫描范围6.2 现象6.3 解决显式指定扫描范围6.4 三种方式对比6.5 本地接口继承可选七、常见问题7.1 No qualifying bean of type XxxApi7.2 LoadBalancer does not have available server7.3 404 Not Found7.4 改了 api jar 但没生效7.5 同一服务多个 Feign 接口 Bean 冲突八、总结OpenFeign 使用指南Spring Cloud OpenFeign将 HTTP 远程调用抽象为 Java 接口 注解的声明式客户端。一、OpenFeign 是什么OpenFeign 是 Spring Cloud 对 Feign 的封装。Feign 在运行时根据接口定义生成 HTTP 请求调用方只需注入接口、调用方法无需手写 URL。对比项RestTemplate / RestClientOpenFeign调用方式命令式手写 URL声明式接口方法契约管理分散在各处可集中在*-api模块负载均衡需LoadBalanced自动调用LoadBalanced适合场景少量临时调用多接口、多服务、长期维护命令式 vs 声明式// RestClient每次拼 URLUserDTOuserrestClient.get().uri(http://user-service/user/{id},id).retrieve().body(UserDTO.class);// OpenFeign像调本地方法AutowiredUserApiuserApi;UserDTOuseruserApi.getById(id);二、依赖2.1 版本管理propertiesspring-cloud.version2025.1.2/spring-cloud.version/propertiesdependencyManagementdependenciesdependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-dependencies/artifactIdversion${spring-cloud.version}/versiontypepom/typescopeimport/scope/dependency/dependencies/dependencyManagement2.2 调用方Consumer调用方需要 Feign 运行时 负载均衡解析服务名!-- OpenFeign 运行时 --dependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-starter-openfeign/artifactId/dependency!-- 客户端负载均衡必须否则无法解析 http://服务名/... --dependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-starter-loadbalancer/artifactId/dependency若使用注册中心Nacos / Eureka 等还需引入对应的 discovery starter。2.3 接口模块*-api独立 jar 模块中定义FeignClient接口和共享 DTO引入 OpenFeign 仅为使用注解artifactIduser-api/artifactIdpackagingjar/packagingdependenciesdependencygroupIdorg.springframework.cloud/groupIdartifactIdspring-cloud-starter-openfeign/artifactId/dependency/dependenciesapi 模块不要加spring-boot-maven-plugin的 repackage它只是普通 jar。2.4 提供方Provider提供方不需要OpenFeign 运行时。若 api 模块中有共享 DTO提供方可引 api jar 复用 DTO保证入参出参与 Feign 接口一致。2.5 依赖关系consumer-service调用方 ├── spring-cloud-starter-openfeign ├── spring-cloud-starter-loadbalancer ├── discovery-starter可选配合注册中心 └── user-api.jar provider-service提供方 └── user-api.jar可选复用 DTO user-api接口模块 └── spring-cloud-starter-openfeign仅注解三、启用 Feign在调用方启动类上加EnableFeignClientsSpringBootApplicationEnableFeignClientspublicclassConsumerApplication{publicstaticvoidmain(String[]args){SpringApplication.run(ConsumerApplication.class,args);}}Spring 会为每个FeignClient接口生成动态代理 Bean可直接Autowired注入。四、接口定义4.1 基本写法Feign 接口的注解与 Spring MVC Controller完全一致Spring 根据注解拼装 HTTP 请求FeignClient(valueuser-service,path/user)publicinterfaceUserApi{GetMapping(/{id})UserDTOgetById(PathVariable(id)Longid);GetMapping(/list)ListUserDTOlist(RequestParam(name)Stringname);GetMapping(/search)ListUserDTOsearch(SpringQueryMapUserQueryquery);PostMapping(/create)UserDTOcreate(RequestBodyUserDTOuser);}4.2 FeignClient 常用属性属性说明value/name目标服务名对应注册中心的spring.application.namepath统一 URL 前缀等价于 Controller 的RequestMappingurl硬编码地址不走负载均衡调试用生产不推荐contextId同一服务多个 Feign 接口时区分 Bean 名称fallback/fallbackFactory降级处理类4.3 参数注解注解对应 HTTP示例PathVariable路径变量/user/123RequestParamQuery 参数/user/list?nameTomSpringQueryMap对象展开为 Query/user/search?id1nameTomRequestBodyJSON 请求体POST BodyRequestHeader请求头Authorization: Bearer xxx4.4 契约对齐Feign 接口定义的是 HTTP 契约提供方 Controller 必须路径、HTTP 方法、参数注解、返回值一致// Feign 接口api 模块FeignClient(valueuser-service,path/user)publicinterfaceUserApi{GetMapping(/{id})UserDTOgetById(PathVariable(id)Longid);}// 提供方 ControllerRestControllerRequestMapping(/user)publicclassUserController{GetMapping(/{id})publicUserDTOgetById(PathVariable(id)Longid){...}}五、接口模块打包5.1 为什么抽成独立 jar好处说明契约复用调用方、提供方共用同一套接口和 DTO版本管理api jar 独立发版接口变更可追溯编译约束改接口 → 调用方编译期即可感知5.2 模块结构project/ ├── user-api/ ← Feign 接口 DTO普通 jar ├── user-service/ ← 提供方 └── consumer-service/ ← 调用方引入 user-api jar5.3 打包 api 模块mvn cleaninstall-pluser-api产物user-api/target/user-api-1.0-SNAPSHOT.jarjar 内只有接口 class 和 DTO class不可执行。5.4 调用方引入 api jardependencygroupIdcom.example/groupIdartifactIduser-api/artifactIdversion1.0-SNAPSHOT/version/dependencySpring Boot 打包时api jar 会被打进 fat jar 的BOOT-INF/lib/目录。5.5 构建顺序api 模块必须先install到本地仓库或私服调用方才能解析依赖# 只改了 api 模块mvn cleaninstall-pluser-api mvn clean package-plconsumer-service# 根目录一键构建Reactor 自动按依赖顺序mvn cleaninstallapi 模块不能打成 Spring Boot fat jar否则其他模块无法依赖其中的 class。六、扫描 jar 包中的 Feign 接口6.1 默认扫描范围EnableFeignClients默认扫描启动类所在包及其子包。启动类com.example.consumer.ConsumerApplication 默认扫描com.example.consumer.*若 Feign 接口在独立 jar 的其他包下如com.example.api.user默认扫不到。6.2 现象启动后注入 Feign 接口报错No qualifying bean of type com.example.api.user.UserApi6.3 解决显式指定扫描范围方式一basePackages推荐EnableFeignClients(basePackagescom.example.api)publicclassConsumerApplication{...}方式二basePackageClassesEnableFeignClients(basePackageClassesUserApi.class)publicclassConsumerApplication{...}以指定 class 所在包为根扫描该包及子包。方式三clientsEnableFeignClients(clients{UserApi.class,OrderApi.class})publicclassConsumerApplication{...}只注册列出的接口扫描范围最小。6.4 三种方式对比方式写法适用场景basePackagesbasePackages com.example.api多个 Feign 接口在同一包 / 包前缀下basePackageClassesbasePackageClasses UserApi.class精确锚定重构时编译期可感知clientsclients UserApi.class只启用个别接口basePackages指定的是Feign 接口所在的包名与 jar 物理位置无关——class 在 classpath 上即可被扫描。6.5 本地接口继承可选在调用方模块定义空继承接口用于锚定扫描// consumer-service 中publicinterfaceLocalUserApiextendsUserApi{}EnableFeignClients(basePackageClassesLocalUserApi.class)Spring 会扫描LocalUserApi及其父接口UserApi。不如basePackages直观一般不必使用。七、常见问题7.1 No qualifying bean of type ‘XxxApi’EnableFeignClients未扫描到接口。检查basePackages是否覆盖 Feign 接口所在包。7.2 LoadBalancer does not have available server缺少spring-cloud-starter-loadbalancer或注册中心中无对应服务实例。7.3 404 Not FoundFeign 接口的path、方法路径、HTTP 方法与提供方 Controller 不一致。7.4 改了 api jar 但没生效api 模块修改后未重新install调用方用的仍是旧 jarmvn cleaninstall-pluser-api7.5 同一服务多个 Feign 接口 Bean 冲突使用contextId区分FeignClient(valueuser-service,contextIduserReadApi,path/user)publicinterfaceUserReadApi{...}FeignClient(valueuser-service,contextIduserWriteApi,path/user)publicinterfaceUserWriteApi{...}八、总结主题要点本质声明式 HTTP 客户端接口 注解 → 自动生成请求调用方依赖openfeignloadbalancer discovery starterapi 模块普通 jar放FeignClient接口和 DTO先install再被引用接口写法注解与 Spring MVC 一致value 服务名path URL 前缀扫描 jar接口在外部 jar 时必须EnableFeignClients(basePackages ...)契约Feign 接口与提供方 Controller 路径、参数、返回值必须对齐