PhalApi 2.x 的SDK包

SDK包列表

已经支持的SDK有:

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

外部DSL

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

  1. create
  2. withHost host
  3. withFilter filter
  4. withParser parser
  5. reset #特别注意:重复查询时须重置请求状态
  6. withService service
  7. withParams paramName1 paramValue1
  8. withParams paramName2 paramValue2
  9. withParams ... ...
  10. withTimeout timeout
  11. 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版本为例,演示如何调用:最简单的调用,也就是默认接口的调用:

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

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

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

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

  1. PhalApiClientResponse response = PhalApiClient.create()
  2. .withHost("http://demo.phalapi.net/")
  3. .withService("Site.Index")
  4. .withParser(new PhalApiClientParserJson()) //设置JSON解析,默认已经是此解析,这里仅作演示
  5. .withParams("username", "dogstar")
  6. .withTimeout(3000)
  7. .request();

更好的建议

不支持面向对象的实现方式

此接口查询的用法是属于基础的用法,其实现与宿主语言有强依赖关系,在不支持面向对象语言中,如javascript,可以使用函数序列的方式,如:

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

封装自己的接口实例

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

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

如第一步先初始化:

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

第二步进行具体的接口请求:

  1. PhalApiClientResponse response = client.reset() #重复查询时须重置
  2. .withService("Site.Index")
  3. .withParams("username", "dogstar")
  4. .withTimeout(3000)
  5. .request();

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

超时重试

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

如:

  1. PhalApiClient client = PhalApiClient.create()
  2. .withHost("http://demo.phalapi.net/")
  3. PhalApiClientResponse response = client.request();
  4. if (response.getRet() == 408) {
  5. response = client.request(); //请求重试
  6. }

原文: http://docs.phalapi.net/#/v2.0/sdk