1.23.1 请求

把我们后台的API想象成一个函数,那么请求的参数就是我们的参数列表;而接口响应的数据则对应函数返回的结果。

对于请求,正如前面所看到的,我们可以使用$_GET,也可以使用$_POST,也可以两者都使用,还可以在测试时自己指定模拟的请求数据包。

或者,在实际项目开发中,我们还需要根据自身的需求,跟我们自己的客户端作一些约定。如通常地,我们会要求客户端 service参数必须用GET方式 ,以便服务器返回500时定位接口服务位置。对此,简单的我们把$_POST['service']去掉即可,如在入口文件前面添加:

  1. unset($_POST['service']); //只接收GET方式的service参数

(1) 在index.php入口处指定数据源

很多时间,不同的项目对数据接收有不同的需求。如简单地,强制统一使用$_POST参数,我们可以这样在入口处进行代码调整:

  1. //vim ./index.php
  2. DI()->request = new PhalApi_Request($_POST);

对于复杂的情况,如需要使用post_raw数据,则可以继承PhalApi_Request实现相应的数据源解析。如:

  1. class My_Request extends PhalApi_Request{
  2. public function __construct($data = NULL) {
  3. parent::__construct($data);
  4. // json处理
  5. $this->post = json_decode(file_get_contents('php://input'), TRUE);
  6. // 普通xml处理
  7. $this->post = simplexml_load_string (
  8. file_get_contents('php://input'),
  9. 'SimpleXMLElement',
  10. LIBXML_NOCDATA
  11. );
  12. $this->post = json_decode(json_encode($this->post), TRUE);
  13. }
  14. }

然后在子类实现对各类参数的数据源的准备。可以说,PhalApi_Request::__construct()构造函数用于初始化各类辅助侯选的数据源,而PhalApi_Request::getData()则用于生成主要默认的数据源。

(2) 单元测试时指定数据源

在进行单元测试时,我们需要模拟接口的请求动作,也需要提供接口参数。这时的参数的指定更为灵活。可通过以下代码来实现,即:

  1. //数据源
  2. $data = array(...);
  3. DI()->request = new PhalApi_Request($data);

或者使用PhalApi封装的测试类来快速模拟调用接口:

  1. public function testIndexByRunner()
  2. {
  3. //Step 1. 构建请求URL
  4. $url = 'service=Default.Index&username=dogstar';
  5. $params = array();
  6. //Step 2. 执行请求
  7. $rs = PhalApi_Helper_TestRunner::go($url, $params);
  8. }

(3) 接口数据的加密传送

有时,出于安全性的考虑,项目需要对请求的接口参数进行对称加密传送。这时可以通过重载PhalApi_Request::genData()来轻松实现。假设,我们现在需要把全部的参数base64编码序列化后通过$_POST['data']来传递,则相应的解析代码如下。

第一步,先定义自己的扩展请求类,在里面完成对称解析的动作:

  1. <?php
  2. class Common_Request extends PhalApi_Request {
  3. public function genData($data) {
  4. if (!isset($data) || !is_array($data)) {
  5. $data = $_POST; //改成只接收POST
  6. }
  7. return isset($data['data']) ? base64_decode($data['data']) : array();
  8. }
  9. }

第二步,在index.php入口文件中重新注册请求类(即添加以下代码):

  1. //重新注册request
  2. DI()->request = 'Common_Request';

然后,就可以轻松实现了接口参数的对称加密传送。至此,你也许已经发现:指定数据源和对称加密是可以结合来使用的。

(4) 接口参数级别的数据源

除了可以指定全局的接口数据源外,还可以进行更细致的配置,即为某个接口参数指定使用$GET、$_POST、$_COOKIE、$_SERVER、$_REQUEST或头部等其他数据源。

其使用方式是在配置接口参数规则时,使用source配置来指定当前参数的数据源,如指定用户在登录时,用户名使用$_GET、密码使用$_POST。

  1. public function getRules() {
  2. return array(
  3. 'login' => array(
  4. 'username' => array('name' => 'username', 'source' => 'get'),
  5. 'password' => array('name' => 'password', 'source' => 'post'),
  6. ),
  7. );
  8. }

