This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Codec

用户请求时RestClient会自动根据用户的 Headers 与 Entity 自动选择合适的Decoder或Encoder进行Decode或Encode。同时RestClient也支持用户在codec前后进行插入业务逻辑。

1: Encoder
2: Decoder

1 - Encoder

RestClient会自动根据用户的 Headers 与 Entity 等选择合适的Encoder进行Encode。其内置了下面这些Encoder：

Json
- jackson ：默认，自动通过SPI的方式注入到RestClient中
- fastjson ：需要引入fastjson依赖,并将FastJsonCodec添加到RestClient中
- gson ：需要引入gson依赖,并将GsonCodec添加到RestClient中
ProtoBuf ：需要引入ProtoBuf依赖,并将ProtoBufCodec添加到RestClient中
File ：自动通过SPI的方式注入到RestClient中
String ：自动通过SPI的方式注入到RestClient中
byte[] ：自动通过SPI的方式注入到RestClient中

除此之外RestClient也支持用户自定义Encoder。

使用Json Encoder

指定contentType为MediaType.APPLICATION_JSON，将自动使用Json Encoder来对Entity来进行Encode。示例如下：

final RestClient client = RestClient.ofDefault();
RestResponseBase response  = client.post("localhost:8080/aaa")
        .contentType(MediaType.APPLICATION_JSON)
        .entity(new Person("Bob","male"))
        .execute()
        .toCompletableFuture()
        .get();

Note

其中Json相关的序列化方式默认配置了日期格式为yyyy-MM-dd HH:mm:ss

使用ProtoBuf Encoder

Step1 : 引入ProtoBuf依赖

<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java</artifactId>
</dependency>

Step2 : 使用 ProtoBuf Encoder 进行编码

将ProtoBufCodec加入到RestClient中，指定contentType为ProtoBufCodec.PROTO_BUF，且Entity类型为com.google.protobuf.Message的子类时，将自动使用ProtoBuf Encoder来对Entity来进行Encode。示例如下：

//将ProtoBufCodec加入到RestClient中
final RestClient client = RestClient.create()
        .addEncoder(new ProtoBufCodec())
        .build();

RestResponseBase response  = client.post("localhost:8080/aaa")
        .contentType(ProtoBufCodec.PROTO_BUF)
        .entity(message)
        .execute()
        .toCompletableFuture()
        .get();

使用File Encoder

当Entity类型为File时，将自动使用File Encoder来对Entity来进行Encode。示例如下：

final RestClient client = RestClient.ofDefault();
RestResponseBase response  = client.post("localhost:8080/aaa")
        .entity(new File("tem"))
        .execute()
        .toCompletableFuture()
        .get();

使用String Encoder

当Entity类型为String时，将自动使用String Encoder来对Entity来进行Encode。示例如下：

final RestClient client = RestClient.ofDefault();
RestResponseBase response  = client.post("localhost:8080/aaa")
        .entity("string")
        .execute()
        .toCompletableFuture()
        .get();

使用byte[] Encoder

当Entity类型为byte[]时，将自动使用byte[] Encoder来对Entity来进行Encode。示例如下：

final RestClient client = RestClient.ofDefault();
RestResponseBase response = client.post("localhost:8080/aaa")
        .entity("bytes".getBytes())
        .execute()
        .toCompletableFuture()
        .get();

自定义Encoder

当RestClient内置的Encoder无法满足用户需求时，用户可以自定义Encoder，示例如下：

public class StringEncoder implements ByteEncoder {

    @Override
    public RequestContent<byte[]> doEncode(EncodeContext<byte[]> ctx) {
        if (MediaType.TEXT_PLAIN.isCompatibleWith(ctx.contentType())) {
            if (ctx.entity() != null) {
                return RequestContent.of(ctx.entity().toString());
            } else {
                return RequestContent.of("null");
            }
        }
        //该Encoder无法Encode这种类型，将Encode工作交给下一个Encoder
        return ctx.next();
    }
}

Tip

在RestClient中，同时存在多个Encoder，它们之间通过getOrder()方法返回值区分执行顺序，值越小，优先级越高。针对当前Encoder，分为两种情况：

当前Encoder可以Encode该请求: 直接返回Encode后的结果。
当前Encoder不可以Encode该请求：调用ctx.next()，将Encode工作交给下一个Encoder，如果RestClient中的所有Encoder都无法编码该请求，则RestClient将抛出CodecException异常。

配置Encoder

Builder

在构造RestClient时传入自定义的Encoder实例，如：

final RestClient client = RestClient.create()
        .addEncoder(ctx -> {
            //encode...
            return ctx.next();
        })
        .build();

SPI

普通SPI

RestClient支持通过SPI的方式加载Encoder接口的实现类，使用时只需要按照SPI的加载规则将自定义的Encoder放入指定的目录下即可。

EncoderFactory

如果用户自定义的Encoder对于不同RestClient的配置有不同的实现，则用户可以实现EncoderFactory接口，并按照SPI的加载规则将自定义的EncoderFactory放入指定的目录下即可。

