Multi encoder

[trumpetinc]

Continuing work started in: #3485

Co-authored-by: trumpetinc 6618744+trumpetinc@users.noreply.github.com

Note

Target branch: 14.x

Important

Please squash and merge this PR if it's approved.

Important

Please add Co-authored-by: trumpetinc <6618744+trumpetinc@users.noreply.github.com> footer to the commit message if this PR is approved.

Summary

This PR introduces multi-encoder support in Feign, allowing users to register multiple encoders that are automatically selected at request time. The Encoder.encode() method now returns boolean (true if the encoder handled the object, false otherwise), and a new Encoder.of() factory combines encoders into a DelegatingEncoder.

Motivation

Previously, Feign only supported a single Encoder registered via Feign.builder().encoder(...). For APIs that mix different content types (JSON, XML, form data, etc.), users had to manually wrap encoders (e.g., new FormEncoder(new JacksonEncoder())). This was brittle and didn't scale well.

Changes

New API

• Encoder.encode() now returns boolean — return true when encoding succeeds, false if the encoder does not handle the request. This replaces the need for a separate canEncode() method.

• Encoder.of(Encoder...) / Encoder.of(List<Encoder>) — factory method that creates a DelegatingEncoder, which tries each delegate's encode() in order and uses the first one that returns true. Throws EncodeException if no encoder succeeds.

• DelegatingEncoder — a composite encoder that delegates to a list of encoders, using the first one whose encode() returns true.

• Util.isJsonContentType(RequestTemplate) / Util.isXmlContentType(RequestTemplate) — utility methods that check the Content-Type header against JSON (application/json, application/ld+json, etc.) and XML (text/xml, application/xml, etc.) patterns.

Encoder Updates

All built-in encoders now return boolean from encode() and gate on Content-Type where applicable:

Encoder	Strategy
DefaultEncoder	Type-based: accepts String, byte[], File, Path, InputStream, Request.Body, and null
FormEncoder	Content-Type-based: accepts multipart/form-data and application/x-www-form-urlencoded
GraphqlEncoder	Metadata-based: accepts requests matched by GraphqlContract; delegates to wrapped encoder otherwise
MeteredEncoder (all variants)	Delegates to the wrapped encoder
All JSON encoders	Content-Type check via Util.isJsonContentType(template)
All XML encoders	Content-Type check via Util.isXmlContentType(template)

Example Usage

Before:

// Only one encoder — had to manually wrap
Feign.builder()
    .encoder(new FormEncoder(new JacksonEncoder()))
    .target(MyApi.class, "https://api.example.com");

After:

Feign.builder()
    .encoder(Encoder.of(
        new FormEncoder(),          // handles multipart/form-urlencoded by Content-Type
        new JacksonEncoder()       // handles JSON encoding
    ))
    .target(MyApi.class, "https://api.example.com");

Breaking Changes

Breaking changes are documented in MIGRATION-v14.md (sections 14–17):

1. Encoder.encode() now returns boolean instead of void. All custom Encoder implementations must update the return type and return true on success or false when the encoder does not handle the request.
2. Single encoder usage is unchanged — Feign.builder().encoder(new JacksonEncoder()) still works.

Files Changed

• New: api/src/main/java/feign/codec/DelegatingEncoder.java
• Modified: Encoder.java, Util.java, Feign.java, AsyncFeign.java, HystrixFeign.java, VertxFeign.java, DefaultEncoder.java, FormEncoder.java, GraphqlEncoder.java, MeteredEncoder.java (×3), JAXBEncoder.java (×2), SOAPEncoder.java (×2), JacksonEncoder.java, Jackson3Encoder.java, GsonEncoder.java, MoshiEncoder.java, Fastjson2Encoder.java, JacksonJrEncoder.java, JacksonJaxbJsonEncoder.java
• Tests: DelegatingEncoderTest.java, all JSON/XML encoder test files, and various integration tests
• Documentation: MIGRATION-v14.md, CHANGELOG.md

[yvasyliev]

Could you please set target branch = 14.x?

[trumpetinc]

Could you please set target branch = 14.x?

Yes - sorry about missing that.