本文所有示例完整代碼地址：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。
