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 ""