为了更好地发挥 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 代码 - 在 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
攻击。
- 数据表的建立,必须采用小写字母的复数形式(例如: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
集合参考文档。
在控制器中,须省略 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);
团队协作,多多沟通,尽量减少重复劳动和无用功。