零序言

说明

这是一套严格的团队开发规范,是 萌芽科技 团队内部 Laravel 工程师践行的开发规范。我们崇尚开放和透明的工程师文化,所以我们尽可能把信息公开。希望这些信息可以为他人参考和借鉴,发挥最大的价值。

目的

山东萌芽科技网络有限公司 是一家崇尚远程协作的软件外包公司,工程师来自全球各地,规范化让我们的工程师训练有素,以此来提供更加高质量的软件交付。另一方面,我们也希望整个团队的项目经验能够得到继承,在每一次实战中不断进行总结和摸索,找到兼备开发效率、程序执行效率、扩展性和安全性的最佳实践,最终实现团体智慧的延续和精进。

优势

规范有以下优点:

  • 高效编码 - 避免了过多的选择造成的『决策时间』浪费;
  • 风格统一 - 最大程度统一了开发团队成员代码书写风格和思路,代码阅读起来如出一辙;
  • 减少错误 - 减小初级工程师的犯错几率。

开发哲学

因为篇幅原因本规范无法涉及到项目里每一块代码的编写标准,所以此处重点说明下此规范遵循的『开发哲学』,开发中请把其当做指明灯,来指引你做决策:

  • DRY –「Don't Repeat Yourself」不写重复的逻辑代码;
  • 约定俗成 - 「Convention Over Configuration」,优先选择框架提倡的做法,不过度配置;
  • KISS - 「Keep it Simple, Stupid」提倡简单易读的代码,不写高深、晦涩难懂的代码,不过度设计
  • 主厨精选 - 让有经验的人来为你选择方案,不独创方案;
  • 官方提倡 - 优先选择官方推崇的方案。

设计理念

以下是一些优秀的『程序设计理念』:

  • MVC - Model, View, Controller ,以 MVC 为核心,严格控制 Controller 的可读性和代码行数;
  • Restful - 利用『资源化概念』和标准的 HTTP 动词来组织你的程序;

在此规范中,我们会将使用这两套理念作为程序设计基础。这些设计理念为我们设计程序提供了依据,遵循这些理念,能让程序变得清晰易读。

能愿动词

为了避免歧义,文档大量使用了「能愿动词」,对应的解释如下:

  • 必须(Must) - 只能这样子做,请无条件遵循,没有别的选项;
  • 绝不(Must Not)- 严令禁止,在任何情况下都不能这样做;
  • 应该(Should) - 强烈建议这样做,但是不强求;
  • 不应该(Should Not) - 强烈建议不这样做,但是不强求;
  • 可以(May) - 选择性高一点,在这个文档内,此词语使用较少;

参考:RFC 2119

关于执行

在这份规范里,有些内容里会解释『这样做的理由』,这样做的目的是为了达成共识。

请不要以此『理由』的准确性来怀疑规范的权威性,规范就是规范,可以讨论改正,但在执行的时候 必须 严格遵守。

请把『团队项目开发』想象就是在行军打仗,对于规范要绝对服从。要有大局观,做到团结一致,把个人的喜好放一边,把整个团队的执行效率放在第一位。

一、项目规范

Laravel 版本选择

选择 Laravel 版本时,应该 优先考虑 LTS 版本,因为安全性和稳定性考虑,商业项目开发中 不应该 使用最新版本的 『Laravel 一般发行版』 。扩展阅读:如何选择 Laravel 框架版本

请使用以下命令来创建指定版本的 Laravel 项目:

composer create-project laravel/laravel project-name --prefer-dist "6.0.*"

开发和线上环境

1.环境说明

一般情况下,一个项目 应该 有以下三个基本的项目环境:

  • Local - 开发环境
  • Staging - 线上测试环境
  • Production - 线上生产环境
2.使用软件
  • 服务器系统
    • Laravel 社区提倡使用 Ubuntu 系统,开发环境 Homestead 中默认也是使用 Ubuntu 系统。所以服务器系统 应该 优先考虑 Ubuntu,并且是 LTS 支持的系统,如 Ubuntu 14.04.5 LTS 或者 Ubuntu 16.04.2 LTS 。
  • PHP 7
    • PHP 版本 应该 优先考虑 PHP 7,不止因为其运行高效,还因为随着 PHP 7 的广泛应用,PHP 7 以下的版本将会很快停止维护。
  • MySQL 5.8
    • 数据库软件 应该 优先选择 MySQL,因为其使用率最高。MySQL 5.8 与 PHP 7 一样,已经是大势所趋,选择版本时 应该 优先考虑 MySQL 5.8。

应该 优先选择 流行 稳定 版本。线上环境 绝不 使用 Beta 或者其他不稳定发行版。

