LARAVEL 项目开发规范

前言

为了更好地发挥 Laravel 的优势，本规范将充分利用 Laravel 的特性为前提，遵循并模仿 Laravel 的框架规范为准则。

配置文件

配置内容属于架构信息、服务器信息、有必要隐藏且无法提交 git 的信息，请使用 .env 文件配合 env() 方法在 /config 文件夹中相应配置文件中进行设定（.env.example 中必须添加对应的字段和示例），属于业务逻辑的常量配置，或可以提交到 git 而无需隐藏的部分配置类信息，直接在定义 /config 相应配置文件中。

数据先行

迁移文件是 Laravel 的一大亮点，迁移文件使得数据的维护更加有效率。在项目开发之前，数据库的设计至关重要。所以项目进行的第一步就是设计数据库。追加 App/Models 目录，App/User.php 迁移至 App/Models 目录中。

在这个阶段，应有如下的产出：

• 数据库迁移文件
• Model 层关联关系
• Repository 基础增删改查代码

基础接口

在 Repository 代码完成的基础之上，可以把基于 Resource 的基础接口完成，包括数据的验证，异常处理，数据格式化。其中各个模块的实现应该分离解耦。接口的风格遵循 RESTful。在这个阶段应该有如下的产出:

• Routes 中 Resource 接口定义，参考文档
• Controller 中 增删改查代码实现
• XXRequest 完成数据验证
• Transformer 完成数据格式化

第三方服务

在项目的开发中往往会使用第三方的服务来完成一些功能，比如邮件、短信、存储等。这方面可以与上述的阶段同时进行。这阶段应该有如下的产出：

• 封装好的各个功能的接口

扩展接口

在上述的三个阶段完成之后，整个项目的基础工作已经完成。那么在这阶段就需要设计出具体的业务逻辑接口。而接下来的工作只需要集中于逻辑代码的实现。这阶段应该有如下的产出：

• 初版的业务逻辑接口
• 系统后端的第一个版本

PHP 编码规范

标签

• PHP 程序可以使用 <?php ?> 或 <?= ?> 来界定 PHP 代码
• 在 HTML 页面中嵌入纯变量时，使用 <?= ?> 这样的形式
• 纯 PHP 文件，文件开始标签使用 <?php，闭合标签 ?> 必须省略

编码

PHP文件必须使用无BOM的UTF-8编码方式

注释

单行注释，在语句后面使用 // 注释，注意斜杆后面跟一个空格。多行注释，如下示例：

文件注释：

/**
 * 描述
 *
 * @copyright Copyright 2017, 公司名称
 * @author    SUNGMEE
 * @Date:     2017/07/01
 * @Time:     18:00:00
 */

方法或者函数注释：

/**
 * 描述
 *
 * @date   2017/05/28 11:27:17
 * @param  类型 $fields 描述
 * @param  类型 $fields 描述
 * @return 类型 描述
 */

属性注释：

/**
 * 描述
 *
 * @var 类型
 */

命名规范

变量命名

变量命名使用小驼峰（例如：$firstName）或者中间下划线命名（例如：$first_name）,一个页面选择一种，不可杂糅。不用缩写，用 name, address, salary 等代替 nam, addr, sal；全局变量以 g_ 开头。和前端交互的变量名全部用小写加下划线命名。

常量命名

全部使用大写字母和下划线组成，常量的名称中不允许出现小写字母。不能模仿系统的常量命名方式（例如：define("__TOO__", "something"),可能造成与系统常量的冲突）.

类命名

类名和文件名必须保持一致，并且一个文件只有一个类，命名采用大驼峰，例如：FirstClass。另外，每个类需要有命名空间 namespace，且采用 PSR-4 规范组织和整理文件和命名空间。

属性和方法命名

• 采用首字母小写的驼峰命名法，尽量用有意义，描述性的词语来命名（例如：isFirstFunc）；私有方法使用下划线开头（例如：_isPrivateFunc）。一般名称的前缀遵循第一规律的原则，如is（判断）、get（得到），set（设置）、store（保存）等等。另外，方法的作用只执行一个动作，达到一个目的即可。
• 属性使用小驼峰（例如：$isFirstPro）。
• 私有属性以_开头（例如：$_isFirstPro）。

