编码规范 - 简书

PHP 编码规范

命名篇

变量命名
- 所有字母都使用小写；对于一个变量使用多个单词的，使用"_"作为每个词的间隔
- 例如：

$user_name = "tony";
$red_rose_price = 123;

常量命名
- 所有字母使用大写；多个单词间使用"_"作为间隔
- 例如：

define('ALI_TIMESTAMP',365*24*60*60);
define('TIMING_SERVER_NAME', '106.31.89.92');

类命名
- 大驼峰命名法。以大写字母开头，多个单词组成的变量名，单词之间不用间隔，各个单词首字母大写
- 例如：

class LearningRoomController extends BaseController
{
}

方法或函数
- 小驼峰命名法。以小写字母开头，多个单词组成的变量名，单词之间不用间隔，各个单词首字母大写
- 例如：

function postFeed() 
{
    //业务逻辑
}

class LearningRoomController extends BaseController
{
    public function postFeed()
    {
        //业务逻辑
    }
}

数据库表命名
- 表名均使用小写字母；
- 对于多个单词组成的表名，使用_间隔
- 例如：

t_learning_feed_image
t_learning_farm_user_study_record

表字段命名
- 均使用小写字母；
- 对于多个单词组成的字段，使用_间隔
- 例如：

feed_id
actual_score
un_goal_day_count

风格篇

代码缩进
- 使用4个空格作为缩进，而不使用tab缩进
大括号{ }
- 结构控制代码编写，如if、for、while、switch等结构，大括号不换行
- 类、方法、函数大括号换行

for ($i = 1; $i < 10; $i++) {

}

if ($a > 1) {

}

foreach ($arr as $key => $value) {

}

function postFeed()
{

}

class A 
{
    public function a() 
    {

    }
}

小括号( ) 与运算符
- 左括号的右边，右括号的左边不加空格
- 每个逗号"," 分号";" 逻辑运算符">" "=" ">=" "<" 等等，前面不空格，后面空格

class A 
{
    public function a($paramsOne, $paramsTwo, $paramsThree) 
    {
        for ($i = 1; $i <= 10; $i++) {
            
        }
    }
}

switch break continue
- switch 语句每个case后面要有break；最后必须要有default模块
- 在多层嵌套语句中使用break continue 时要注意层级关系，switch的case结构会被当做一层


for ($i = 1; $i <= 10; $i++) {
    switch ($i) {
        case 1:
            echo 123;
            break;
        case 2:
            echo "nihao";
            break;
        case 8:
            break;//如果想中断for循环 则要使用 break 2; continue 同理
        default:
            echo "gan!";
    }
}

注释篇

类注释

/** 
* @ Purpose: 
* 访问数据库的类，以ODBC作为通用访问接口 
* @Author: Forrest Gump gump@crtvu.edu.cn 
* @Modifications: 
* No20020523-100: 
* odbc_fetch_into()参数位置第二和第三个位置调换 
* John Johnson John@crtvu.edu.cn 
* @See: (参照) 
*/ 
class Database 
{ 
…… 
}

函数注释

/** 
* @Purpose: 
* 执行一次查询 
* 
* @Param: string $queryStr SQL查询字符串 
* @Param: string $username 用户名
* 
* @Author: Michael Lee
*
* @Return: mixed 查询返回值（结果集对象） 
*/ 
function abc($queryStr,$username)
{……}

单行注释尽量写在代码上一行，而不是行尾

//定义一个用户名
$user_name = "Tony";

业务篇

数据库部分
- 1.所有新增数据表，表结构修改，必须严格遵守数据库建表规范，且由后台，微服务，PHP三组组长评审通过以后才能予以修改，且必须写明字段注释。修改完成以后必须告知所有服务端人员以及数据组相关人员。
- 2.每次上线，应跟随代码提交所有的SQL语句，并做对应业务说明。SQL语句必须使用索引，而且要提前预估大数据量可能会导致的问题。
- 3.对于测试数据库，如果开发和测试的时候有特殊需要，改完以后必须要予以恢复，以保证测试服数据的完整性。禁止通过任何方式私自改动生产环境数据库数据，必须经过审批且通过。
- 4.禁止在循环里面嵌套查询。
- 5.尽量避免连表查询，如果实在要连表查，不要超过2张表。
- 6.避免重复查询。在一次请求的生命周期中，避免多次重复查询同一组数据。可以通过传参的方式将需要使用的数据传达给后面的函数

