开发规范

[TOC]

  • Laravel 版本 5.5
  • PHP 版本 7.1.13
  • MySQL 版本 5.7.19

1. 目录结构

文件夹名称 简介
app 应用程序的业务逻辑代码存放文件夹
app/Console 存放自定义 Artisan 命令文件
app/Console/Commands 自定义 Artisan 命令文件
app/Console/Commands/stubs 自定义命令相关的文件模板
app/Exceptions 存放异常、错误码,以及处理异常文件
app/Http/Controllers 存放控制器文件
app/Http/Middleware 存放「中间件」文件
app/Logic 数据库逻辑层
app/Models 数据库 ORM 映射文件,每个文件对应一张表
bootstrap 框架启动与自动加载设置相关的文件
composer.json 应用依赖的扩展包
composer.lock 扩展包列表,确保这个应用的副本使用相同版本的扩展包
config 应用程序的配置文件
config/custom.php 项目自定义配置文件
database 数据库操作相关文件(数据库迁移和数据填充)
node_modules 存放 NPM 依赖模块
package.json 应用所需的 NPM 包配置文件
phpunit.xml 测试工具 PHPUnit 的配置文件
public 前端控制器和资源相关文件(图片、JavaScript、CSS)
readme.md 项目介绍说明文件
resources 应用资源
resources/assets 未编译的应用资源文件(图片、JavaScript、CSS)
resources/lang 多语言文件
resources/views 视图文件
routes/api.php 用于定义 API 类型的路由
routes/channels.php 事件转播注册信息
routes/console.php 用于定义 Artisan 命令
routes/web.php 用于定义 Web 类型的路由
server.php 使用 PHP 内置服务器时的 URL 重写(类似于 Apache 的 "mod_rewrite" )
storage 编译后的视图、基于会话、文件缓存和其它框架生成的文件
storage/app 目录可用于存储应用程序使用的任何文件
storage/framework 目录被用于保存框架生成的文件及缓存
storage/logs 应用程序的日志文件
tests 应用测试相关文件
vendor Composer 依赖模块
webpack.mix.js Laravel 的前端工作流配置文件
yarn.lock Yarn 依赖版本锁定文件
.gitignore 被 Git 所忽略的文件
.env 环境变量配置文件

2. Artisan 命令

项目中,如果需要创建 Model、Middleware 或 其他,必须通过 php artisan 命令来创建。

如果需要自定义 Artisan 命令的话,都 必须 包含项目的名称。

下面三个是项目自定义的 Artisan 命令,

项目创建 Model 命令:

php artisan mtime:model ModelName

查看帮助:

php artisan mtime:model -h

参数列表:

参数名 含义
-c, --controller 为该 Model 创建一个对应的 Controller
-f, --factory 创建数据填充文件
-m, --migration 创建数据库迁移文件
-p, --pivot
-r, --resource 资源
-l, --logic 创建数据库逻辑层
-a, --all 包含上面所有的命令,一个参数搞定
--force 强制创建,及时 Model 以及存在

创建 Controller 命令:

php artisan mtime:controller Controller

查看帮助:

php artisan mtime:controller -h

创建 Logic 命令:

php artisan mtime:logic ModelLogic

查看帮助:

php artisan mtime:logic -h

3. 异常和错误处理

目录:app/Exceptions

包含:

  • 错误码,包括与 客户端定义 和 后端自用的错误 放在 ErrorCode.php 文件,并在 $errorCodeList 数组中添加错误码对应的错误信息
  • 异常处理,代码在 Handler.phprender() 函数
  • 误码的命名规则为:客户端错误码,以 CLIENT_ 开头;服务端以 SERVER_ 开头

4. 业务逻辑层

目录:app/Http

包含:

  • 存放 controller , 目录/Controllers/

    所有的接口业务逻辑 必须 写到该目录下,且与 Model 对应,并且 Controller 之间 禁止 相互调用

  • 存放 中间件,目录 /Middleware

  • 后续补充 …...

注意事项:

  • 接口参数验证使用 Validator::make 的方式验证,并且添加自定义的错误信息 自定义验证规则,使返回给客户端的错误更加明确

    注册接口参数验证例子:

    $validator = Validator::make(
        $input, [
        'phone' => ['required', new PhoneNumberRule],
        'password' => 'required',
        'verifcode' => 'required',
    ], [
        'required' => ':attribute未填写',
    ]);
    if ($validator->fails()) {
        // 项目内参数错误异常
        throw ApiException::createForParamsError($validator->errors()->first());
    }
    
  • 所有的错误信息,通过 throw new ApiException(ErrorCode::CODE); 的方式抛出

    与客户端协议的错误码定义在 app/Exceptions/ErrorCode.php 文件中,包括服务器自己用的错误码也定义在其中

  • 正确的返回信息使用 BaseController.phppublic function success($data = []) 方法返回

