基于接口查询语言的SDK包

6.1.1 用一句话来描述接口请求

为了给客户端统一接口请求调用的规范性、流畅性和简单易懂，我们特别为此使用了内部领域特定语言： 接口查询语言（Api Structured Query Language） 。

从外部DSL的角度来看待接口查询的操作

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

所用到的查询文法如下（通常从上往下依次操作，顺序不强制）：

(2)JAVA示例

以JAVA版本为例，演示如何调用：
最简单的调用，也就是默认接口的调用：

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

通常的调用，即有设置接口服务名称、接口参数和超时：

PhalApiClientResponse response = PhalApiClient.create()
       .withHost("http://demo.phalapi.net/")
       .withService("Default.Index")          //接口服务
       .withParams("username", "dogstar")     //接口参数
       .withTimeout(3000)                     //接口超时
       .request();

高级复杂调用，即设置了过滤器、解析器的操作：

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，可以使用函数序列的方式，如：

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

(2)封装自己的接口实例

通常，在一个项目里面我们只需要一个接口实例即可，但此语言没默认使用单例模式，是为了大家更好的自由度。
基于此，大家在项目开发时，可以再进行封装：提供一个全局的接口查询单例，并组装基本的接口公共查询属性。

即分两步：初始化接口实例，以及接口具体的查询操作。

如第一步先初始化：

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();

这样，在其他业务场景下就不需要再重复设置这些共同的属性（如过滤器、解析器）或者共同的接口参数。

(3)超时重试

当接口请求超时时，统一返回 ret = 408，表示接口请求超时。此时可进行接口重试。

如：

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

PhalApiClientResponse response = client.request();

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