Feign Client表单请求时final字段未序列化致请求失败

问题描述 #

我基于io.github.openfeign:feign-core:13.1和Java 21编写了PerTenantTokenClient接口，用于发送Content-Type: application/x-www-form-urlencoded的POST请求获取认证令牌。请求需要携带grant_type、client_id、client_secret三个参数，我将这些参数封装在带有@RequiredArgsConstructor注解的AuthFormData类中，所有字段均声明为final。

调用接口时返回400 Bad Request，提示缺少grant_type参数。但移除字段的final修饰符后请求成功；换成Java Record（成员隐式为final）时，同样请求失败。想确认这是Feign的Bug还是代码问题？

原因分析 #

这是Feign 13.x版本的已知限制，并非你的代码问题：

• Feign默认的FormEncoder处理表单参数时依赖JavaBean规范，要求字段支持反射访问（非final）或有对应的setter方法；
• 当字段为final时，即使有构造函数，FormEncoder无法通过反射读取字段值来生成表单参数；
• Java Record的成员是隐式final的，同样不符合FormEncoder的序列化要求，导致参数无法被正确解析。

解决方案 #

1. 升级Feign版本（推荐） #

Feign 14.0及以上版本已经修复了该问题，支持直接处理final字段和Java Record作为表单参数。只需将依赖版本升级到14.x或更高即可。

2. 自定义FormEncoder（兼容旧版本） #

如果无法升级版本，可以自定义编码器，支持解析final字段和Record类型：

public class CustomFormEncoder extends FormEncoder {
    public CustomFormEncoder(Encoder delegate) {
        super(delegate);
        this.addEncoder(new RecordFormEncoder());
        this.addEncoder(new FinalFieldFormEncoder());
    }

    private static class RecordFormEncoder implements Encoder {
        @Override
        public void encode(Object object, Type bodyType, RequestTemplate template) throws EncodeException {
            if (object instanceof Record) {
                Map<String, Object> formData = new LinkedHashMap<>();
                for (Field field : object.getClass().getDeclaredFields()) {
                    field.setAccessible(true);
                    try {
                        formData.put(field.getName(), field.get(object));
                    } catch (IllegalAccessException e) {
                        throw new EncodeException("Failed to access record field", e);
                    }
                }
                super.encode(formData, MAP_STRING_WILDCARD, template);
            }
        }
    }

    private static class FinalFieldFormEncoder implements Encoder {
        @Override
        public void encode(Object object, Type bodyType, RequestTemplate template) throws EncodeException {
            if (!(object instanceof Record)) {
                Map<String, Object> formData = new LinkedHashMap<>();
                for (Field field : object.getClass().getDeclaredFields()) {
                    if (Modifier.isFinal(field.getModifiers())) {
                        field.setAccessible(true);
                        try {
                            formData.put(field.getName(), field.get(object));
                        } catch (IllegalAccessException e) {
                            throw new EncodeException("Failed to access final field", e);
                        }
                    }
                }
                if (!formData.isEmpty()) {
                    super.encode(formData, MAP_STRING_WILDCARD, template);
                }
            }
        }
    }
}

然后在Feign配置类中注入自定义编码器：

@Configuration
public class FeignConfig {
    @Bean
    public Encoder feignEncoder() {
        return new CustomFormEncoder(new DefaultEncoder());
    }
}

3. 改用Map传递参数 #

如果不想修改编码器或升级版本，可以直接使用Map<String, String>传递表单参数：

@PostMapping(value = "/token", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
ResponseEntity<TokenResponse> getToken(@RequestBody Map<String, String> formData);

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