Feign使用简介
基本用法
基本的使用如下所示，一个对于的适配。
interface GitHub { // RequestLine注解声明请求方法和请求地址,可以允许有查询参数 @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);}...// AccountDecoder() 是自己实现的一个DecoderBank bank = Feign.builder().decoder(new AccountDecoder()).target(Bank.class, "https://api.examplebank.com");
多种接口
Feign可以提供多种API接口，这些接口都被定义为 Target<T> (默认的实现是 HardCodedTarget<T>), 它允许在执行请求前动态发现和装饰该请求。
CloudDNS cloudDNS = Feign.builder().target(new CloudIdentityTarget(user, apiKey));
示例
Feign 包含了 和 客户端的实现样例.相似的项目也同样在实践中运用了Feign。尤其是它的示例后台程序。
Feign集成模块
Feign 可以和其他的开源工具集成工作。你可以将这些开源工具集成到 Feign 中来。目前已经有的一些模块如下:
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依赖:
com.netflix.feign feign-gson 8.18.0
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依赖:
com.netflix.feign feign-jackson 8.18.0
Sax
用于解析XML,并兼容普通JVM和Android。下面是一个配置sax来解析响应的例子:
api = Feign.builder() .decoder(SAXDecoder.builder() .registerContentHandler(UserIdHandler.class) .build()) .target(Api.class, "https://apihost");
Maven依赖:
com.netflix.feign feign-sax 8.18.0
JAXB
包含了一个编码器和一个解码器，这个可以被用于XML格式的API。
添加JAXBEncoder 以及 JAXBDecoder 到你的 Feign.Builder 中， 如下: api = Feign.builder() .encoder(new JAXBEncoder()) .decoder(new JAXBDecoder()) .target(Api.class, "https://apihost");
Maven依赖:
com.netflix.feign feign-jaxb 8.18.0
JAX-RS
使用 JAX-RS 规范重写覆盖了默认的注解处理。下面是一个使用 JAX-RS 的例子:
interface GitHub { @GET @Path("/repos/{owner}/{repo}/contributors") List 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依赖:
com.netflix.feign feign-jaxrs 8.18.0
OkHttp
使用 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");
Maven依赖:
com.netflix.feign feign-okhttp 8.18.0
Ribbon
重写了 Feign 客户端的对URL的处理，其添加了 智能路由以及一些其他由提供的弹性功能。
// myAppProd是你的ribbon client nameMyService api = Feign.builder().client(RibbonClient.create()).target(MyService.class, "https://myAppProd");
Maven依赖:
com.netflix.feign feign-ribbon 8.18.0
Hystrix
配置了 Hystrix 提供的熔断机制。
Feign 中使用 Hystrix ，你需要添加Hystrix模块到你的环境变量，然后使用 HystrixFeign 来构造你的API: MyService api = HystrixFeign.builder().target(MyService.class, "https://myAppProd");
Maven依赖:
com.netflix.feign feign-hystrix 8.18.0
SLF4J
允许你使用 SLF4J 作为 Feign 的日志记录模块，这样你就可以轻松的使用 Logback, Log4J , 等 来记录你的日志.
Feign 中使用 SLF4J ，你需要添加SLF4J模块和对应的日志记录实现模块(比如Log4J)到你的环境变量，然后配置 Feign使用Slf4jLogger : GitHub github = Feign.builder() .logger(new Slf4jLogger()) .target(GitHub.class, "https://api.github.com");
Maven依赖:
com.netflix.feign feign-slf4j 8.18.0
Feign 组成
Decoders
Feign.builder() 允许你自定义一些额外的配置，比如说如何解码一个响应。假如有接口方法返回的消息不是 Response, String, byte[] 或者 void 类型的，那么你需要配置一个非默认的解码器。
GitHub github = Feign.builder() .decoder(new GsonDecoder()) .target(GitHub.class, "https://api.github.com");
假如你想在将响应传递给解码器处理前做一些额外的处理，那么你可以使用mapAndDecode方法。一个用例就是使用jsonp服务的时候:
// 貌似1.8.0版本中沒有mapAndDecode这个方法。。。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\"}");
通过配置一个解码器，你可以发送一个安全类型的请求体，如下是一个使用 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 注解申明的参数相匹配,使用方法如下
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! // 这里JSON格式需要的花括号居然需要转码，有点蛋疼了。 @Body("%7B\"user_name\": \"{user_name}\", \"password\": \"{password}\"%7D") void json(@Param("user_name") String user, @Param("password") String password);}...//
Headers
Feign 支持给请求的api设置或者请求的客户端设置请求头
给API设置请求头
- 使用
@Headers设置静态请求头
// 给BaseApi中的所有方法设置Accept请求头@Headers("Accept: application/json")interface BaseApi { // 单独给put方法设置Content-Type请求头 @Headers("Content-Type: application/json") @RequestLine("PUT /api/{key}") void put(@Param("key") String, V value); } - 设置动态值的请求头
@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注解，如下:
// @HeaderMap 注解设置的请求头优先于其他方式设置的@RequestLine("POST /")void post(@HeaderMap Map headerMap); 给Target设置请求头
有时我们需要在一个API实现中根据不同的endpoint来传入不同的Header，这个时候我们可以使用自定义的RequestInterceptor 或 Target来实现.
通过自定义的 RequestInterceptor 来实现请查看 Request Interceptors 章节. 下面是一个通过自定义Target来实现给每个Target设置安全校验信息Header的例子:static class DynamicAuthTokenTargetimplements 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的。
高级用法
Base APIS
有些请求中的一些方法是通用的，但是可能会有不同的参数类型或者返回类型，这个时候可以这么用:
// 通用APIinterface 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"); 也可以参考上面的 SLF4J 章节的说明
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"); 或者，你可能需要实现Basic Auth，这里有一个内置的基础校验拦截器 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 类型的值:
// 通过设置 @Param 的 expander 为 DateToMillis.class 可以定义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); Static and Default Methods
如果你使用的是JDK 1.8+ 的话，那么你可以给接口设置统一的默认方法和静态方法,这个事JDK8的新特性，如下:
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"); } }