如何更優雅地對接第三方API
本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
我們在日常開發過程中，有不少場景會對接第三方的API，例如第三方賬號登入，第三方服務等等。第三方服務會提供API或者SDK，我依稀記得早些年Maven還沒那麼廣泛使用，通常要對接第三方服務的時候會去下載第三方服務的SDK開發包，也就是jar包，拷貝到自己的工程中進行開發。但現如今，幾乎所有的大中小企業都使用Maven進行依賴管理，第三方服務通過提供SDK包的情況越來越少，有的SDK也早已處於不再更新的狀態。並且現在流行的微服務以及輕量級的RESTful通訊方式，使得第三方服務主要提供API介面。
API介面，指的是通過HTTP的方式提供服務對接，也就需要對接方發起HTTP請求，解析第三方服務返回的資料；而SDK開發包，指的是對接方直接呼叫第三方服務提供的Java方法進行呼叫，不再對第三方服務發起HTTP請求。從便利性上講，以SDK的方式對接第三方服務，的確能更加方便地進行開發對接工作。而從目前的趨勢看，以RESTful通訊的微服務正逐漸成為主流，服務的提供方也不再對外提供SDK開發包，因為這涉及開發量以及包的依賴問題。
我仍記得在第一家公司對接第三方API時的場景，業務要求能通過微信發起WiFi連線，這自然需要對接微信提供的API介面。那時我用了“最低階”的對接方式，也就是使用原生JDK發起HTTP請求，以及對HTTP響應的JSON資料進行解析獲取我想要的資料。這其中的坑不勝其數，手寫的HTTP請求客戶端本身的不健壯，解析響應資料時經常丟擲空指標，其中的苦惱不盡其數。
直到現在，SpringBoot為我們封裝了RestTemplate，再到SpringCloud可以通過Feign讓我們呼叫API就好像在呼叫介面一般順滑。
Feign詮釋了什麼是面向物件，什麼是一切皆為物件，我甚至認為，它可以作為面向物件程式設計實踐的典型。
所以本文將以下4個示例講述如何優雅地對接第三方API。
- 原生JDK構造HTTP請求客戶端，呼叫API
- 在SpringBoot下使用
RestTemplate，以及抽取配置的方式呼叫API - 使用
OpenFeign以及抽取配置的方式呼叫API
準備工作
第三方API提供方，聚合資料：www.juhe.cn
API介面詳情：https://www.juhe.cn/docs/api/id/21
appKey（建議註冊賬號免費申請）：71e065a2cdf2753a5d6261b5002498b7
實現的功能：根據股票程式碼獲取股票名稱
原生JDK構造HTTP請求客戶端，呼叫API
這種方式需要手動去建立HTTP連線，並將資料寫入流中，再將資料轉換為JSON物件進行解析。
存在以下幾個問題：
- 配置未抽取，以硬編碼方式注入不利於維護
- 返回的資料是字串，將它轉換為JSON物件極其不直觀
- 原生JDK構造HTTP客戶端不能保證健壯性
第一個問題，首先是不可取的，必須將它抽取為properties或者yml配置。將appId或者appKey以硬編碼的方式注入，不是一個合格的工程師。
第二個問題，轉換為JSON物件獲取資料：
//本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
String data = getResponse(code); //獲取API返回資料
JSONObject jsonObject = JSONObject.parseObject(data); //將資料轉換為JSON物件
if (jsonObject.getInteger("error_code") != 0) { //判斷API介面是否呼叫成功
return ;
}
//解析資料，獲取股票名稱
JSONArray resultArray = JSONArray.parseArray(jsonObject.getString("result"));
JSONObject result = JSONObject.parseObject(resultArray.getString(0));
JSONObject stockObject = JSONObject.parseObject(result.getString("data"));
String stockName = stockObject.getString("name");你寫完後，還能回憶起這個API介面所返回的資料格式嗎？
第三個問題，也就是上面程式碼片段中的getResponse方法：
//本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
String strUrl = String.format(URL, code, APPKEY);
StringBuffer sb = new StringBuffer();
URL url = new URL(strUrl);
HttpURLConnection conn = (HttpURLConnection) url.openConnection(); //建立一個HTTP連線
//構造HTTP請求資料
conn.setRequestMethod("GET");
conn.setRequestProperty("User-agent", USER_AGENT);
conn.connect(); //開啟連線
InputStream is = conn.getInputStream();
BufferedReader reader = new BufferedReader(new InputStreamReader(is, "UTF-8"));
//將API介面的返回資料寫入
String strRead = null;
while ((strRead = reader.readLine()) != null) {
sb.append(strRead);
}
return sb.toString();這種“教科書”式的實現方式，其程式碼的複雜度，健壯性都值得商榷，有的工程中將HTTP請求客戶端封裝成一個公共類，有的使用現有的一些HTTP請求客戶端。但我認為這都不是好的方式。就算例如Okhttp有很好的穩定性，但也解決不了第二個介面返回資料解析的問題，
在SpringBoot下使用RestTemplate，以及抽取配置的方式呼叫API
前面我們使用最“古老”的方式發現了3個問題，在SpringBoot大行其道的今天，將一些配置抽取出來，不同的環境執行不同的配置檔案是常見的做法。例如我們可以將上面的appKey放到application.yml配置檔案中。
juhe-stock:
appKey: 71e065a2cdf2753a5d6261b5002498b7同時定義第三方服務的配置類。
package com.coderbuff.third2resttemplateprop;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
/**
* 配置
* @author yulinfeng
* @date 2019/12/26
*/
@Data
@Component
@ConfigurationProperties("juhe-stock")
public class JuheConfig {
/**
* appkey
*/
private String appKey;
}這樣當Spring容器啟動時，appKey就被注入到了JuheConfig類的appKey欄位中。
第一個問題被完美解決了，接下來我們來看如何通過RestTemplate解決第二、第三個問題。
RestTemplate簡化了我們發起HTTP請求，它內部預設使用JDK構造HTTP客戶端，它發起HTTP請求獲取響應資料通過getForObject和getForEntity，前者能直接將響應資料封裝成一個物件，後者則將封裝HTTP呼叫的一些響應狀態，在我們使用getForObject。
getForObject能將響應資料直接轉換為一個物件供我們使用，這意味著我們不再依靠繁瑣的JSON格式轉換獲取我們想要的資料，但同時也意味著我們需要定義返回物件。我們先看示例中，返回的JSON是怎麼的格式。
{
"resultcode":"200",
"reason":"SUCCESSED!",
"result":[
{
//省略
"dapandata":{
"name":"貴州茅臺"
//省略
}
}
],
"error_code":0
}因為篇幅原因，我省略了一些欄位資訊。觀察JSON資料格式，我們只需要拿到股票名稱，股票名稱處於比較底層的位置，我們定義一個叫做JuheStockResultDapanData的類，欄位和JSON中的key相同。
package com.coderbuff.third2resttemplateprop.entity;
import lombok.Data;
/**
* @author yulinfeng
* @date 2019/12/26
*/
@Data
public class JuheStockResultDapanData {
private String name;
}它的外層key是一個數組，對應的也就是List，其中的一個物件就是我們定義的JuheStockResultDapanData，所以我們定義一個JuheStockResult類，對應JSON中key=result的資料。
package com.coderbuff.third2resttemplateprop.entity;
import lombok.Data;
/**
* @author yulinfeng
* @date 2019/12/26
*/
@Data
public class JuheStockResult {
private JuheStockResultDapanData dapandata;
}在最外層是一些呼叫資訊和錯誤碼，所以我們繼續定義一個響應類JuheStockResponse。
package com.coderbuff.third2resttemplateprop.entity;
import lombok.Data;
import java.util.List;
import java.util.Map;
/**
* @author yulinfeng
* @date 2019/12/26
*/
@Data
public class JuheStockResponse {
/**
* 響應碼
*/
private String resultcode;
/**
* 錯誤資訊
*/
private String reason;
/**
* 錯誤碼
*/
private String error_code;
/**
* 資料
*/
private List<JuheStockResult> result;
}注意欄位名要和API介面返回的JSON資料key值保持一致。這樣我們就定義好了整個JSON物件所對應的Java物件，其中我省略了很多欄位，Java物件中沒有JSON中對應的欄位，資料自然也不會對映到Java物件中。接下來就是使用RestTemplate#getForObject方法呼叫API介面。
//本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
String url = String.format(URL, code, juheConfig.getAppKey()); //拼接URL
RestTemplate restTemplate = new RestTemplate();
restTemplate.setMessageConverters(parseContentType()); //設定ContentType支援的型別
JuheStockResponse response = restTemplate.getForObject(url, JuheStockResponse.class);
JuheStockResultDapanData juheStockResultDapanData =
response.getResult().get(0).getDapandata();
String name = juheStockResultDapanData.getName();可以看到這種方式相比較於第一種“教科書”式呼叫HTTP介面，無論從易用性和健壯性都要略勝一籌，特別是不再去解析JSON物件，RestTemplate已經為我們做好了轉換，這樣的程式碼，即使換了一個人維護，也同樣能明白是什麼含義。
這種對接第三方API的方式，我想也是常年使用SpringBoot所採用的方式，因為它都解決了我們在開頭提到幾個問題，似乎想不到還能有什麼更優雅地方式，直到遇到了下面的方式。
使用OpenFeign以及抽取配置的方式呼叫API
在使用這種方式呼叫第三方API時，我簡直想要大呼一聲Amazing！，簡直太完美太優雅了。它不但解決了上面的3個問題，它同時把面向物件的思想發揮到了極致。
上面的思路不過是封裝再封裝，封裝完HTTP客戶端後又封裝了JSON資料轉換，實際上的思路仍然是傳遞一個URL->請求->響應的思路，但接下來的這種方式，真真正正地詮釋了什麼是面向物件，什麼是一切皆為物件。
它將API呼叫變得更加像呼叫普通介面一樣方便。
使用過SpringCloud的同學對Feign並不陌生，甚至覺得我孤陋寡聞。原版的OpenFeign可不依賴Spring獨立使用（https://github.com/OpenFeign/feign），SpringCloud整合了OpenFeign，在SpringCloud2.x，Feign甚至成為了SpringCloud的一級專案（https://cloud.spring.io/spring-cloud-openfeign/）這足以體現它的地位。
在SpringCloud中，OpenFeign的功能很強大，它為微服務架構下服務之間的呼叫提供瞭解決方案，同時它可以結合其它元件可以實現負載均衡的HTTP客戶端。
接下來我們將展示使用原版的OpenFeign優雅地呼叫第三方API服務。
我們同樣需要定義JuheStockResponse、JuheStockResult、JuheStockResultDapanData類，因為在OpenFeign中，也自動的將JSON資料轉換為了Java物件。但我們需要定義一個介面——JuheClient。
package com.coderbuff.third3feignprop;
import com.coderbuff.third3feignprop.entity.JuheStockResponse;
import feign.Param;
import feign.RequestLine;
/**
* @author yulinfeng
* @date 2019/12/26
*/
public interface JuheClient {
/**
* 根據股票程式碼查詢股票資訊
* @param code 股票程式碼
* @return 介面返回
*/
@RequestLine("GET /finance/stock/hs?gid={gid}&key={key}")
JuheStockResponse queryStock(@Param("gid") String code, @Param("key") String appKey);
}這簡直就是面向物件思想的最佳實踐，接下來的工作基本上就是直接呼叫這個方法，就能呼叫我們想要呼叫的API。
//本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
JuheClient client = Feign.builder().encoder(new JacksonEncoder()).decoder(new JacksonDecoder()).target(JuheClient.class, juheConfig.getUrl());
JuheStockResponse response = client.queryStock(code, juheConfig.getAppKey());
JuheStockResultDapanData juheStockResultDapanData =
response.getResult().get(0).getDapandata();
String name = juheStockResultDapanData.getName();這看起來似乎和直接使用RestTemplate並無大異，但我仍然想表達我的激動，我仍然認為這其中的奧祕不在於編碼的具體實現，而在於將API介面呼叫上升到了面向物件的最佳實踐。沒有了URL的拼接，像呼叫普通介面一樣方便地呼叫第三方API。
本文所有示例完整程式碼地址：https://github.com/yu-linfeng/BlogRepositories/tree/master/repositories/third
關注公眾號：CoderBuff，回覆“es”獲取《ElasticSearch6.x實戰教程》完整版PDF。
這是一個能給程式設計師加buff的公眾號 （CoderBuff）
