Laravel框架开发规范

扩展包

我们都知道 Laravel 扩展包的注册会对应用造成消耗。有一些扩展包是开发环境中专用，生产环境中并不会使用到，为了避免无用的负载， 必须严格控制其安装和加载。安装开发专用扩展包时必须使用 --dev 参数，如：
composer require laracasts/generators --dev
开发专用的 provider 绝不在 config/app.php 里面注册，必须在 app/Providers/AppServiceProvider.php
文件中使用如以下方式：

public function register()
{
   	 if ($this->app->environment() == 'local') {
          	$this->app->register('Laracasts\Generators\GeneratorsServiceProvider');
        }
}

配置信息与环境变量

所有程序配置信息必须通过 config() 来读取，所有的 .env 配置信息必须通过config() 来读取，绝不在配置文件以外的范围使用 env()。

这样做主要有以下几个优势：

1. 定义分明，config() 是配置信息，env() 只是用来区分不同环境；
2. 统一放置于 config 中还可以利用框架的配置信息缓存功能来提高运行效率；
3. 代码健壮性，config() 在 env() 之上多出来一个抽象层，会使代码更加健壮，更加灵活。

辅助函数

Laravel 提供了很多辅助函数，有时候我们也需要创建自己的辅助函数。
必须把所有的『自定义辅助函数』存放于 app 文件夹中，文件名为helpers.php。

if(! function_exists('decrypt_aes'))
 {
	   // aes解密
	 function decrypt_aes($aes_data, $key)
	 {
			return json_decode(openssl_decrypt(hex2bin($aes_data), 'AES-256-ECB', $key, OPENSSL_RAW_DATA), true);
	 }
 }

并在 composer.json 文件中加载，方法请见： Laravel 的自定义函数 helpers.php 文件存放位置

代码风格

代码风格必须严格遵循 PSR-2 规范。

路由器

绝不在路由配置文件里书写『闭包路由』或者其他业务逻辑代码，因为一旦使用将无法使用路由缓存。

路由器要保持干净整洁，绝不放置除路由配置以外的其他程序逻辑。

必须优先使用Restful 路由，配合资源控制器使用。资源路由路由URI 必须使用复数形式。

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-NYwEzYwM-1597387500667)(http://wiki.hibo.vip.php?s=/api/attachment/visitFile/sign/1761b8841c5d2b49f0f5a79b175317b1&showdoc=.jpg)]
出 Restful 路由的，应该模仿上图的方式来定义路由。使用 resource 方法时，如果仅使用到部分路由，必须使用 only 列出所有可用路由：

Route::resource('photos', 'PhotosController', ['only' => ['index', 'show']]);

绝不 使用 except，因为** only** 相当于白名单，相对于 except 更加直观。路由使用白名单有利于养成『安全习惯』。

除了** resource** 资源路由以外，其他所有路由都 必须 使用 name 方法进行命名。

必须使用『资源前缀』作为命名规范，如下的 users.follow，资源前缀的值是 users.：

Route::post('users/{id}/follow', 'UsersController@follow')->name('users.follow');

模型

所有的数据模型文件，都必须 存放在：app/Models/ 文件夹中。

数据模型相关的命名规范：

• 数据模型类名必须为「单数」, 如：App\Models\Photo
• 类文件名必须为「单数」，如：app/Models/Photo.php

有时候数据模型里的代码会变得很臃肿，应该利用 Trait 来精简逻辑代码量，提高可读性，类似于Ruby China 源码。

借鉴于 Rails 的设计理念：「Fat Models, Skinny Controllers」。
存放于文件夹：app/Models/Traits 文件夹中。

控制器

优先使用 Restful 资源控制器 。

控制器相关的命名规范：

类名必须为「复数」，如：PhotosController
类文件名必须为「复数」，如：PhotosController.php
必须保持控制器文件代码行数最小化，还有可读性。

不应该为「方法」书写注释，这要求方法取名要足够合理，不需要过多注释；
应该为一些复杂的逻辑代码块书写注释，主要介绍产品逻辑 - 为什么要这么做。；
不应该在控制器中书写「私有方法」，控制器里应该只存放「路由动作方法」；
绝不遗留「死方法」，就是没有用到的方法，控制器里的所有方法，都应该被使用到，否则应该删除；
绝不在控制器里批量注释掉代码，无用的逻辑代码就必须清除掉。

表单验证

必须使用表单请求 - FormRequest 类来处理控制器里的表单验证。
FormRequest 表验证类必须遵循资源路由方式进行命名，photos 对应app/Http/Requests/PhotoRequest.php
FormRequest 表验证类文件请参考以下：

<?php

namespace App\Http\Requests;

class PhotoRequest extends Request
{
    public  function  authorize()  
	{ 
	    // Using policy for Authorization  
	    return  true;  
	}
    public function rules()
    {
        switch($this->method())
        {
            // CREATE
            case 'POST':
            {
                return [
                    // CREATE ROLES
                ];
            }
            // UPDATE
            case 'PUT':
            case 'PATCH':
            {
                return [
                    // UPDATE ROLES
                ];
            }
            case 'GET':
            case 'DELETE':
            default:
            {
                return [];
            };
        }
    }

    public function messages()
    {
        return [
            // Validation messages
        ];
    }
}

Artisan命令行

所有的自定义命令，都必须有项目的命名空间，如：

php artisan doctor:clear-token

php artisan doctor:send-status-email

日期函数

必须使用 Carbon 来处理日期和时间相关的操作。

中间件

Auth 中间件必须书写在控制器的 __construct 方法中，并且必须使用except 黑名单进行过滤，这样当你新增控制器方法时，默认是安全的。

public function __construct()
{
    $this->middleware('auth', [            
        'except' => ['show', 'index']
    ]);
}

注意事项

关闭 DEBUG

Laravel Debug 开启时，会暴露很多能被黑客利用的服务器信息，所以生产环境下请必须确保：

APP_DEBUG=false

开发流程

路由 >>> 控制器 >>> 服务 Service >>> 响应 Response

1、状态码问题：所有的错误都走 Exception 自定义公用的状态码管理，例如 1001 数据验证错误 2001用户相关错误接口日志做好状态码记录

2、服务service只做逻辑处理，不进行数据封装格式化，所有的格式化返回数据交给控制器处理

3、数据验证：如果控制器方法较少，验证参数少的情况下，数据验证在控制器处理。资源控制器必须使用 表单请求 - FormRequest 类

4、公用方法放在app/helpers.php 文件里，composer 自动加载

5、公用服务放在 app/Tools 目录文件中，例如图片上传、短信发送、支付宝、微信支付

author： 汤小米
Datetime： 2020-8-14

---