Feign基础教程

Feign使得编写java http客户端变得更容易

Feign 灵感来源于 Retrofit, JAXRS-2.0, 和 WebSocket. 最初是为了降低统一绑定 Denominator 到 HTTP API 的复杂度， 不区分是否支持 ReSTfulness.

为什么选择Feign而不是其他

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

Feign工作机制

Feign 通过注解注入一个模板化请求进行工作。在输出之前，参数以直接的方式应用于这些模板。虽然Feign仅限于支持基于文本的API，但它极大地简化了系统方面，例如重放请求。此外，Feign可以轻松地对您的转换进行单元测试。

基本用法

基本用法如下所示, 改编自 canonical Retrofit sample.

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

static class Contributor {
  String login;
  int contributions;
}

public static void main(String... args) {
  GitHub github = Feign.builder()
                       .decoder(new GsonDecoder())
                       .target(GitHub.class, "https://api.github.com");

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

定制

Feign有几个方面可以定制。举个简单的例子，您可以使用 Feign.builder() 来构造一个拥有你自己组件的API接口。例如：

interface Bank {
  @RequestLine("POST /account/{id}")
  Account getAccountInfo(@Param("id") String id);
}
...
Bank bank = Feign.builder().decoder(new AccountDecoder()).target(Bank.class, "https://api.examplebank.com");

多种接口

Feign 可以提供多种API接口。这些接口都被定义为 Target (默认的实现是 HardCodedTarget)，它允许在执行请求前动态发现和装饰该请求。

举个例子，下面的这个模式允许使用当前url和身份验证token来装饰每个发往身份验证中心服务的请求。

CloudDNS cloudDNS = Feign.builder().target(new CloudIdentityTarget(user, apiKey));

示例

Feign 包含了 GitHub 和 Wikipedia 客户端的实现样例。相似的项目也同样在实践中运用了 Feign 。尤其是 example daemon 项目。

集成

Feign 可以和其他的开源工具集成工作。你可以将这些开源工具集成到 Feign 中来！

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");

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");

Sax

SaxDecoder 用于解析XML,并兼容普通JVM和Android。

下面是一个配置sax来解析响应的例子：

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

JAXB

JAXB 包含了一个编码器和一个解码器，这个可以被用于XML格式的API。

添加 JAXBEncoder 以及 JAXBDecoder 到你的 Feign.Builder 中，如下：

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

JAX-RS

JAXRSContract 会覆盖注释处理，而是使用JAX-RS规范提供的标准处理。目前针对1.1规范。

以下是使用JAX-RS重写的上述示例：

interface GitHub {
  @GET @Path("/repos/{owner}/{repo}/contributors")
  List contributors(@PathParam("owner") String owner, @PathParam("repo") String repo);
}

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

OkHttp

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

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

Ribbon

RibbonClient 重写了 Feign 客户端的对URL的处理，其添加了智能路由以及一些其他由 Ribbon 提供的弹性功能。

集成Ribbon需要你将ribbon的客户端名称当做url的host部分来传递，如下：myAppProd。

MyService api = Feign.builder().client(RibbonClient.create()).target(MyService.class, "https://myAppProd");

Hystrix

HystrixFeign 配置了 Hystrix 提供的熔断机制。

要在Feign中使用Hystrix ，你需要添加Hystrix模块添加到类路径中。然后使用 HystrixFeign 来构造你的API：

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

SLF4J

SLF4JModule 允许你使用 SLF4J 作为 Feign 的日志记录模块，这样你就可以轻松的使用 (Logback, Log4J, etc.) 来记录你的日志。

要在 SLF4J 中使用 Feign，你需要添加 SLF4J 模块和对应的日志记录实现模块(比如Log4J)到你的类路径下。然后配置 Feign 使用 Slf4jLogger：

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

Decoders

Feign.builder() 允许你自定义一些额外的配置，比如说如何解码一个响应。

假如有接口方法返回的消息不是 Response，String，byte[] 或者 void类型的，那么你需要配置一个非默认的 Decoder。

下面是一个配置使用JSON解码器（使用的是 feign-gson 扩展）的例子：

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

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

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

Encoders

发送一个 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\"}");

通过配置一个 Encoder，你可以发送一个安全类型的请求体，如下是一个使用 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"));

@Body templates

@Body 注解申明一个请求体模板，模板中可以带有参数，与方法中 @Param 注解申明的参数相匹配。您可能需要添加 Content-Type 到请求头，使用方法如下：

interface LoginClient {

  @RequestLine("POST /")
  @Headers("Content-Type: application/xml")
  @Body("")
  void xml(@Param("user_name") String user, @Param("password") String password);

  @RequestLine("POST /")
  @Headers("Content-Type: application/json")
  // json curly braces must be escaped!
  @Body("%7B\"user_name\": \"{user_name}\", \"password\": \"{password}\"%7D")
  void json(@Param("user_name") String user, @Param("password") String password);
}
...
client.xml("denominator", "secret"); // 
client.json("denominator", "secret"); // {"user_name": "denominator", "password": "secret"}

Headers

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

给API设置请求头

