3.2 SDk包的使用 · PhalApi 2.x 開發文檔

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