SpringBoot——Netflix Feign

1. 概述

What？

Feign是一个 Netflix 开发的声明性的Web服务客户端，灵感来源于Retrofit、JAXRS-2.0和WebSocket。Feign 最初是为了降低统一绑定Denominator 到 HTTP API 的复杂度，使得 Java HTTP 客户端编写更方便。
Feign 的 MAVEN 直接依赖如下所示：

<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-core</artifactId>
    <version>${feign.version}</version>
</dependency>
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-gson</artifactId>
    <version>${feign.version}</version>
</dependency>

其中 feign-gson 主要是为了进行 gson 序列化，并不是必需的

Why Feign？

当然，你可以使用 Jersey 和 CXF 这些来写一个 Rest 或 SOAP 服务的java客服端，也可以直接使用 Apache HttpClient 来实现。但是 Feign 的目的是尽量的减少资源和代码来实现和 HTTP API 的连接。通过自定义的编码解码器以及错误处理，你可以编写任何基于文本的 HTTP API。

How？

Feign 通过注解注入一个模板化请求进行工作，它本身并不对请求进行处理，只不过通过注解来生成 Request，并进行 URL 的模板进行参数替换。然而这也限制了 Feign，只支持文本形式的API，它在响应请求等方面极大的简化了系统。同时，它也是十分容易进行单元测试的。

2. 使用简介

2.1 基本用法

Feign 的使用比较简单，如下是获取 GitHub Contributors 的示例：

public interface GitHubClient {

    // RequestLine注解声明请求方法和请求地址,可以允许有查询参数
    @RequestLine("GET /repos/{owner}/{repo}/contributors")
    List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo);

    public static class Contributor {
        public final String login;
        public final int contributions;

        public Contributor(String login, int contributions) {
            this.login = login;
            this.contributions = contributions;
        }
    }
}

通过 @RequestLine 即可定义一个远程的 Http 请求，通过参数指定请求的方法以及 PATH 属性（支持参数替换），具体值来自于以 @Param 指定的方法参数。

单元测试用例如下所示：

public class FeignTest {

    @Test
    public void testFeign() {
        GitHubClient github = Feign.builder()
                .decoder(new GsonDecoder())
                .target(GitHubClient.class, "https://api.github.com");

        // Fetch and print a list of the contributors to this library.
        List<GitHubClient.Contributor> contributors = github.contributors("OpenFeign", "feign");
        for (GitHubClient.Contributor contributor : contributors) {
            log.info(contributor.login + " (" + contributor.contributions + ")");
        }
    }
}

注意：这里并没有严格按照单元测试用例的规范来通过 assert 验证，而是将数据打印了出来。

2.2 自定义与定制化