如果特定接口或调用应始终设置某些请求头，则将
请求头定义为 api 的一部分是有意义的。

可以使用@Headers注释在 api 接口或方法上设置静态请求头。

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

方法可以使用变量扩展指定静态请求头的动态内容 @Headers。

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

设置key和value都是动态的请求头
有些API需要根据调用时动态确定使用不同的请求头(e.g. custom metadata header fields such as “x-amz-meta-” or “x-goog-meta-“),，
这时候可以使用 HeaderMap 注解，如下：

 @RequestLine("POST /")
 void post(@HeaderMap Map headerMap);

这些方法将请求头指定为 api 的一部分，并且
在构建Feign客户端时不需要任何自定义。

给Target设置请求头

有时我们需要在一个API实现中根据不同的 endpoint 来传入不同的Header，这个时候我们可以使用自定义的 RequestInterceptor 或 Target 来实现。

通过自定义的 RequestInterceptor 来实现请查看 Request Interceptors 章节。

下面是一个通过自定义 Target 来实现给每个 Target 设置安全校验信息Header的例子：

  static class DynamicAuthTokenTarget implements Target {
    public DynamicAuthTokenTarget(Class clazz,
                                  UrlAndTokenProvider provider,
                                  ThreadLocal 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)来为不同的线程设置不同的请求头。

高级用法

Base Apis

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

来看这个例子:

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

  @RequestLine("GET /all")
  List all();
}

您可以定义和定位特定的api，继承基本方法。

interface CustomAPI extends BaseAPI {
  @RequestLine("GET /custom")
  String custom();
}

在许多情况下，资源表示也是一致的。因此，基本api接口支持类型参数。

@Headers("Accept: application/json")
interface BaseApi {

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

  @RequestLine("GET /api")
  List list();

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

interface FooApi extends BaseApi { }

interface BarApi extends BaseApi { }

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");

也可以参考上面的 SLF4JLogger 的说明。

Request Interceptors

当你希望修改所有的的请求的时候，你可以使用 RequestInterceptor 。比如说，你作为一个中介，你可能需要为每个请求设置 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");

或者，你可能需要实现认证，这里有一个内置的基础校验拦截器 BasicAuthRequestInterceptor。

Bank bank = Feign.builder()
                 .decoder(accountDecoder)
                 .requestInterceptor(new BasicAuthRequestInterceptor(username, password))
                 .target(Bank.class, "https://api.examplebank.com");

Custom @Param Expansion

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

@RequestLine("GET /?since={date}") Result list(@Param(value = "date", expander = DateToMillis.class) Date date);

Dynamic Query Parameters

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

@RequestLine("GET /find")
V find(@QueryMap Map queryMap);

这也可以用于使用 QueryMapEncoder 从POJO对象生成查询参数。

@RequestLine("GET /find")
V find(@QueryMap CustomPojo customPojo);

以这种方式使用时，如果不指定自定义 QueryMapEncoder，将使用成员变量名称作为查询参数名称生成查询映射。以下POJO将生成 "/find?name={name}&number={number}" 的查询参数（不保证的查询参数的顺序，以及，将忽略值为null的参数）。

public class CustomPojo {
  private final String name;
  private final int number;

  public CustomPojo (String name, int number) {
    this.name = name;
    this.number = number;
  }
}

设置自定义 QueryMapEncoder:

MyApi myApi = Feign.builder()
                 .queryMapEncoder(new MyCustomQueryMapEncoder())
                 .target(MyApi.class, "https://api.hostname.com");

Error Handling

如果您需要更多控制处理意外响应，Feign实例可以通过构建器注册自定义 ErrorDecoder。

MyApi myApi = Feign.builder()
                 .errorDecoder(new MyErrorDecoder())
                 .target(MyApi.class, "https://api.hostname.com");

导致HTTP状态不在2xx范围内的所有响应都将触发 ErrorDecoder 的 decode 方法，允许您可以处理响应，将故障包装到自定义异常中或执行任何其他处理。如果要再次重试请求，请抛出 RetryableException。这将调用已注册的 Retryer。

Retry

默认情况下，Feign将自动重试 IOException，无论HTTP方法如何，都将其视为瞬态网络相关的异常，以及从 ErrorDecoder 抛出的任何 RetryableException。要自定义这个行为，通过构建器注册自定义 Retryer 实例。

MyApi myApi = Feign.builder()
                 .retryer(new MyRetryer())
                 .target(MyApi.class, "https://api.hostname.com");

Retryer 负责通过continueOrPropagate(RetryableException e); 方法返回的 true 或者 false 来确定是否应该重试；一个 Retryer 实例将为每个 Client 执行创建，允许您在需要时保持每个请求的状态。如果确定重试不成功，将抛出最后一次 RetryException。

Static and Default Methods

Feign所针对的接口可能具有静态或默认方法（如果使用Java 8+）。这些允许Feign客户端包含未由底层API明确定义的逻辑。例如，静态方法可以轻松指定常见的客户端构建配置;默认方法可用于组合查询或定义默认参数。

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

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

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

  /**
   * Lists all contributors for all repos owned by a user.
   */
  default List 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");
  }
}