PHP-编程规范-基础版

@命名规范

• 所有 class, interface, trait 文件的命名都使用 驼峰法（Camel Case）

CacheManager.php, LogInterface.php, LogTrait.php

• 常量必须是全部用 大写 的单词，并且单词之间使用 _ 分隔

<?php

defined('APP_NAME') || define('APP_NAME', 'adamtyn');

const APP_VERSION = 'v1.0.1';

• 公共函数的命名使用 小写单词加下划线（Snake Case）的方式

<?php

if (!function_exists('yield_method')) {
    /**
     * @author AdamTyn
     * @description 协程处理迭代器
     *
     * @param Iterator $iterator
     * @return int
     */
    function yield_method(Iterator $iterator)
    {
        foreach ($iterator as $key => $value) {
            yield $key => $value;
        }

        return 0;
    }
}

• 类名称、类属性、类方法、接口名称、trait名称、普通变量名称均使用 驼峰法（Camel Case）

<?php

namespace AT;

class CacheManager implements LogInterface
{
    use LogTrait;

    /**
     * @var int
     */
    private $currentTime;

    /**
     * @var string
     */
    private $name;

    public function __construct(string $name)
    {
        $baseName = 'at_';

        $this->name = $baseName . $name;
      
        $this->currentTime = time();
    }

    /**
     * @return int
     */
    public function getCurrentTime(): int
    {
        return $this->currentTime;
    }
}

@接口规范

• 请求

请求头	含义	示例值
Client-Source	客户端来源信息	bazirim-android, bazirim-ios, bazirim-h5
Client-Version	客户端版本信息	v1.0.0-test, v2.3.1-release
Client-Locale	客户端语言类型	uey, zh_cn

• 响应

字段	类型	描述
code	String	响应的状态码
message	String	状态码对应的描述信息
meta	Object	数据元信息。譬如时间戳 timestamp，语言类型 locale 等
data	Mixed	响应返回的数据。可能有多种类型，譬如对象 Object，数组 Array 等

1. 单个资源的响应数据示例

{
   "code": "00200",
   "message": "success.",
   "meta": {
       "locale": "zh_cn",
       "timestamp": 1594828800,
       "version": "v1" // 接口版本(string)
   },
   "data": {
       "user_name": "adamtyn",
       "user_id": 1
   }
}

2. 带分页的响应数据示例

{
   "code": "00200",
   "message": "success.",
   "meta": {
       "locale": "zh_cn",
       "timestamp": 1594828800,
       "version": "v1"
   },
   "data": {
       "scroll": false, 
       "pagination": {
           "count": 1,
           "size": 12,
           "total": 1, 
           "current": 1, 
           "last": 1 // 最后页号(int)
       },
       "list": [ // 单页数据集(array)
           {
               "user_name": "adamtyn",
               "user_id": 1
           }
       ]
   }
}

3. 特别的，当有必要 表示资源不存在 时，需要保证接口响应字段的值是 null 或 [] 中的一种

{
   "code": "00200",
   "message": "success.",
   "meta": {
       "locale": "zh_cn",
       "timestamp": 1594828800,
       "version": "v1"
   },
   "data": null // or []
}

4. 规定 code 统一使用 长度为5的数字字符串，其中 0, 00开头的 code 为 系统预留，业务接口 不可定义，不可覆盖，但是业务中含义相同的状态可以共用一个 code

状态码	含义
00200	正常响应
00300	未知的客户端来源
04010	未登录
04011	已过期
04030	无权限
40000	错误的请求数据

5. 只要涉及到资源的修改和新增，必须要保证接口的 幂等性

1.不可以重复插入意义相同的数据
2.任意次数的请求，资源状态修改后的必须永远保持一致

6. 涉及分页输出的接口，后端必须 限制单页数量 per_page 请求参数的上限