Laravel5.5开发规范 [ 个人总结 ]
我先在石墨文档总结的这篇开发规范,感觉在石墨文档的排版看着更舒服,点击传送:Laravel5.5开发规范
一、概述
laravel5.5是目前laravel框架发行使用最稳定的版本,laravel社区会维护这个版本到2019年6月,所以公司一直采用laravel5.5版本作为所有项目的开发框架。
为了保证产品开发过程中统一代码的编写原则,提高代码的可读性、可维护性及可靠性,特定此开发标准规范。
请所有新老员工严格按照此文档制定好的代码规范来进行开发。
二、开发环境
1. PHP开发环境
- 操作系统:windows/Linux
- 数据库:Mysql5.7
- PHP:PHP7.0+
- 服务器:Nginx1.0+
- 文件编码要求:utf-8 无 BOM头
2. 服务器环境
- 操作系统:Linux(centos7.2+)
- 数据库:Mysql5.7+
- PHP:PHP7.0+
- 服务器:Nginx1.0+
三、命名规范
1. 目录和文件命令
- 目录使用小写字母,如果单个字母无法满足要求,使用中划线连接多个字母,如:easywechat-composer;
- 类库、函数文件统一以 " .php " 为后缀;
- 类的文件名均以命名空间定义,并且命名空间的路径和类库文件所在路径一致;
- 类文件采用首字母大写驼峰命令,其他文件统一采用首字母小写驼峰命名。
2. 类、函数、属性、变量命令
- 类的命名与类文件名一致,采用驼峰法(首字母大写),例如UserController应该直接命名为User;
- 函数的命名使用驼峰法(首字母小写),例如 getUserName;
- 属性、变量的命名使用驼峰法(首字母小写),例如 tableName、instance;
- 以双下划线“__”打头的函数或方法作为魔法方法,例如 __call 和 __autoload。
3. 常量和配置命名
- 常量以大写字母和下划线命名,例如:APP_PATH、THINK_PATH;
- 配置参数以小写字母和下划线命名,例如:url_path。
4. 数据表和字段命名
- 数据表和字段采用小写加下划线方式命名,并注意字段名不要以下划线开头,不允许使用驼峰和中文作为数据表字段命名;
- 优先采用简短易懂的英文加下划线命名,例如:member_info,过长时使用简写或前4个字母;
- 如果该字段表示的是时间,则统一使用_time为后缀。例如:add_time、edit_time;
- 会员ID字段命名统一使用uid来命名,请勿使用userid、user_id等;
- 日期型字段,必须使用timestamp类型,默认值为'0000-00-00 00:00:00';
- 代码中的sql语句,禁止物理删除,用字段进行标记(如:is_del或者status)。同时数据库也会禁用删除权限;
- 状态字段统一使用名称:status,默认0为不可用,1为正常;
- 建议数据表的命名不使用前缀设计,表前缀其实已经是一种过时的设计了,很多时候跨库的设计比表前缀的设计来的更灵活和实用;
- 除自增长ID外,其余字段、表都应加上说明注释,在注释时,如果该字段表示多个状态应在注释处补全说明;
- 习惯上来说,时间与状态字段统一放在表的最后边,时间在状态之前。
5. 接口参数命名
- 统一采用小写字母;
- 如果有多个字母连接,采用 “ _ ” 进行连接,如:user_info;
- 如果单个参数过长,可以截取单个单次的前4个字母。
四、目录结构
严格按照官方文档的目录结构设计架构业务代码:https://laravelacademy.org/post/7629.html
五、注释标准
方法函数必须注释清楚用途,如需传入与输出数据的方法函数必须做到以下申明:该方法函数的用途、需要传入的参数、传入参数的类型、处理完后输出的参数、输出参数的类型。如下所示:
六、输出标准
除了报错或成功跳转页面输出外,其余部分,如:模型、类、公共方法等输出格式统一使用以下的方式输出:
/*
* status:布尔型,输出状态;
* msg :字符串型,提示信息;
* data :输出数据,根据实际需求,可以是数组、字符串、对象等。
*/
['status'=>Boolean, 'msg'=>String, 'data'=>'']
七、跨行和空格
1. 跨行
- 方法注释和方法之间不跨行;
- 两个方法之间必须跨行;
- 方法内的if判断前必须跨行;
- 方法内的foreach必须跨行;
- 方法内的代码需要按照逻辑块儿进行跨行,如:数据准备块、逻辑判断块,逻辑计算块、输出块等;
- 方法的花括号必须跨行,判断和循环的花括号不跨行。
2. 空格
- if和条件括号之间必须空格,花括号前必须空格;
- foreach和条件括号之间必须空格,花括号前必须空格;
- 函数内逗号隔开变量时,逗号后必须空格。
八、研发思想
1. 代码的优雅性:匠人精神
何为匠人精神?当你做一件事情就全身心的投入进去,做到你目前所能达到的极致,再通过你总结的经验去雕琢它,理解它,超越它。codeing也是一样,代码写得好不好,用不用心,谁看谁知道。我们要的不是一个控制器写上个八九百行代码完成实际业务即可的结果,而是除了你之外,其他同事都看得懂、看的舒服、使用方便的code。
注意缩进:合理的使用tab与空格缩进会使你的代码相对美观很多,方便其他同事阅读。
合理命名:方便与变量的命名尽可能简短、易懂。比如在一个逻辑方法里变量$newcurrencydata,字面意思易懂(新的货币数据),但变量名过长,会带来阅读与编写的不便,但如果太短,如$datac,那却是不清不楚的。
2. 高复用性:逻辑原子化
在编写逻辑层的时候应多方面考虑复用性,易用性,原子化的问题。
如实际业务【用户注册】:可拆分为多个原子逻辑,如注册表单静态效验、检查用户是否存在、注册成功、插入日志、用户登录等等,当其他业务需要对应的原子逻辑时,比如检查用户是否存在,那么便可以直接实例化之前的logic直接调用了。
3. 高性能
laravel自带有trace,开启后可以看到当前所有执行的SQL与页面的详细开销,特别是在有循环操作与多表操作处应仔细审查,编写是否合理?是否可以优化?是否合理的使用缓存处理?哪怕页面加载减少了1s,那也是一种进步。你的细心与眼界直接决定了你的代码性能。
4. 低冗余
不要重复造*、不要重复造*、不要重复造*....
重要的事情说三遍,当一段代码你重复写了两次以上时你就应该思考设计是否合理,而不是为了完成功能而cpoy过去改一改应付而已。
九、其他说明
1. 一个方法中,同一个函数只能执行一次;
2. 一个方法内,不能有太多if {…} else { … },如果不是极其特殊的原因,不用if {} else {},在做逻辑判断时,最好可以进行单个if截断,如下图:
3. 每个业务逻辑方法的 “ 圈复杂度 ” 不能超过4;