5. 模型逻辑层

目录:app/Logic

主要是 隔离 Controller 和 Model 的调用,剥离出一个逻辑层用于封装 Model 的 增删改查

注意事项:

  • Controller 禁止 直接调用 Model 的方法,必须 通过 Logic 层来调用
  • 每个 Model 对应一个 Logic,但是每个 Controller 可以对应多个 Logic

6. 模型层

目录:app/Models

数据库 ORM 映射文件,每个文件对应一张表

注意事项:

  • 如果接口文档字段 与 数据库字段 名称不一致时,重写 Model 的 toArray() 方法,在方法内做对应的修改

    禁止 在 Controller 层做数据拼装

  • 所有的数据拼装,需要在 Model 层进行操作

7. 工具类

目录:app/Tools

命名空间:App\Tools

所有的工具类 必须 放到该目录下

处理不同事物的工具类,必须 分文件放到该目录下

如有一个 图片处理的工具类,可以命名为 ImageTools.php 放到该目录下,暴露出的函数 必须 为静态函数

8. 配置文件

目录:config/

项目中用到的所有配置都 必须 放到该目录下

目前自定义的配置放到了 config/custom.php 文件下,如果后期配置项多的时候,可以考虑分文件

注意事项:

所有程序配置信息 必须 通过 config() 来读取

所有的 .env 配置信息 必须 通过 config() 来读取

绝不 在配置文件以外的范围使用 env()

9. 数据库迁移和数据填充

目录:database/

所有与此相关的文件,必须使用上面的 自定义命令 来创建

  • 数据库迁移文件目录 database/migrations
  • 数据填充目录 database/factories
  • artisan seed命令 源文件 database/seeds

10. 前端相关

目录:public/

  • 前端 js 文件 和 css 文件 public/csspublic/js 目录
  • 程序入口 index.php

注意事项:

  • 所有与静态页相关的内容,必须封装路由,内部重定向,禁止 直接将 XXX.html 给客户端

11. 应用资源

目录: resources/

框架 MVC 的 views 包含的所有内容

  • public/assets 未编译的应用资源文件(图片、JavaScript、CSS)
  • public/lang 多语言文件
  • public/views 视图文件

12. 路由文件

目录:routes/

路由的设置都在该文件夹下

目前所有与 api 相关的路由全部放在了 api.php 文件中

若后期路由很多的情况下,可对 api.php 进行拆分

  • api.php 用于定义 API 类型的路由
  • channels.php 事件转播注册信息
  • console.php 用于定义 Artisan 命令 禁用
  • web.php 用于定义 Web 类型的路由

13. 单元测试

目录:tests/

所有单元测试都要放到 /Unit 目录中,

并且单元测试必须分为不同的模块,

如与用户相关的单元测试命名为 UserTest.php

与发短信相关的单元测试命名为 SmsTest.php

附录

1. 自定义验证规则

使用自定义认证规则时,参考 Laravel 自定义验证规则

必须 使用 Artisan 命令,如添加一个手机号验证规则:

php artisan make:rule PhoneNumberRule

运行后,新的规则存放在 app/Rules 目录中,

规则对象包含两个方法: passesmessage

passes 方法接收属性值和名称,并根据属性值是否符合规则而返回 true 或者 false

message 应返回验证失败时应使用的验证错误消息:

<?php

namespace App\Rules;

use Illuminate\Contracts\Validation\Rule;

class PhoneNumberRule implements Rule
{
    public function __construct()
    {
    }

    public function passes($attribute, $value)
    {
        if (strlen($value) === 11) {
            // 正则验证
            if (preg_match("/^1[34578]{1}\d{9}$/", $value)) {
                return true;
            }
            return false;
        }
        return false;
    }

    public function message()
    {
        return '手机号不正确';
    }
}

创建完规则之后,如何 使用?如下代码:

$validator = Validator::make(
   $input, [
   'phone' => ['required', new PhoneNumberRule],
   'password' => 'required',
   'verifcode' => 'required',
], [
   'required' => ':attribute未填写',
]);
最后更新于 20th Sep 2018