【SpringCloud技術專題】「原生態Fegin」開啟Fegin之RPC技術的開端，你會使用原生態的Fegin嗎？(中)

承接上篇文章：

【SpringCloud技術專題】「原生態Fegin」開啟Fegin之RPC技術的開端，你會使用原生態的Fegin嗎？(上)

為什麼選擇Feign而不是其他

• 你可以使用 Jersey 和 CXF 這些來寫一個 Rest 或 SOAP 服務的java客服端。

• 你也可以直接使用 Apache HttpClient 來實現。但是 Feign 的目的是儘量的減少資源和程式碼來實現和 HTTP API 的連線。

• 通過自定義的編碼解碼器以及錯誤處理，你可以編寫任何基於文字的 HTTP API。

Feign工作機制

• Feign通過註解注入一個模板化請求進行工作。只需在傳送之前關閉它，引數就可以被直接的運用到模板中。

• 然而這也限制了Feign，只支援文字形式的API，它在響應請求等方面極大的簡化了系統。

Feign使用回顧

基本用法

基本的使用如下所示

interface UserService {
 	// RequestLine註解宣告請求方法和請求地址,可以允許有查詢引數
 	@RequestLine("GET /repos/{userName}/{age}/users")
	 List<User> getUserList(@Param("userName") String userName, @Param("age") int age);
}

static class User {
 String userName;
 int age;
}

public static void main(String... args) {
 User user = Feign.builder()
            .decoder(new GsonDecoder())
            .target(UserService.class, "https://api.github.com");
 // Fetch and print a list of the contributors to this library.
 List<User> userList = github.getUserList("libo", 12);
 for (User user : userList) {
   System.out.println(user.userName + " (" + user.age + ")");
 }
}

自定義實現介面

Feign 有許多可以自定義的方面。舉個簡單的例子，你可以使用 Feign.builder() 來構造一個擁有你自己元件的API介面，如下:

interface Bank {
 @RequestLine("POST /account/{id}")
 Account getAccountInfo(@Param("id") String id);
}

// AccountDecoder() 是自己實現的一個Decoder

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。尤其是它的示例後臺程式。

Feign整合多種型別編碼器

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

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>

Jackson

• Jackson包含了一個編碼器和一個解碼器，這個可以被用於JSON格式的API。

新增JacksonEncoder以及JacksonDecoder到你的Feign.Builder 中， 如下:

UserService service = Feign.builder()
           .encoder(new JacksonEncoder())
           .decoder(new JacksonDecoder())
           .target(UserService.class, https://api.user.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>

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>

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>

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>

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

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>

Ribbon

RibbonClient 重寫了 Feign 客戶端的對URL的處理，其新增了 智慧路由以及一些其他由Ribbon提供的彈性功能。
整合Ribbon需要你將ribbon的客戶端名稱當做url的host部分來傳遞，如下：

// 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>

Hystrix

HystrixFeign配置了Hystrix提供的熔斷機制。

要在Feign中使用Hystrix ，你需要新增Hystrix模組到你的環境變數，然後使用 HystrixFeign 來構造你的API:

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>

SLF4J

SLF4JModule 允許你使用 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依賴:

<!-- 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>

Feign 組成

Decoders

Feign.builder() 允許你自定義一些額外的配置，比如說如何解碼一個響應。假如有介面方法返回的訊息不是 Response, String, byte[] 或者 void 型別的，那麼你需要配置一個非預設的解碼器。

• 下面是一個配置使用JSON解碼器(使用的是feign-gson擴充套件)的例子:

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("<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);
}
...
client.xml("denominator", "secret"); // <login "user_name"="denominator" "password"="secret"/>
client.json("denominator", "secret"); // {"user_name": "denominator", "password": "secret"}

Headers

• Feign 支援給請求的api設定或者請求的客戶端設定請求頭，如下:
• 給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);
}

設定動態值的請求頭

@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<String, Object> headerMap);

給Target設定請求頭

有時我們需要在一個API實現中根據不同的endpoint來傳入不同的Header，這個時候我們可以使用自定義的RequestInterceptor或Target來實現。

通過自定義的 RequestInterceptor來實現

通過自定義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)來為不同的執行緒設定不同的請求頭。