PHP
<p>[TOC]</p>
<h3>命名规范</h3>
<blockquote>
<p>关于：方法名采用首字母小写的驼峰命名规范、变量名都用小驼峰
（对于老项目有指定命名规范的，需要遵循老项目规范，编辑时不要格式化其代码）
因为API部门的代码目前都是下划线的，<a href="https://open.onebound.cn/help/api/">https://open.onebound.cn/help/api/</a>
其他老项目也不统一 。</p>
<p>开发规范默认主要适用于onebuy系统开发更严格 ，其他项目作为参考</p>
</blockquote>
<ul>
<li>命名需要有意义</li>
</ul>
<pre><code class="language-php">// 错误示例
$a = 30;
// 正确示例
$age = 30;</code></pre>
<ul>
<li>命名需要简洁明了，不应过长</li>
</ul>
<pre><code class="language-php">// 错误示例
$internationalTransshipmentLogistics = [];
// 正确示例
$logistics = [];</code></pre>
<ul>
<li>方法名采用首字母小写的驼峰命名规范，类名采用首字母大写的驼峰命名规范，方法名首词采用动词加驼峰</li>
</ul>
<pre><code class="language-php">// 错误示例
public function get_total_price()
{
// method body
}
// 正确示例
public function getTotalPrice()
{
// method body
}
// 错误示例
class bizcode
{
// class body
}
// 正确示例
class BizCode
{
// class body
} </code></pre>
<ul>
<li>变量名都用小驼峰</li>
</ul>
<pre><code>// 错误示例
$total_price = 0;
// 正确示例
$totalPrice = 0;</code></pre>
<ul>
<li>常量定义大写,单词间以下划线分隔</li>
</ul>
<pre><code>// 错误示例
define('app_path', __DIR__ . '/../application/');
// 正确示例
define('APP_PATH', __DIR__ . '/../application/');</code></pre>
<ul>
<li>PHP关键字都小写， 常量 true 、false 和 null 也都小写</li>
</ul>
<pre><code>// 错误示例
FOREACH ($students AS $student) {
}
// 正确示例
foreach ($students as $student) {
}
// 错误示例
IF ($age > 18) {
// condition body
} ELSE {
// condition body
}
// 正确示例
if ($age > 18) {
// condition body
} else {
// condition body
}
// 错误示例
public function replaceStr(){
// method body
return NULL;
}
// 正确示例
public function replaceStr(){
// method body
return null;
}
</code></pre>
<h3>类(class), 属性(properties), 方法(methods)</h3>
<p>namespace以及use声明</p>
<ul>
<li>namespace 声明后必须插入一个空白行。</li>
<li>所有use必须在namespace 后声明。</li>
<li>每个类必须要有一个namespace。thinkphp中，统一通过use去引入一个类，不要通过include去引入</li>
</ul>
<p>extends 和 implements</p>
<ul>
<li>关键词 extends 和 implements必须写在类名称的同一行。</li>
</ul>
<pre><code class="language-php">namespace ob/taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi extends ObApi {
// class body
}
</code></pre>
<p>属性</p>
<ul>
<li>类的属性命名必须遵循小写字母开头的驼峰式命名规范 ($camelCase)。</li>
<li>必须对所有属性设置访问控制（如，public，protect，private）。</li>
<li>一定不可使用关键字 var 声明一个属性。</li>
<li>每条语句一定不可定义超过一个属性。</li>
<li>定义属性时先常量属性再变量属性，先public 然后 protected，最后private。</li>
</ul>
<pre><code>namespace ob/taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi extends ObApi {
const BASE_URL = 'https://api-1.onebound.cn';
public $tp = 'taobao';
protected $api_key = '';
protected $api_secret = '';
private $api_list = ['get_item','search','upimage'];
}
</code></pre>
<p>方法</p>
<ul>
<li>方法名称必须符合 camelCase() 式的小写字母开头驼峰命名规范。</li>
<li>所有方法都必须设置访问控制（如，public，protect，private）。</li>
</ul>
<pre><code>namespace ob/taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi extends ObApi {
const BASE_URL = 'https://api-1.onebound.cn';
public $tp = 'taobao';
protected $api_key = '';
protected $api_secret = '';
private $api_list = ['get_item','search','upimage'];
public function getItem(){
// methods body
}
public function search(){
// methods body
}
private function request($url,Array $params = []){
// methods body
}
}
</code></pre>
<p>方法参数</p>
<ul>
<li>方法参数名称必须符合 camelCase 式的小写字母开头驼峰命名规范</li>
<li>有默认值的参数，必须放到参数列表的末尾。</li>
<li>如果参数类型为对像必须指定参数类型为具体的类名。</li>
<li>如果参数类型为array必须指定参数类型为array。如$params。</li>
</ul>
<pre><code>namespace ob/taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi extends ObApi {
private function request($url,array $params = []){
// methods body
}
}
</code></pre>
<h3>ThinkPHP/Fastadmin规范</h3>
<p>目录和文件</p>
<ul>
<li>目录使用小写+下划线；</li>
<li>类文件采用驼峰法命名（首字母大写），类名与类文件名保持一致，其它文件采用小写+下划线命名</li>
<li>目录规范
<ul>
<li>公共助手函数 统一放application/common.php</li>
<li>公共助手类 统一放extend目录下(参考extend/fast)</li>
<li>Queue队列统一放 application/job目录下</li>
</ul></li>
</ul>
<p>变量、函数、类、属性命名</p>
<ul>
<li>变量命名统一以 首字母小写，驼峰体命名，例如：$total_price应写为：$totalPrice</li>
<li>类的命名采用驼峰法（首字母大写），例如 User、UserType，默认不需要添加后缀，例如UserController应该直接命名为User；</li>
<li>函数的命名使用小写字母和下划线（小写字母开头）的方式，例如 get_client_ip；</li>
<li>方法的命名使用驼峰法（首字母小写），例如 getUserName；</li>
<li>属性的命名使用驼峰法（首字母小写），例如 tableName、instance；</li>
<li>以双下划线“<strong>”打头的函数或方法作为魔术方法，例如 </strong>call 和 __autoload；</li>
</ul>
<p>常量和配置</p>
<ul>
<li>常量以大写字母和下划线命名，例如 APP_PATH和 THINK_PATH；</li>
<li>配置参数以小写字母和下划线命名，例如 url_route_on 和url_convert；</li>
</ul>
<h3>注释相关</h3>
<p>在方法、函数前需注释该方法的作者，时间，接收参数，返回值类型、方法作用等</p>
<ul>
<li>类注释</li>
</ul>
<pre><code>namespace ob\taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi(){
// class body
}</code></pre>
<ul>
<li>属性注释</li>
</ul>
<pre><code>namespace ob\taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi(){
/**
* APPID，可以在XX申请
* @var string
*/
public $app_id = '';
}</code></pre>
<ul>
<li>方法注释</li>
</ul>
<pre><code>namespace ob\taobao;
/**
* 获取淘宝商品相关信息类
* @author Cole 2022-03-02 13:37
* @version 1.0.0
*/
class TaobaoApi(){
// class body
/**
* 请求淘宝商品详情接口
* @author Cole 2022-03-02 13:37
* @params $num_iid {String} 淘宝商品ID
* @return Object {title: '',num_iid: '', sku: {} ....}
* @version 1.0.0
* @example /api/taobao_api/item/num_iid/659585269247
*/
public function Item($num_iid){
// todo
return []
}
}</code></pre>
<ul>
<li>注释相关参数参考以下表格：</li>
</ul>
<table>
<thead>
<tr>
<th>注释名</th>
<th>语法</th>
<th>含义</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td>@author</td>
<td>@author 作者信息 [附属信息：如邮箱、日期]</td>
<td>描述此函数作者的信息</td>
<td>@author Cole 2022-03-02 13:37</td>
</tr>
<tr>
<td>@params</td>
<td>@param 参数名 {参数类型} 描述信息</td>
<td>描述参数的信息</td>
<td>@param name {String} 传入名称</td>
</tr>
<tr>
<td>@return</td>
<td>@return {返回类型} 描述信息</td>
<td>描述返回值的信息</td>
<td>@return {Object} obapi返回的商品详情信息 {title: '',num_iid: '', sku: {} ....}</td>
</tr>
<tr>
<td>@version</td>
<td>@version XX.XX.XX</td>
<td>描述此函数的版本号</td>
<td>@version 1.0.3</td>
</tr>
<tr>
<td>@example</td>
<td>@example 示例代码</td>
<td>演示函数使用</td>
<td>@example requestTaobaoItemApi('659585269247')]</td>
</tr>
</tbody>
</table>
<h3>Fastadmin API模块注释规则</h3>
<p>开发api模块下的人员写注释时，参考上述规则，并增加下述注释规则，有重复的以以下规则为准，例如@return、@params</p>
<ul>
<li>控制器注释</li>
</ul>
<table>
<thead>
<tr>
<th>名称</th>
<th>描述</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td>@ApiSector</td>
<td>API分组名称</td>
<td>(测试分组)</td>
</tr>
<tr>
<td>@ApiRoute</td>
<td>API接口URL，此@ApiRoute只是基础URL</td>
<td>(/api/test)</td>
</tr>
<tr>
<td>@ApiInternal</td>
<td>忽略的控制器,表示此控制将不加入API文档</td>
<td>无</td>
</tr>
<tr>
<td>@ApiWeigh</td>
<td>API方法的排序,值越大越靠前</td>
<td>(99)</td>
</tr>
</tbody>
</table>
<ul>
<li>控制器方法注释</li>
</ul>
<table>
<thead>
<tr>
<th>名称</th>
<th>描述</th>
<th>示例</th>
</tr>
</thead>
<tbody>
<tr>
<td>@ApiTitle</td>
<td>API接口的标题,为空时将自动匹配注释的文本信息</td>
<td>(测试标题)</td>
</tr>
<tr>
<td>@ApiSummary</td>
<td>API接口描述</td>
<td>(测试描述)</td>
</tr>
<tr>
<td>@ApiRoute</td>
<td>API接口地址,为空时将自动计算请求地址</td>
<td>(/api/test/index)</td>
</tr>
<tr>
<td>@ApiMethod</td>
<td>API接口请求方法,默认为GET</td>
<td>(POST)</td>
</tr>
<tr>
<td>@ApiSector</td>
<td>API分组,默认按钮控制器或控制器的@ApiSector进行分组</td>
<td>(测试分组)</td>
</tr>
<tr>
<td>@ApiParams</td>
<td>API请求参数,如果在@ApiRoute中有对应的{@参数名}，将进行替换</td>
<td>(name="id", type="integer", required=true, description="会员ID")</td>
</tr>
<tr>
<td>@ApiHeaders</td>
<td>API请求传递的Headers信息</td>
<td>(name=token, type=string, required=true, description="请求的Token")</td>
</tr>
<tr>
<td>@ApiReturn</td>
<td>API返回的结果示例</td>
<td>({"code":1,"msg":"返回成功"})</td>
</tr>
<tr>
<td>@ApiReturnParams</td>
<td>API返回的结果参数介绍</td>
<td>(name="code", type="integer", required=true, sample="0")</td>
</tr>
<tr>
<td>@ApiReturnHeaders</td>
<td>API返回的Headers信息</td>
<td>(name="token", type="integer", required=true, sample="123456")</td>
</tr>
<tr>
<td>@ApiInternal</td>
<td>忽略的方法,表示此方法将不加入文档</td>
<td>无</td>
</tr>
<tr>
<td>@ApiWeigh</td>
<td>API方法的排序,值越大越靠前</td>
<td>(99)</td>
</tr>
</tbody>
</table>
<p>参考</p>
<pre><code><?php
namespace app\api\controller;
use app\common\controller\Api;
/**
* 优惠券
* @version 1.1
*
*/
class Coupon extends Api
{
protected $noNeedLogin = '';
protected $noNeedRight = '*';
/**
* 优惠券列表
* @author Cole 2022-03-02 13:37
* @version 1.0.3
* @ApiTitle (优惠券列表)
* @ApiSummary (获取优惠券列表)
* @ApiMethod (GET)
* @ApiRoute (/api/Coupon/lists)
* @ApiParams (name="page", type="integer", required=true, description="页数")
* @ApiParams (name="size", type="integer", required=false, description="每页个数(默认10)")
* @ApiParams (name="getway", type="string", required=false, description="获取方式（1.积分兑换，2奖励，3节日活动赠送）")
* @ApiParams (name="status", type="string", required=false, description="状态 (默认全部 1未使用 2已使用 3已过期)")
* @ApiParams (name="usetype", type="string", required=false, description="用途方式：0任何地方 1订单 2运单 3充值")
* @ApiReturnParams (name="code", type="integer", required=true, sample="0")
* @ApiReturnParams (name="msg", type="string", required=true, sample="返回成功")
* @ApiReturnParams (name="data", type="object", sample="{}", description="优惠劵对象数组集合")
* @ApiReturn ({
"code":"1",
"msg":'返回成功",
"data":{
"lists":[
{
"coupon_id": "65",
"sn": "20190506165811404",
"user_id": "33",
"getway": "1",
"usetype": "0",
"endtime": "1559725091",
"createtime": "1557133091",
"money": "100",
"state": "1",
"coupon_rule_id": "0",
"type":"1",
"name":"100元抵扣券",
"total":"",
"discount":"1"
}
]
}
})
*/
public function lists()
{
// methods body
return $this->apiReturn($this->logicCoupon->getCouponList($where, true, 'createtime desc', $size));
}
}
</code></pre>
<h3>引用文档</h3>
<p><a href="https://www.kancloud.cn/thinkphp/thinkphp5-guide/90124">ThinkPHP5命名规范</a>
<a href="https://doc.fastadmin.net/doc/163.html">Fastadmin 一键生成API文档</a></p>