public interface EncoderFactory {
    Collection<Encoder> encoders(RestClientOptions clientOptions);
}

在RestClient构建时将调用EncoderFactory.encoders(RestClientOptions clientOptions)，该方法返回的所有Encoder都将加入到构建好的RestClient中。

直接绑定Request

Encoder可以直接绑定Request，使用方式如下:

final RestResponseBase response = client.post(url)
        .entity(new File("aaa"))
        .encoder(ctx -> {
            //encode...
            return ctx.next();
        })
        .execute()
        .toCompletableFuture()
        .get();

Tip

当Request绑定了Encoder，该Client中设置的所有Encoder将对该请求失效。即：如果当前Encoder无法Encode该请求的Entity，则RestClient将会抛出CodecException异常。

执行时机

见请求处理完整流程中的Encoder。

EncodeAdvice

用户可以通过EncodeAdvice在Encode前后插入业务逻辑，来对要Encode的 Entity 或者 Encode后的RequestContent 进行修改替换等操作。

示例

public class EncodeAdviceImpl implements EncodeAdvice {
    @Override
    public RequestContent<?> aroundEncode(EncodeAdviceContext ctx) throws Exception {
        //...before encode
        RequestContent<?> requestContent = ctx.next();
        //...after encode
        return requestContent;
    }
}

Tip

多个EncodeAdvice之间通过getOrder()方法返回值区分执行顺序，值越小，优先级越高。

配置方式

Builder

在构造RestClient时传入自定义的EncodeAdvice实例，如：

final RestClient client = RestClient.create()
        .addEncodeAdvice(ctx -> {
            //...before encode
            RequestContent<?> requestContent = ctx.next();
            //...after encode
            return requestContent;
        })
        .build();

SPI

普通SPI

RestClient支持通过SPI的方式加载EncodeAdvice接口的实现类，使用时只需要按照SPI的加载规则将自定义的EncodeAdvice放入指定的目录下即可。

EncodeAdviceFactory

如果用户自定义的EncodeAdvice对于不同RestClient的配置有不同的实现，则用户可以实现EncodeAdviceFactory接口，并按照SPI的加载规则将自定义的EncodeAdviceFactory放入指定的目录下即可。

public interface EncodeAdviceFactory {
    Collection<EncodeAdvice> encodeAdvices(RestClientOptions clientOptions);
}

在RestClient构建时将调用EncodeAdviceFactory.encodeAdvices(RestClientOptions clientOptions)，该方法返回的所有EncodeAdvice都将加入到构建好的RestClient中。

执行时机

见请求处理完整流程中的EncodeAdvice。

2 - Decoder

RestClient会自动根据用户的 Headers 与期望Entity类型等选择合适的Decoder进行解码。RestClient内置了下面这些Decoder：

Json
- jackson ：默认，自动通过SPI的方式注入到RestClient中
- fastjson ：需要引入fastjson依赖,并将FastJsonCodec添加到RestClient中
- gson ：需要引入gson依赖,并将GsonCodec添加到RestClient中
ProtoBuf ：需要引入ProtoBuf依赖,并将ProtoBufCodec添加到RestClient中
String ：自动通过SPI的方式注入到RestClient中
byte[] ：自动通过SPI的方式注入到RestClient中

除此之外RestClient也支持用户自定义解码器。

使用Json Decoder

当Response的contentType为MediaType.APPLICATION_JSON，将自动使用Json Decoder来来进行Decode。

final RestClient client = RestClient.ofDefault();
RestResponseBase response  = client.get("localhost:8080/aaa")
        .execute()
        .toCompletableFuture()
        .get();

//当 response.contentType() == MediaType.APPLICATION_JSON 时将自动使用Json Decoder
Person person = response.bodyToEntity(Person.class);

Note

其中Json相关的序列化方式默认配置了日期格式为yyyy-MM-dd HH:mm:ss

使用ProtoBuf Decoder

Step1 : 引入ProtoBuf依赖

<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java</artifactId>
</dependency>

Step2 : 使用 ProtoBuf Decoder 进行解码

将ProtoBufCodec加入到RestClient中，当Response的contentType为ProtoBufCodec.PROTO_BUF，且response.bodyToEntity()传入的类型为com.google.protobuf.Message的子类时，将自动使用ProtoBuf Decoder来进行Decode。

//将ProtoBufCodec加入到RestClient中
final RestClient client = RestClient.create()
        .addDecoder(new ProtoBufCodec())
        .build();

RestResponseBase response = client.get("localhost:8080/aaa")
        .execute()
        .toCompletableFuture()
        .get();

//当 ProtoBufCodec.PROTO_BUF.isCompatibleWith(response.contentType())，且 Person 为 Message 的子类时，将自动使用ProtoBuf Decoder
Person person = response.bodyToEntity(Person.class);

使用String Encoder

当response.bodyToEntity()传入的类型为String.class，且Response的contentType不为MediaType.APPLICATION_JSON时，将自动使用String Decoder来进行Decode。

