如何更優雅地對接第三方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解決第2、第三個問題。

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）