如何更優雅地對接第三方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對象進行解析。

存在以下幾個問題：

1. 配置未抽取，以硬編碼方式注入不利于維護
2. 返回的數據是字符串，將它轉換為JSON對象極其不直觀
3. 原生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

總結

以上是生活随笔為你收集整理的如何更优雅地对接第三方API的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。