可以看到在测试用例中，我们通过 Feign.Builder来实例化我们的 GitHubClient，其`Build的过程其实有许多的定制化入口，比如日志、编码、解码、重试机制等等。

比如，下面的代码演示了如何构建使用自定义的编码：

interface BankClient {
  @RequestLine("POST /account/{id}")
  Account getAccountInfo(@Param("id") String id);
}
...
// AccountDecoder() 是自己实现的一个Decoder
BankClient bankClient = Feign.builder().decoder(new AccountDecoder()).target(BankClient.class, "https://api.examplebank.com");

3. Feign 的组成

3.1 编码器 Encoder

发送一个Post请求最简单的方法就是传递一个 String 或者 byte[] 类型的参数了。你也许还需添加一个Content-Type请求头，如下:

interface LoginClient {
  @RequestLine("POST /")
  @Headers("Content-Type: application/json")
  void login(String content);
}
...
client.login("{\"user_name\": \"denominator\", \"password\": \"secret\"}");

通过配置一个解码器，你可以发送一个安全类型的请求体，如下是一个使用 feign-gson 扩展的例子:

static class Credentials {
  final String user_name;
  final String password;

  Credentials(String user_name, String password) {
    this.user_name = user_name;
    this.password = password;
  }
}

interface LoginClient {
  @RequestLine("POST /")
  void login(Credentials creds);
}
...
LoginClient client = Feign.builder()
                          .encoder(new GsonEncoder())
                          .target(LoginClient.class, "https://foo.com");

client.login(new Credentials("denominator", "secret"));

3.2 解码器 Decoder

相对应于编码器，假如有接口方法返回的消息不是 Response, String, byte[] 或者 void 类型的，那么你需要配置一个非默认的解码器。
下面是一个配置使用JSON解码器(使用的是feign-gson扩展)的例子:

1
2
3

GitHub github = Feign.builder()
                     .decoder(new GsonDecoder())
                     .target(GitHub.class, "https://api.github.com");

假如你想在将响应传递给解码器处理前做一些额外的处理，那么你可以使用mapAndDecode方法。一个用例就是使用jsonp服务的时候:

1
2
3

JsonpApi jsonpApi = Feign.builder()
            .mapAndDecode((response, type) -> jsopUnwrap(response, type), new GsonDecoder())
            .target(JsonpApi.class, "https://some-jsonp-api.com");

3.3 @Body 模板

@Body注解申明一个请求体模板，模板中可以带有参数，与方法中 @Param 注解申明的参数相匹配,使用方法如下

interface LoginClient {

  @RequestLine("POST /")
  @Headers("Content-Type: application/xml")
  @Body("<login \"user_name\"=\"{user_name}\" \"password\"=\"{password}\"/>")
  void xml(@Param("user_name") String user, @Param("password") String password);

  @RequestLine("POST /")
  @Headers("Content-Type: application/json")
  // json curly braces must be escaped!
  // 这里JSON格式需要的花括号居然需要转码，有点蛋疼了。
  @Body("%7B\"user_name\": \"{user_name}\", \"password\": \"{password}\"%7D")
  void json(@Param("user_name") String user, @Param("password") String password);
}

...
// <login "user_name"="denominator" "password"="secret"/>
client.xml("denominator", "secret"); 

// {"user_name": "denominator", "password": "secret"}
client.json("denominator", "secret");

3.4 Headers 支持

Feign 支持给请求的api设置或者请求的客户端设置请求头：

3.4.1 给API设置请求头

使用 @Headers 设置静态请求头

// 给BaseApi中的所有方法设置Accept请求头
@Headers("Accept: application/json")
interface BaseApi<V> {
  // 单独给put方法设置Content-Type请求头
  @Headers("Content-Type: application/json")
  @RequestLine("PUT /api/{key}")
  void put(@Param("key") String, V value);
}

设置动态值的请求头

1
2
3

@RequestLine("POST /")
@Headers("X-Ping: {token}")
void post(@Param("token") String token);

设置key和value都是动态的请求头

有些API需要根据调用时动态确定使用不同的请求头（比如：设置 x-amz-meta- 或者 x-goog-meta-*）,
这时候可以使用 @HeaderMap 注解，如下：
1
2
3
// @HeaderMap 注解设置的请求头优先于其他方式设置的
@RequestLine("POST /")
void post(@HeaderMap Map<String, Object> headerMap);

3.4.2 给Target设置请求头

有时我们需要在一个API实现中根据不同的endpoint来传入不同的Header，这个时候我们可以使用自定义的RequestInterceptor 或 Target来实现。
下面是一个通过自定义Target来实现给每个Target设置安全校验信息Header的例子：

static class DynamicAuthTokenTarget<T> implements Target<T> {
  public DynamicAuthTokenTarget(Class<T> clazz,
                                UrlAndTokenProvider provider,
                                ThreadLocal<String> requestIdProvider);
  ...
  @Override
  public Request apply(RequestTemplate input) {
    TokenIdAndPublicURL urlAndToken = provider.get();
    if (input.url().indexOf("http") != 0) {
      input.insert(0, urlAndToken.publicURL);
    }
    input.header("X-Auth-Token", urlAndToken.tokenId);
    input.header("X-Request-ID", requestIdProvider.get());

    return input.request();
  }
}
...
Bank bank = Feign.builder()
        .target(new DynamicAuthTokenTarget(Bank.class, provider, requestIdProvider));

这种方法的实现依赖于给Feign 客户端设置的自定义的RequestInterceptor 或 Target。可以被用来给一个客户端的所有api请求设置请求头。比如说可是被用来在header中设置身份校验信息。这些方法是在线程执行api请求的时候才会执行，所以是允许在运行时根据上下文来动态设置header的。
比如说可以根据线程本地存储(thread-local storage)来为不同的线程设置不同的请求头。

4. Feign 与第三方组件的集成

4.1 Gson

Gson 包含了一个编码器和一个解码器，这个可以被用于JSON格式的API。
添加 GsonEncoder 以及 GsonDecoder 到你的 Feign.Builder 中，如下:

GsonCodec codec = new GsonCodec();
GitHub github = Feign.builder()
                     .encoder(new GsonEncoder())
                     .decoder(new GsonDecoder())
                     .target(GitHub.class, "https://api.github.com");

需要的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-gson</artifactId>
    <version>8.18.0</version>
</dependency>

4.2 Jackson

Jackson 包含了一个编码器和一个解码器，这个可以被用于JSON格式的API。
添加 JacksonEncoder 以及 JacksonDecoder 到你的 Feign.Builder 中，如下：

GitHub github = Feign.builder()
                     .encoder(new JacksonEncoder())
                     .decoder(new JacksonDecoder())
                     .target(GitHub.class, "https://api.github.com");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-jackson</artifactId>
    <version>8.18.0</version>
</dependency>

4.3 Sax

SaxDecoder 用于解析XML,并兼容普通JVM和Android。下面是一个配置sax来解析响应的例子：

api = Feign.builder()
           .decoder(SAXDecoder.builder()
                              .registerContentHandler(UserIdHandler.class)
                              .build())
           .target(Api.class, "https://apihost");

对应的 MAVEN 依赖如下：

<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-sax</artifactId>
    <version>8.18.0</version>
</dependency>

4.4 JAXB

JAXB 包含了一个编码器和一个解码器，这个可以被用于XML格式的API。
添加 JAXBEncoder 以及 JAXBDecoder 到你的 Feign.Builder 中，如下：

api = Feign.builder()
           .encoder(new JAXBEncoder())
           .decoder(new JAXBDecoder())
           .target(Api.class, "https://apihost");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-jaxb</artifactId>
    <version>8.18.0</version>
</dependency>

4.5 JAX-RS

JAXRSContract 使用 JAX-RS 规范重写覆盖了默认的注解处理。下面是一个使用 JAX-RS 的例子：

interface GitHub {
  @GET @Path("/repos/{owner}/{repo}/contributors")
  List<Contributor> contributors(@PathParam("owner") String owner, @PathParam("repo") String repo);
}
// contract 方法配置注解处理器,注解处理器定义了哪些注解和值是可以作用于接口的
GitHub github = Feign.builder()
                     .contract(new JAXRSContract())
                     .target(GitHub.class, "https://api.github.com");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-jaxrs</artifactId>
    <version>8.18.0</version>
</dependency>

4.6 OkHttp

OkHttpClient 使用 OkHttp 来发送 Feign 的请求，OkHttp 支持 SPDY (SPDY是Google开发的基于TCP的传输层协议，用以最小化网络延迟，提升网络速度，优化用户的网络使用体验),并有更好的控制http请求。
要让 Feign 使用 OkHttp ，你需要将 OkHttp 加入到你的环境变量中区，然后配置 Feign 使用 OkHttpClient，如下：

1
2
3

GitHub github = Feign.builder()
                     .client(new OkHttpClient())
                     .target(GitHub.class, "https://api.github.com");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-okhttp</artifactId>
    <version>8.18.0</version>
</dependency>

4.7 Ribbon

RibbonClient 重写了 Feign 客户端的对URL的处理，其添加了智能路由以及一些其他由Ribbon提供的弹性功能。
集成Ribbon需要你将ribbon的客户端名称当做url的host部分来传递，如下：

1 2	// myAppProd是你的ribbon client name MyService api = Feign.builder().client(RibbonClient.create()).target(MyService.class, "https://myAppProd");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-ribbon</artifactId>
    <version>8.18.0</version>
</dependency>

4.8 Hystrix

HystrixFeign 配置了 Hystrix 提供的熔断机制。
要在 Feign 中使用 Hystrix ，你需要添加Hystrix模块到你的环境变量，然后使用 HystrixFeign 来构造你的API：

1	MyService api = HystrixFeign.builder().target(MyService.class, "https://myAppProd");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-hystrix</artifactId>
    <version>8.18.0</version>
</dependency>

4.9 SLF4J

SLF4JModule 允许你使用 SLF4J 作为 Feign 的日志记录模块，这样你就可以轻松的使用 Logback, Log4J , 等来记录你的日志.
要在 Feign 中使用 SLF4J ，你需要添加SLF4J模块和对应的日志记录实现模块(比如Log4J)到你的环境变量，然后配置 Feign使用Slf4jLogger：

1
2
3

GitHub github = Feign.builder()
                     .logger(new Slf4jLogger())
                     .target(GitHub.class, "https://api.github.com");

对应的 MAVEN 依赖如下：

<!-- https://mvnrepository.com/artifact/com.netflix.feign/feign-gson -->
<dependency>
    <groupId>com.netflix.feign</groupId>
    <artifactId>feign-slf4j</artifactId>
    <version>8.18.0</version>
</dependency>

5. 高级用法

5.1 通用 API

有些请求中的一些方法是通用的，但是可能会有不同的参数类型或者返回类型，这个时候可以这么用：

// 通用API
interface BaseAPI {
  @RequestLine("GET /health")
  String health();

  @RequestLine("GET /all")
  List<Entity> all();
}

// 继承通用API
interface CustomAPI extends BaseAPI {
  @RequestLine("GET /custom")
  String custom();
}

// 各种类型有相同的表现形式，定义一个统一的API
@Headers("Accept: application/json")
interface BaseApi<V> {

  @RequestLine("GET /api/{key}")
  V get(@Param("key") String key);

  @RequestLine("GET /api")
  List<V> list();

  @Headers("Content-Type: application/json")
  @RequestLine("PUT /api/{key}")
  void put(@Param("key") String key, V value);
}

// 根据不同的类型来继承
interface FooApi extends BaseApi<Foo> { }

interface BarApi extends BaseApi<Bar> { }

5.2 Logging

你可以通过设置一个 Logger 来记录http消息，如下:

GitHub github = Feign.builder()
                     .decoder(new GsonDecoder())
                     .logger(new Logger.JavaLogger().appendToFile("logs/http.log"))
                     .logLevel(Logger.Level.FULL)
                     .target(GitHub.class, "https://api.github.com");

参考第 4 部分的 SLF4J 集成

5.2 Request Interceptors

当你希望修改所有的的请求的时候，你可以使用Request Interceptors。比如说，你作为一个中介，你可能需要为每个请求设置 X-Forwarded-For：

static class ForwardedForInterceptor implements RequestInterceptor {
  @Override public void apply(RequestTemplate template) {
    template.header("X-Forwarded-For", "origin.host.com");
  }
}
...
Bank bank = Feign.builder()
                 .decoder(accountDecoder)
                 .requestInterceptor(new ForwardedForInterceptor())
                 .target(Bank.class, "https://api.examplebank.com");

5.3 自定义 @Param 展开

在使用 @Param 注解给模板中的参数设值的时候，默认的是使用的对象的 toString() 方法的值，通过声明自定义的Param.Expander，用户可以控制其行为，比如说格式化 Date 类型的值：

1
2
3

// 通过设置 @Param 的 expander 为 DateToMillis.class 可以定义Date类型的值
@RequestLine("GET /?since={date}") 
Result list(@Param(value = "date", expander = DateToMillis.class) Date date);

5.4 动态查询参数

动态查询参数支持，通过使用 @QueryMap 可以允许动态传入请求参数,如下:

1 2	@RequestLine("GET /find") V find(@QueryMap Map<String, Object> queryMap);

5.5 表态方法与默认方法

如果你使用的是JDK 1.8+ 的话，那么你可以给接口设置统一的默认方法和静态方法,这个事JDK8的新特性，如下:

interface GitHub {
  @RequestLine("GET /repos/{owner}/{repo}/contributors")
  List<Contributor> contributors(@Param("owner") String owner, @Param("repo") String repo);

  @RequestLine("GET /users/{username}/repos?sort={sort}")
  List<Repo> repos(@Param("username") String owner, @Param("sort") String sort);

  default List<Repo> repos(String owner) {
    return repos(owner, "full_name");
  }

  /**
   * Lists all contributors for all repos owned by a user.
   */
  default List<Contributor> contributors(String user) {
    MergingContributorList contributors = new MergingContributorList();
    for(Repo repo : this.repos(owner)) {
      contributors.addAll(this.contributors(user, repo.getName()));
    }
    return contributors.mergeResult();
  }

  static GitHub connect() {
    return Feign.builder()
                .decoder(new GsonDecoder())
                .target(GitHub.class, "https://api.github.com");
  }
}