如何更優雅地對接第三方API_ZenDei技術網路在線

本文所有示例完整代碼地址：https://github.com/yu linfeng/BlogRepositories/tree/master/repositories/third 我們在日常開發過程中，有不少場景會對接第三方的API，例如第三方賬號登錄，第三方服務等等。第三方服務會提供API或者S ...

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

如何更優雅地對接第三方API

原生JDK構造HTTP請求客戶端，調用API

在SpringBoot下使用RestTemplate，以及抽取配置的方式調用API

使用OpenFeign以及抽取配置的方式調用API

在SpringBoot下使用`RestTemplate`，以及抽取配置的方式調用API

使用`OpenFeign`以及抽取配置的方式調用API