3.Production 生产环境

线上环境部署可以参考 Laravel 6.0 部署方案

出于安全考虑,线上环境 必须 只开放以下端口:

  • 80 HTTP
  • 443 HTTPS
  • 22 SSH
4.Local 开发环境

所有项目 必须 使用 Homestead 作为应用程序运行的环境。请阅读 为什么必须使用 Homestead 来开发 Laravel 应用? 。

  • 统一使用域名 .test 作为后缀
  • 统一使用 IP 192.168.10.10 作为 hosts 绑定地址,如:192.168.10.10 project-name.test
  • 统一使用 VS Code 进行开发
5.Staging 线上测试环境

除了域名等其他独立应用配置以外,环境 必须 跟 Production 保持高度一致性,可以的话 应该 与 Production 使用同台机器。

配置信息与环境变量

假如我们有个『CDN 域名』的变量,在 Laravel 中有以下几种方法:

  1. 硬代码,直接写死。- ❌ 可维护性低
  2. 写死在 config/app.php 文件中。 - ❌ 无法区分环境进行配置
  3. 存储于 .env 文件中,使用 env() 方法直接读取。 - ❌ 虽然解决了环境变量问题但是不推荐
  4. 存储在 .env 和 config/app.php 文件中,然后使用 config() 函数来读取。- ✅ 最佳实践

第一种方法是最古老的方法,代码可维护性极低,一旦域名变更就只能全局替换。第二种方法无法区分环境,例如本地使用开发环境域名测试,线上才是正式的 CDN 域名。第三种方法虽然解决了环境变量的问题,并且也具备一定的灵活性,但是不够灵活,假如你的网站流量巨大,需要配置几个 CDN 域名,使其在加载静态资源时随机支配域名,这种做法就无法满足需求了。第四种方法既支持环境变量,又具备极高的灵活性,假如遇到同样的 CDN 多域名随机问题,你只需要写一个辅助方法,然后在 config/app.php 中调用即可,不需要动到任何一行业务逻辑代码。

代码示例

.env 文件中设置:

CDN_DOMAIN=cdndomain.com

config/app.php 文件中设置:

'cdn_domain' => env('CDN_DOMAIN', null),

程序中两种获取 相同配置 的方法:

  1. env('CDN_DOMAIN')
  2. config('app.cdn_domain')

在此统一规定:所有程序配置信息 必须 通过 config() 来读取,所有的 .env 配置信息 必须 通过 config() 来读取,绝不 在配置文件以外的范围使用 env()

有何优势

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

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

注: Laravel 5.2 以后的官方文档也提倡用此方法。

辅助函数

Laravel 提供了很多 辅助函数,有时候我们也需要创建自己的辅助函数。

必须 把所有的『自定义辅助函数』存放于 app 文件夹中。

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

项目文档编写规范

每一个项目都 必须 包含一个 readme.md 文件,readme 里书写这个项目的简单信息。作用主要有两个,一个是团队新成员可从此文件中快速获悉项目大致情况,另一个是部署项目时可以作为参考。

1. 排版规范

文档页面排版 必须 遵循 中文文案排版指北 ,在此基础上:

  • 中文文档请使用全角标点符号;
  • 必须 遵循 Markdown 语法,勿让代码显示错乱;
  • 原文中的双引号(" ")请代换成中文的引号(『』符号怎么打出来见 这里)。
  • 所有的 「加亮」、「加粗」和「[链接]()」都需要在左右保持一个空格。
2. 行文规范

readme.md 文档 应该 包含以下内容:

  • 「项目概述」- 介绍说明项目的一些情况,类似于简单的产品说明,简单的功能描述,项目相关链接等,500 字以内;
  • 「运行环境」- 运行环境说明,系统要求等信息;
  • 「开发环境部署 / 安装」- 一步一步引导说明,保证项目新成员能最快速的,没有歧义的部署好开发环境;
  • 「服务器架构说明」- 最好能有服务器架构图,从用户浏览器请求开始,包括后端缓存服务使用等都描述清楚(主要体现为软件的使用),配合「运行环境」区块内容,可作为线上环境部署的依据;
  • 「代码上线」- 介绍代码上线流程,需要执行哪些步骤;
  • 「扩展包说明」- 表格列出所有使用的扩展包,还有在哪些业务逻辑或者用例中使用了此扩展包;
  • 「自定义 Artisan 命令列表」- 以表格形式罗列出所有自定义的命令,说明用途,指出调用场景;
  • 「队列列表」- 以表格形式罗列出项目所有队列接口,说明用途,指出调用场景。

二、编码规范

占位

三、杂项

占位