3.2 PhalApi 2.x SDK包的使用

PhalApi 2.x 的SDK包

SDK包列表

已經支持的SDK有：

• Java版SDK
• Object-C版SDK
• Object-C版SDK，遵循AFNetworking
• Javascript版SDK
• Golang版SDK
• PHP版SDK
• Python版SDK
• React-Native版SDK
• Ruby版SDK

一句話描述

為了給客戶端統(tǒng)一接口請求調用的規(guī)范性、流暢性和簡單易懂，我們特別為此使用了內部領域特定語言： 接口查詢語言 （Api Structured Query Language） 。

外部DSL

從外部DSL的角度來看待接口查詢的操作

create


withHost host
withFilter filter
withParser parser


reset   #特別注意：重復查詢時須重置請求狀態(tài)


withService service
withParams paramName1 paramValue1
withParams paramName2 paramValue2
withParams ... ...
withTimeout timeout


request

根據此設計理念，各客戶端語言都可以實現(xiàn)此接口請求的操作。

接口查詢語言設計理念與示例

文法：create -> with -> request

所用到的查詢文法如下（通常從上往下依次操作，順序不強制）：

JAVA示例

以JAVA版本為例，演示如何調用：
最簡單的調用，也就是默認接口的調用：

PhalApiClientResponse response = PhalApiClient.create()
       .withHost("http://demo.phalapi.net/")  //接口域名
       .request();                            //發(fā)起請求

通常的調用，即有設置接口服務名稱、接口參數(shù)和超時：

PhalApiClientResponse response = PhalApiClient.create()
       .withHost("http://demo.phalapi.net/")
       .withService("Site.Index")          //接口服務
       .withParams("username", "dogstar")     //接口參數(shù)
       .withTimeout(3000)                     //接口超時
       .request();

高級復雜調用，即設置了過濾器、解析器的操作：

PhalApiClientResponse response = PhalApiClient.create()
       .withHost("http://demo.phalapi.net/")
       .withService("Site.Index")
       .withParser(new PhalApiClientParserJson()) //設置JSON解析，默認已經是此解析，這里僅作演示
       .withParams("username", "dogstar")
       .withTimeout(3000)
       .request();

更好的建議

不支持面向對象的實現(xiàn)方式

此接口查詢的用法是屬于基礎的用法，其實現(xiàn)與宿主語言有強依賴關系，在不支持面向對象語言中，如javascript，可以使用函數(shù)序列的方式，如：

create();
withHost('http://demo.phalapi.net/');
withService('Site.Index');
withParams('username', 'dogstar');
withTimeout(3000);
var rs = request();

封裝自己的接口實例

通常，在一個項目里面我們只需要一個接口實例即可，但此語言沒默認使用單例模式，是為了大家更好的自由度。
基于此，大家在項目開發(fā)時，可以再進行封裝：提供一個全局的接口查詢單例，并組裝基本的接口公共查詢屬性。

即分兩步：初始化接口實例，以及接口具體的查詢操作。

如第一步先初始化：

PhalApiClient client = PhalApiClient.create()
     .withHost("http://demo.phalapi.net/")
     .withParser(new PhalApiClientParserJson());

第二步進行具體的接口請求：

PhalApiClientResponse response = client.reset()  #重復查詢時須重置
     .withService("Site.Index")
     .withParams("username", "dogstar")
     .withTimeout(3000)
     .request();

這樣，在其他業(yè)務場景下就不需要再重復設置這些共同的屬性（如過濾器、解析器）或者共同的接口參數(shù)。

超時重試

當接口請求超時時，統(tǒng)一返回 ret = 408，表示接口請求超時。此時可進行接口重試。

如：

PhalApiClient client = PhalApiClient.create()
     .withHost("http://demo.phalapi.net/")


PhalApiClientResponse response = client.request();


if (response.getRet() == 408) {
     response = client.request(); //請求重試
}