final RestClient client = RestClient.ofDefault();
RestResponseBase response = client.get("localhost:8080/aaa")
        .execute()
        .toCompletableFuture()
        .get();

//当 !MediaType.APPLICATION_JSON.isCompatibleWith(response.contentType()) 时，自动使用String Decoder来进行Decode
String result = response.bodyToEntity(String.class);

使用byte[] Encoder

当response.bodyToEntity()传入的类型为byte[].class，且Response的contentType不为MediaType.APPLICATION_JSON时，将自动使用byte[] Decoder来进行Decode。

final RestClient client = RestClient.ofDefault();
RestResponseBase response = client.get("localhost:8080/aaa")
        .execute()
        .toCompletableFuture()
        .get();

//当 !MediaType.APPLICATION_JSON.isCompatibleWith(response.contentType()) 时，自动使用byte[] Decoder来进行Decode
byte[] result = response.bodyToEntity(byte[].class);

自定义Decoder

当RestClient内置的Decoder无法满足用户需求时，用户可以自定义Decoder，示例如下：

public class StringDecoder implements ByteDecoder {

    @Override
    public Object doDecode(DecodeContext<byte[]> ctx) {
        if (String.class.isAssignableFrom(ctx.targetType())) {
            return new String(ctx.content().value());
        }
        return ctx.next();
    }
}

Tip

在RestClient中，同时存在多个Decoder，它们之间通过getOrder()方法返回值区分执行顺序，值越小，优先级越高。针对当前Decoder，分为两种情况：

当前Decoder可以Decode该响应: 直接返回Decode后的结果。
当前Decoder不可以Decode该响应：调用ctx.next()，将Decode工作交给下一个Decoder，如果RestClient中的所有Decoder都无法编码该请求，则RestClient将抛出CodecException异常。

配置Decoder

Builder

在构造RestClient时传入自定义的Decoder实例，如：

final RestClient client = RestClient.create()
        .addDecoder(ctx -> {
            //decode...
            return ctx.next();
        })
        .build();

SPI

普通SPI

RestClient支持通过SPI的方式加载Decoder接口的实现类，使用时只需要按照SPI的加载规则将自定义的Decoder放入指定的目录下即可。

DecoderFactory

如果用户自定义的Decoder对于不同RestClient的配置有不同的实现，则用户可以实现DecoderFactory接口，并按照SPI的加载规则将自定义的DecoderFactory放入指定的目录下即可。

public interface DecoderFactory {
    Collection<Decoder> decoders(RestClientOptions clientOptions);
}

在RestClient构建时将调用DecoderFactory.decoders(RestClientOptions clientOptions)，该方法返回的所有Decoder都将加入到构建好的RestClient中。

直接绑定Request

Decoder可以直接绑定Request，使用方式如下:

final RestResponseBase response = client.post(url)
        .entity(new File("aaa"))
        .decoder(ctx -> {
            //decode...
            return ctx.next();
        })
        .execute()
        .toCompletableFuture()
        .get();

Tip

当Request绑定了Decoder，该Client中设置的所有Decoder将对该请求失效。即：如果当前Decoder无法解码该响应，则RestClient将会抛出CodecException异常。

执行时机

见请求处理完整流程中的Decoder。

DecodeAdvice

用户可以通过DecodeAdvice在Decode前后进行来插入业务逻辑，来对要解码的 ResponseContent 或者 Decode后的对象进行修改替换等操作。

示例

public class DecodeAdviceImpl implements DecodeAdvice {
    @Override
    public Object aroundDecode(DecodeAdviceContext ctx) throws Exception {
        //...before decode
        Object decoded = ctx.next();
        //...after decode
        return decoded;
    }
}

Tip

多个DecodeAdvice之间通过getOrder()方法返回值区分执行顺序，值越小，优先级越高。

配置方式

Builder

在构造RestClient时传入自定义的DecodeAdvice实例，如：

final RestClient client = RestClient.create()
        .addDecodeAdvice(ctx ->{
            //...before decode
            Object decoded = ctx.next();
            //...after decode
            return decoded;
        })
        .build();

SPI

普通SPI

RestClient支持通过SPI的方式加载DecodeAdvice接口的实现类，使用时只需要按照SPI的加载规则将自定义的DecodeAdvice放入指定的目录下即可。

DecodeAdviceFactory

如果用户自定义的DecodeAdvice对于不同RestClient的配置有不同的实现，则用户可以实现DecodeAdviceFactory接口，并按照SPI的加载规则将自定义的DecodeAdviceFactory放入指定的目录下即可。

public interface DecodeAdviceFactory {
    Collection<DecodeAdvice> decodeAdvices(RestClientOptions clientOptions);
}

在RestClient构建时将调用DecodeAdviceFactory.decodeAdvices(RestClientOptions clientOptions)，该方法返回的所有DecodeAdvice都将加入到构建好的RestClient中。

执行时机

见请求处理完整流程中的DecodeAdvice。