这样,PhalApi框架就会从$_GET中提取username参数,从$_POST中提取password参数。

目前支持的source与对应的数据源映射关系如下:

source 对应的数据源
post $_POST
get $_GET
cookie $_COOKIE
server $_SERVER
requset $_REQUEST
header $_SERVER['HTTP_X']

因此,这样就可以轻松、更自由获取不同来源的参数。以下是一些常用的配置示例。

  1. // 获取HTTP请求方法,判断是POST还是GET
  2. 'method' => array('name' => 'REQUEST_METHOD', 'source' => 'server'),
  3. // 获取COOKIE中的标识
  4. 'is_new_user' => array('name' => 'is_new_user', 'source' => 'cookie'),
  5. // 获取HTTP头部中的编码,判断是否为utf-8
  6. 'charset' => array('name' => 'Accept-Charset', 'source' => 'header'),

若需要扩展项目自定义的映射关系,则可以重载PhalApi_Request::getDataBySource($source)方法,如:

  1. class My_Request extends PhalApi_Request {
  2. protected function &getDataBySource($source) {
  3. if (strtoupper($source) == 'stream') {
  4. // TODO 处理二进制流
  5. }
  6. return parent::getDataBySource($source);
  7. }
  8. }

然后,便可在项目中这样配置使用二进制流的数据源。

  1. // 从二进制流中获取密码
  2. 'password' => array('name' => 'password', 'source' => 'stream'),

若配置的source为无效或非法时,则会抛出异常。如故意配置一个错误的数据源source为NOT_FOUND。

  1. 'password' => array('name' => 'password', 'source' => 'NOT_FOUND'),

在请求接口时,会遇到这样的异常提示返回。

  1. {
  2. "ret": 500,
  3. "data": [],
  4. "msg": "服务器运行错误: 参数规则中未知的数据源:NOT_FOUND"
  5. }
温馨提示:以上功能需要PhalApi 1.4.0 及以上版本支持。

1.23.2 响应

当前默认使用JSON的格式返回,但项目需要其他返回格式也是可以的。只需要实现PhalApi_Response抽象中的formatResult($result)格式化返回结果,然后也是重新注册DI()->response服务即可。如:

(1) JSONP的返回

在H5页面中,我们可能会需要用到JSONP的返回,所以这里默认提供了这种格式的支持。

在入口文件中,添加:

  1. //支持JsonP的返回
  2. if (!empty($_GET['callback'])) {
  3. DI()->response = new PhalApi_Response_JsonP($_GET['callback']);
  4. }

在接口访问时再带上&callback=XXX参数即可。

这里在创建响应服务时,可以看到是用了回调函数的名字进行初始化。考虑到会存在XSS(跨站脚本攻击),对回调函数要进行相应的过滤,可以用黑名单或者白名单的方式。黑名单方式暂时还没提供,白名单相对简单但需要项目自己实现,如:

  1. class Common_JsonP extends PhalApi_Response_JsonP {
  2. protected function clearXss($callback) {
  3. return in_array($callback, array('fun1', 'func2', 'func3')) ? $callback : '';
  4. }
  5. }

(2) 其他格式返回

如上面所述,当需要返回一种当前PhalApi没提供的格式时,可以:

  • 1、实现PhalApi_Response抽象中的formatResult($result)格式化返回结果
  • 2、重新注册DI()->response服务
    这里以扩展XML返回格式为例,简单说明。

首先,添加实现一个XML响应子类:

  1. <?php
  2. class Common_Response_XML extends PhalApi_Response {
  3. protected function formatResult($result) {
  4. return ArrayToXML::toXml($result);
  5. }
  6. }

关于ArrayToXML,请查看: 将PHP数组转成XML

然后,重新注册:

  1. DI()->response = new Common_Response_XML();

done!

原文: https://www.phalapi.net/wikis/1-23.html