代码部分
- 所有表model必须存放在model 文件夹中
- 业务实现写在service层，controller只做业务拼接
- 避免写超过4层嵌套的if else 逻辑嵌套，复杂的逻辑拆分成多个方法，以提高代码可读性。
- 复杂业务必须要先做好设计方案和预演。如果涉及多方，必须要一起开会讨论，确定方案
- 业务设计要尽量减少数据库查询，尽量减少接口调用，尽量不返回多余数据的原则。对于可能会频繁访问的接口，可以多使用缓存。
- 相同业务代码要尽量可以复用，组内人员在开发之前要沟通好，不要相同的代码写很多遍。但是也要注意，如果业务有不同，也不要强行复用，该区分的时候也要做好区分。如果有不确定的地方，可以一起讨论。
Git版本管理部分
- 严格按照git分支管理策略，任何临时的需求或者小的改动，都要拉分支做开发。不同需求使用不同分支，最后按上线计划进行合并上线
- git的commit信息要简要描述清楚提交的内容，禁止提交mmm aaa 123等无意义的字符
- 合并代码采取提交merge request 方式。提交申请后，执行代码审查流程通过后方可合并。

开发部分
- 确保需求确认一致，各方实现方案互通后在开始开发，任何不明确的地方均要主动沟通确认并负责跟踪消息同步进度，确保需求的变更传达到每一环。
- 发现需求中流程走不通或者产品设计特别复杂的地方，要及时与产品沟通。讨论方案可行性或者研讨优化方案。
- 发挥主观能动性，积极推展项目进度，积极推进各方交流。不要只顾自己开发，造成互相等的情况。
- 要有deadline意识，遇到技术难点或者自己能力不足的地方及时与组长沟通，不要等到最后才上报，导致影响项目进度节点延期。
- 一定要注意数据的验证，使用数据前要做判空和类型鉴定，避免由于空对象，错误的数据类型导致抛出异常或者产生预期外的结果。例如数据库查询结果为空时，直接获取对象属性则会抛出异常。字符串搜索等函数要注意0和===的区别等等。
- 严格按照项目设计去开发，使用封装好的公共方法去做数据验证和结果返回，保证返回给客户端的数据类型的一致性。
- 所有接口一律要在showDoc上提供接口文档，标明用法，参数，返回值。对返回值中的数据要写明注释。
- 注释清晰。复杂的方法要有流程步骤注释，函数的参数要有注释，且写明参数类型。
  多次的redis操作尽量采取pipline去操作，减少IO。尽可能的多使用缓存，同时要注意缓存穿透，雪崩等常见问题。
接口设计
- 接口参数尽量少，格式简单，避免多层嵌套参数如数组，json字符串（特殊情况除外）
- 返回数据要有封装意识。要对数据进行抽象，同一类型的数据，同一含义的数据在不同的接口里要保持一致。对象要进行封装再返回。禁止将所有字段揉在一起，做一个层级返回
- 返回数据较多时，要写明注释
- 不要在一个接口里完成所有功能，应尽可能的将不同的业务拆分成不同的接口，避免通过各种type去组合功能。

    {
      "result": true,
      "errorCode": 0,
      "errorMsg": "成功",
      "isEnd": false,
      "groupList": [
        {
          "groupInfo": { //群信息
            "id": 4182, //群id
            "name": "167、162、16", //群名称
            "createTime": 1595297040000, //群创建时间
        }
      ]
    }

接口交付
- 接口开发应先交付接口文档。再根据接口文档进行开发
- 接口交付一定要自己完成自测，下游可用才算完成
- 接口返回值改动要同步4端（android，ios，服务端，web端），并在群内@相关人员