6.1.1 用一句話來描述接口請求

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

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

create

withHost host
withFilter filter
withParser parser

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

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

request

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

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

(1)文法：create -> with -> request

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

(2)JAVA示例

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

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

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

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

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

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

6.1.3 更好的建議

(1)不支持面向?qū)ο蟮膶崿F(xiàn)方式

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

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

(2)封裝自己的接口實例

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

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

如第一步先初始化：

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

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

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

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

(3)超時重試

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

如：

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

PhalApiClientResponse response = client.request();

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