代码格式

• 所有 PHP 文件必须以一个空行结束
• 行实际长度不应超过 80 个字符；较长的行应当被拆分成多个不超过80 个字符的后续行。
• 适当增加空行以改善代码的可读性和区分相关的代码块
• 一行不应多于一个语句
• 每个缩进的单位约定是 4 个空格的缩进，并且不可使用制表符作为缩进
• 每个运算符与两边参与运算的值或表达式中间要有一个空格
• 在绝大多数可以使用单引号的场合，禁止使用双引号
• PHP 所有关键字必须全部小写。常量 true 、false 和 null 也 必须 全部小写
• 类的开始花括号 { 必须 写在函数声明后自成一行，结束花括 } 也 必须 写在函数主体后自成一行
• 方法的开始花括号 { 必须 写在函数声明后自成一行，结束花括号 } 也 必须 写在函数主体后自成一行
• 方法名在声明之后不可跟随一个空格。左括号后面不可有空格，右括号前面不可有空格
• 关键词 extends 和 implements 必须 写在类名称的同一行。implements 的继承列表也可以分成多行,每个继承接口名称都必须分开独立成行，包括第一个
• 类的属性和方法必须添加访问修饰符（private、protected 以及 public），abstract 以及final 必须 声明在访问修饰符之前，而 static 必须 声明在访问修饰符之后，如果存在abstract 和final 声明必须放在可见性声明前面
• 一定不可 使用关键字 var 声明一个属性。
• 每条语句 一定不可 定义超过一个属性
• 在参数列表中，逗号之前不可有空格，逗号之后必须要有一个空格
• 方法中有默认值的参数必须放在参数列表的最后面
• 参数列表可以被分为多个有缩进的多个后续行，且只能有一个缩进单位。如果这么做，列表的第一项必须放在下一行，并且每行必须只放一个参数。
• 当参数列表被分为多行，右括号和左花括号必须夹带一个空格放在一起自成一行。

安全规范

• 文件中，必须不可见明文密码；若要配置密码，只能配置于 .env 文件中，不能直接写在 /config 文件夹下的配置文件中，更不能直接写于执行程序中。数据库中存储密码，也不能直接存储，需要进行可逆或不可逆加密（视实际需求而定）.
• 如果需要使用可逆加密，必须使用 Laravel 自己的加密机制，而不是尝试自己的「自制」加密算法。参考文档。
• 除了由后台管理员或者程序生成的富文本使用 {!! !!}，其余输出必须使用 或 `}`——默认 是会进行 html_filter 处理的，可以避免 XSS 攻击。

数据库规范 遵循 Laravel 规范

• 数据表的建立，必须采用小写字母的复数形式（例如：users），单不能直接加结尾 s，可使用 Laravel 的辅助函数 str_plural() 获取标准字符。多个单词，使用下划线连接(例如：user_logins）.
• 数据表尽量采用 Inonodb 引擎。
• 如果数据表中存在主键，必须为 id，迁移文件示例：$table->increments('id');；关联表中相应的字段，必须为 XXX_id 形式，XXX 对应表名。
• 附加表，如 user_metas 不可定死字段，采用可扩展的原则，如 id, user_id, key, value。
• 加入 created_at 和 updated_at 字段，$table->timestamps();。默认采用 Eloquent 自动维护这两个字段。
• 加入 deleted_at 字段于软删除使用，$table->softDeletes();。

前后端通讯

为最大发挥 Laravel 的特性，前后端通讯数据格式通常采用 JSON 或 集合（对象），一般不用纯 PHP 数组。Laravel 集合参考文档。

JSON 范例

在控制器中，须省略 response()->json()，Larave 会根据需要自动进行 JSON 转换处理，直接返回如下格式的数组即可。

return [
    'status'        => 'success',
    'status_code'   => 200,
    'data'          => $collection
]);

return [
    'status'        => 'failed',
    'status_code'   => 400,
    'message'       => $message
];

PS：状态码的使用，请阅读文档。

集合（对象）范例

$data['title']      = 'Title';
$data['subtitle']   = 'Sub Title';
$data['tables']     = $collection;
...

return view('view', $data);

团队协作

团队协作，多多沟通，尽量减少重复劳动和无用功。