1. API开发

1.1. 文件位置

  • 文件统一放在如下位置：
    app/{$app_name}/api/

1.2. API注册

  • 注册文件

    config/apis.php

  • 注册格式

      'api的method' => ['uses' => '调用哪个类@哪个方法', 'version'=>['支持的版本号']],

      'item.search' => ['uses' => 'sysitem_api_item_search@getList', 'version'=>['v1']],

  • API请求权限注册 API请求权限是注册给app的，比如topc应用可以请求systrade应用提供的api，需要注册如下信息：

    //表示topc可以调用systrade的api，并且每60秒可以调用1000次
  'depends'=>array (
       'topc' => array (
           'systrade' => array ( 'appName' => 'systrade', 'path' => '*', 'limit_count' => 1000, 'limit_seconds' => 60,),
       ),
  ),

    dev应用提供了一个命令：cmd dev:rpc depends_info命令可以获取当前代码的调用情况。直接将显示出来的数组复制到config/apis.php的depends项即可

1.3. API实现

  • CLASS格式
<?php
/**
 * ShopEx licence
 * - syscontent.content.get.info
 * - 用于获取文章的详情
 * @copyright Copyright (c) 2005-2016 ShopEx Technologies Inc. (http://www.shopex.cn)
 * @license   http://ecos.shopex.cn/ ShopEx License
 * @link      http://www.shopex.cn/
 * @author    shopex 2016-05-17
 */
class syscontent_api_getContentInfo {

    /**
     * api接口的名称
     * @var string
     */
    public $apiDescription = '获取文章详情';

    /**
     * 定义API传入的应用级参数
     * @desc 用于在调用接口前，根据定义的参数，过滤必填参数是否已经参入，并且定义参数的数据类型，参数是否必填，参数的描述
     * @return array 返回传入参数
     */
    public function getParams()
    {
        //接口传入的参数
        $return['params'] = array(
            'fields'     => ['type'=>'field_list', 'valid'=>'',         'title'=>'需要的字段', 'example'=>'', 'desc'=>'需要的字段'],
            'article_id' => ['type'=>'int',        'valid'=>'required', 'title'=>'文章id',    'example'=>'', 'desc'=>'文章id'],
        );

        return $return;
    }

    /**
     * 获取单个商品的详细信息
     * @desc 用于获取单个商品的详细信息
     * @return int article_id 文档ID
     * @return string title 文章标题
     * @return int modified 文章最后修改时间
     * @return string content 文章内容
     * @return int node_id 文章所属类目ID
     */
    public function getContentInfo($params)
    {
        $syscontentLibArticle = kernel::single('syscontent_article_article');
        try
        {
            $syscontentInfo = $syscontentLibArticle->getArticleInfo($params);

        }
        catch(Exception $e)
        {
            $msg = $e->getMessage();
            return $this->splash('error',null,$msg,true);
        }
        return $syscontentInfo;
    }

}

1.4. 约定

  • 一个文件只提供给一个接口使用

  • 类的注释

    将API定义文件config/apis.php中的api定义的uses别名带上，方便查找本api，便于开发， 例如

      /**
   * ShopEx licence
   * - syscontent.content.get.info
   * - 用于获取文章的详情
   * @copyright Copyright (c) 2005-2016 ShopEx Technologies Inc. (http://www.shopex.cn)
   * @license   http://ecos.shopex.cn/ ShopEx License
   * @link      http://www.shopex.cn/
   * @author    shopex 2016-05-17
   */

  • $apiDescription 接口的名称，例如

      /**
   * api接口的名称
   * @var string
   */
  public $apiDescription = '获取文章详情';

  • 入参方法

      function getParams()内定义的是入参需要检验的字段，共5个，

  [type=>'字段类型','valid'=>'验证规则','title'=>'字段名','example'=>'示例值','desc'=>'字段的详细描述']

  `valid`字段的验证规则参考文件config/validation.php

    例如：

      /**
   * 定义API传入的应用级参数
   * @desc 用于在调用接口前，根据定义的参数，过滤必填参数是否已经参入，并且定义参数的数据类型，参数是否必填，参数的描述
   * @return array 返回传入参数
   */
  public function getParams()
  {
      //接口传入的参数
      $return['params'] = array(
          'fields'     => ['type'=>'field_list', 'valid'=>'',         'title'=>'需要的字段', 'example'=>'', 'desc'=>'需要的字段'],
          'article_id' => ['type'=>'int',        'valid'=>'required', 'title'=>'文章id',    'example'=>'', 'desc'=>'文章id'],
      );

      return $return;
  }

  • 响应方法

      这里具体调用的api方法的注释有三个要求,例如上面例子当中的 function getContentInfo($params)
  api方法的简单描述，如 `获取单个商品的详细信息`
  api方法的详细描述，如 `@desc 用于获取单个商品的详细信息`
  所有返回字段按照 `@return 返回类型(如int/string/array) 返回参数 返回参数描述`，如 `@return int node_id 文章所属类目ID`

    例如1

      /**
   * 获取单个商品的详细信息
   * @desc 用于获取单个商品的详细信息
   * @return int article_id 文档ID
   * @return string title 文章标题
   * @return int modified 文章最后修改时间
   * @return string content 文章内容
   * @return int node_id 文章所属类目ID
   */
  public function getContentInfo($params)
  {
      $syscontentLibArticle = kernel::single('syscontent_article_article');
      try
      {
          $syscontentInfo = $syscontentLibArticle->getArticleInfo($params);

      }
      catch(Exception $e)
      {
          $msg = $e->getMessage();
          return $this->splash('error',null,$msg,true);
      }
      return $syscontentInfo;
  }

    返回的参数如果有数组,数组主键和数组下的每个字段都写出来

    例如2

      /**
   * 获取活动报名列表
   * @desc 用于获取活动报名列表
   * @return array data 活动报名列表
   * @return int data[].id 主键ID
   * @return int data[].shop_id 店铺ID
   * @return int data[].activity_id 活动ID
   * @return string data[].verify_status 审核状态
   * @return bool data[].valid_status 有效状态
   * @return string data[].refuse_reason 拒绝原因
   * @return timestamp data[].modified_time 报名最后更新时间
   * @return string count 返回数据数量
   */
  public function registerList($params)
  {
      # code...
  }

1.5. API查询

results matching ""

    No results matching ""