## 6.1.1 用一句話來描述接口請求 為了給客戶端統一接口請求調用的規范性、流暢性和簡單易懂，我們特別為此使用了內部領域特定語言： **接口查詢語言** （Api Structured Query Language） 。 ###從外部DSL的角度來看待接口查詢的操作 ```javascript create withHost host withFilter filter withParser parser reset #特別注意：重復查詢時須重置請求狀態 withService service withParams paramName1 paramValue1 withParams paramName2 paramValue2 withParams ... ... withTimeout timeout request ``` 根據此設計理念，各客戶端語言都可以實現此接口請求的操作。 ## 6.1.2 接口查詢語言設計理念與示例 ### (1)文法：create -> with -> request 所用到的查詢文法如下（通常從上往下依次操作，順序不強制）： 操作|參數|是否必須|是否可重復調用|作用說明 ---|---|---|---|--- create|無|必須|可以，重復調用時新建一個實例，非單例模式|需要先調用此操作創建一個接口實例 withHost|接口域名|必須|可以，重復時會覆蓋|設置接口域名，如：http://demo.phalapi.net/ withFilter|過濾器|可選|可以，重復時會覆蓋|設置過濾器，與服務器的DI().filter對應，需要實現PhalApiClientFilter接口 withParser|解析器|可選|可以，重復時會覆蓋|設置結果解析器，僅當不是JSON返回格式時才需要設置，需要實現PhalApiClientParser接口 reset|無|通常必須|可以|重復查詢時須重置請求狀態，包括接口服務名稱、接口參數和超時時間 withService|接口服務名稱|通常必選|可以，重復時會覆蓋|設置將在調用的接口服務名稱，如：Default.Index withParams|接口參數名、值|可選|可以，累加參數|設置接口參數，此方法是唯一一個可以多次調用并累加參數的操作 withTimeout|超時時間|可選|可以，重復時會覆蓋|設置超時時間，單位毫秒，默認3秒 request|無|必選|可以，重復發起接口請求|最后執行此操作，發起接口請求 ### (2)JAVA示例 以JAVA版本為例，演示如何調用： 最簡單的調用，也就是默認接口的調用： ```javascript PhalApiClientResponse response = PhalApiClient.create() .withHost("http://demo.phalapi.net/") //接口域名 .request(); //發起請求 ``` 通常的調用，即有設置接口服務名稱、接口參數和超時： ```javascript PhalApiClientResponse response = PhalApiClient.create() .withHost("http://demo.phalapi.net/") .withService("Default.Index") //接口服務 .withParams("username", "dogstar") //接口參數 .withTimeout(3000) //接口超時 .request(); ``` 高級復雜調用，即設置了過濾器、解析器的操作： ```javascript PhalApiClientResponse response = PhalApiClient.create() .withHost("http://demo.phalapi.net/") .withService("Default.Index") .withParser(new PhalApiClientParserJson()) //設置JSON解析，默認已經是此解析，這里僅作演示 .withParams("username", "dogstar") .withTimeout(3000) .request(); ``` ## 6.1.3 更好的建議 ### (1)不支持面向對象的實現方式 此接口查詢的用法是屬于基礎的用法，其實現與宿主語言有強依賴關系，在不支持面向對象語言中，如javascript，可以使用函數序列的方式，如： ```javascript create(); withHost('http://demo.phalapi.net/'); withService('Default.Index'); withParams('username', 'dogstar'); withTimeout(3000); var rs = request(); ``` ### (2)封裝自己的接口實例 通常，在一個項目里面我們只需要一個接口實例即可，但此語言沒默認使用單例模式，是為了大家更好的自由度。 基于此，大家在項目開發時，可以再進行封裝：提供一個全局的接口查詢單例，并組裝基本的接口公共查詢屬性。 即分兩步：初始化接口實例，以及接口具體的查詢操作。 如第一步先初始化： ```javascript PhalApiClient client = PhalApiClient.create() .withHost("http://demo.phalapi.net/") .withParser(new PhalApiClientParserJson()); ``` 第二步進行具體的接口請求： ```javascript PhalApiClientResponse response = client.reset() #重復查詢時須重置 .withService("Default.Index") .withParams("username", "dogstar") .withTimeout(3000) .request(); ``` 這樣，在其他業務場景下就不需要再重復設置這些共同的屬性（如過濾器、解析器）或者共同的接口參數。 ### (3)超時重試 當接口請求超時時，統一返回 ret = 408，表示接口請求超時。此時可進行接口重試。 如： ```javascript PhalApiClient client = PhalApiClient.create() .withHost("http://demo.phalapi.net/") PhalApiClientResponse response = client.request(); if (response.getRet() == 408) { response = client.request(); //請求重試 } ```