openfeign 自定义注解需实现 contract 接口并重写 parseandvalidatemetadata 方法，解析如 @apiversion 等自定义注解，注入请求头或参数绑定逻辑，注册时替换默认 contract 并委托父类处理原生注解。
OpenFeign 的契约（Contract）负责解析接口上的注解，将其转换为可执行的 HTTP 请求逻辑。要自定义注解解析规则，核心是实现并替换默认的 Contract，比如继承 Default.Contract 或直接实现 Contract 接口，在其中重写 parseAndValidateMetadata 方法来处理你自己的注解。
定义自定义注解
先创建一个运行时保留的注解，用于标记方法级或参数级语义：
// 例如：@ApiVersion 控制请求头中的版本信息
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.METHOD, ElementType.PARAMETER})
public @interface ApiVersion {
String value() default "v1";
}
扩展 Contract 解析逻辑
继承 Default.Contract（推荐），覆盖关键方法，注入对自定义注解的支持：
- 在
parseAndValidateMetadata中遍历方法和参数的注解，识别@ApiVersion - 若出现在方法上，可将其作为全局请求头（如
X-API-Version）添加到metadata.template().headers() - 若出现在参数上（带
@Param或自定义绑定逻辑），可将其映射为 header、query 或 body 字段，需配合自定义Encoder或RequestInterceptor - 注意调用
super.parseAndValidateMetadata(...)保留对@RequestLine、@Headers等原生注解的支持
注册自定义 Contract 到 Feign.Builder
构建 Feign 客户端时显式传入你的契约实现：
Feign.builder()
.contract(new MyCustomContract()) // 替换默认 Contract
.encoder(new JacksonEncoder())
.decoder(new JacksonDecoder())
.target(MyApi.class, "https://api.example.com");
Spring Cloud OpenFeign 用户可在配置类中通过 @Bean 提供 Contract，它会被自动生效：
@Bean
public Contract feignContract() {
return new MyCustomContract();
}
注意事项与常见陷阱
- 不要忽略原有注解解析 —— 必须委托给父类或手动补全
@RequestLine、@QueryMap等标准行为 - 方法级注解影响整个请求模板；参数级注解需结合
MethodMetadata的parameterAnnotationClasses和parameterNames正确绑定位置 - 若需动态 header（如 token + version 组合），更适合用
RequestInterceptor，而非在 Contract 中硬编码 - 自定义注解不参与 Spring MVC 映射，仅作用于 Feign 客户端侧，服务端需自行解析对应 header/query
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
