3.2 PhalApi 2.x SDK包的使用

PhalApi 2.x 的SDK包

SDK包列表

已經(jīng)支持的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)一接口請(qǐng)求調(diào)用的規(guī)范性、流暢性和簡單易懂，我們特別為此使用了內(nèi)部領(lǐng)域特定語言： 接口查詢語言 （Api Structured Query Language） 。

外部DSL

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

create


withHost host
withFilter filter
withParser parser


reset   #特別注意：重復(fù)查詢時(shí)須重置請(qǐng)求狀態(tài)


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


request

根據(jù)此設(shè)計(jì)理念，各客戶端語言都可以實(shí)現(xiàn)此接口請(qǐng)求的操作。

接口查詢語言設(shè)計(jì)理念與示例

文法：create -> with -> request

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

JAVA示例

以JAVA版本為例，演示如何調(diào)用：
最簡單的調(diào)用，也就是默認(rèn)接口的調(diào)用：

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

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

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

高級(jí)復(fù)雜調(diào)用，即設(shè)置了過濾器、解析器的操作：

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

更好的建議

不支持面向?qū)ο蟮膶?shí)現(xiàn)方式

此接口查詢的用法是屬于基礎(chǔ)的用法，其實(shí)現(xiàn)與宿主語言有強(qiáng)依賴關(guān)系，在不支持面向?qū)ο笳Z言中，如javascript，可以使用函數(shù)序列的方式，如：

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

封裝自己的接口實(shí)例

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

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

如第一步先初始化：

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

第二步進(jìn)行具體的接口請(qǐng)求：

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

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

超時(shí)重試

當(dāng)接口請(qǐng)求超時(shí)時(shí)，統(tǒng)一返回 ret = 408，表示接口請(qǐng)求超時(shí)。此時(shí)可進(jìn)行接口重試。

如：

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


PhalApiClientResponse response = client.request();


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