208 lines
7.1 KiB
Markdown
208 lines
7.1 KiB
Markdown
## 代码规范
|
||
|
||
本篇规范制定了代码风格的相关标准，以确保团队开发时代码间具有较高程度的技术互通性。
|
||
|
||
|
||
### 定义
|
||
- `大驼峰`: 首字母大写的驼峰式 StudlyCase
|
||
- `小驼峰`: 首字母小写的驼峰式 camelCase
|
||
- `蛇形`: 下划线链接的小写 snake_case
|
||
- `链式`: 短线链接的小写 kebab-case
|
||
- `常数式`: 全部大写字母 CONSTENT_CAST
|
||
- `标题式`: 每个单词首字母大写 Title Case
|
||
- `点式`: 英文.分割 dot.cast
|
||
- `分式`: 英文:分割 semicolon:cast
|
||
|
||
### 能愿动词
|
||
|
||
- `必须 (MUST)`：绝对，严格遵循，请照做，无条件遵守
|
||
- `一定不可 (MUST NOT)`：禁令，严令禁止
|
||
- `应该 (SHOULD)` ：强烈建议这样做，但是不强求
|
||
- `不该 (SHOULD NOT)`：强烈不建议这样做，但是不强求
|
||
- `可以 (MAY)` 和 `可选 (OPTIONAL)` ：选择性高一点，在这个文档内，此词语使用较少
|
||
|
||
### 文件夹及文件
|
||
|
||
- 存放类的文件夹 `应该` 以 `大驼峰` 的方式命名
|
||
- 资源文件夹 `应该` 以 `蛇形` 的方式命名
|
||
- 类的文件命名 `必须` 以 `大驼峰`的方式命名，并且文件名和类名一致
|
||
- 其他的php文件命名 `必须` 以 `蛇形` 的方式命名
|
||
|
||
### 基础规范
|
||
- 每个类 `应该` 都独立为一个文件，且命名空间 `必须` 符合目录层级
|
||
- 类的命名 `必须` 遵循 `大驼峰` 命名规范
|
||
- 类的常量 `必须` 遵循 `常数式` 命名规范
|
||
- 类的属性 `应该` 遵循 `小驼峰` 命名规范，私有属性 `应该` 使用'_'开始
|
||
- 类的方法 `必须` 遵循 `小驼峰` 命名规范
|
||
- 全局函数 `必须` 遵循 `蛇形` 命名规范
|
||
- 变量的命名 `应该` 遵循 `小驼峰` 命名规范
|
||
|
||
### 单数 or 复数？
|
||
|
||
#### Route
|
||
资源路由路由 URI 必须 使用复数形式，如：
|
||
|
||
- `/photos/create`
|
||
- `/photos/{photo}`
|
||
|
||
错误的例子如：
|
||
- `/photo/create`
|
||
- `/photo/{photo}`
|
||
|
||
#### Model
|
||
- 数据模型类名 `必须` 为「单数」, 如：`App\Models\Photo`
|
||
- 类文件名 `必须` 为「单数」，如：`app/Models/Photo.php`
|
||
- 数据库表名字 `必须` 为「复数」，多个单词情况下使用「Snake Case」 如：`photos`, `my_photos`
|
||
- 数据库表迁移名字 `必须` 为「复数」，如：`2014_08_08_234417_create_photos_table.php`
|
||
- 数据填充文件名 `必须` 为「复数」，如：`PhotosTableSeeder.php`
|
||
- 数据库字段名 `必须` 为「Snake Case」，如：`view_count`, `is_vip`
|
||
- 数据库表主键 `必须` 为「id」
|
||
- 数据库表外键 `必须` 为「resource_id」，如：`user_id`, `post_id`
|
||
- 数据模型变量 `必须` 为「resource_id」，如：`$user_id`, `$post_id`
|
||
|
||
#### Controller
|
||
资源控制器 `必须` 使用资源的单数形式，如：
|
||
|
||
- 类名：`PhotoController`
|
||
- 文件名：`PhotoController.php`
|
||
|
||
错误的例子如：
|
||
|
||
- 类名：`PhotosController`
|
||
- 文件名：`PhotosController.php`
|
||
|
||
#### Service
|
||
服务层 `必须` 使用资源的单数形式，如：
|
||
|
||
- 类名：`PhotoService`
|
||
- 文件名：`PhotoService.php`
|
||
|
||
错误的例子如：
|
||
|
||
- 类名：`PhotosService`
|
||
- 文件名：`PhotosService.php`
|
||
|
||
#### Repository
|
||
仓库层 `必须` 使用资源的单数形式，如：
|
||
|
||
- 类名：`PhotoRepository`
|
||
- 文件名：`PhotoRepository.php`
|
||
|
||
错误的例子如：
|
||
|
||
- 类名：`PhotosRepository`
|
||
- 文件名：`PhotosRepository.php`
|
||
|
||
### API接口规范
|
||
|
||
#### 路由
|
||
|
||
- 所有API接口 `必须` 通过路由文件下的 `api.php` 进行定义，其他接口如文件上传、第三方授权登录 `必须` 通过路由文件下 `web.php` 进行定义
|
||
- 所有路由的前缀 `必须` 以 `Service` 的 `链式` 方式定义
|
||
- 所有路由 `必须` 同时兼容 `GET` 和 `POST` 两种请求方式
|
||
|
||
#### 数据处理
|
||
|
||
> 对于API当中的正确和异常的处理，各家公司的方式各有不同。有的将所有返回的HTTP状态码均设为200，错误在json中以全局错误码设定；也有将HTTP状态码作为错误的判断标准。
|
||
>
|
||
> 综合考虑前后端分离的开发方式，以及PHP代码的可读性。本项目采用以HTTP状态码定义请求状态。
|
||
|
||
返回数据 `必须` 遵循以下规范:
|
||
|
||
```
|
||
{
|
||
"code" => 0,
|
||
"message" => "正确",
|
||
"data" => $data
|
||
}
|
||
```
|
||
|
||
- code: 0表示请求成功, 其他均为错误，错误码可自定义
|
||
- message: 请求提示
|
||
- data: 返回的数据结果
|
||
|
||
> 对于请求是否成功，以是否是预期的返回来进行判断。如遇 参数不合法、未找到数据、未登录等都 `必须` 使用错误的放回形式
|
||
|
||
所有请求都应该响应HTTP响应码，请仔细阅读以下HTTP状态码含义,或与传统HTTP状态码含义有所不同：
|
||
|
||
200: 请求成功，前端需要提示 message 信息
|
||
201: 请求成功，前端不需要提示 message 信息
|
||
202: 请求失败，前端不需要提示错误 message 信息
|
||
400及以上的状态码均表示请求失败，且前端需要提示错误 message 信息
|
||
|
||
以下HTTP状态码均需要前端提示出，错误信息可自定义
|
||
- 400： (错误请求) 请求失败,请稍后重试
|
||
- 401： (未授权) 用户未登录
|
||
- 402： (需要付费) 该资源需要付费获取
|
||
- 403： (禁止) 用户没有权限
|
||
- 404： (未找到) 未找到数据
|
||
- 405： (方法禁用) 请求方法不允许
|
||
- 406： (不接受) 服务器返回的数据错误
|
||
- 407： (需要代理授权) 授权方没有权限
|
||
- 408： (请求超时) 请求其他API接口超时
|
||
- 409： (冲突) 请求太快，请休息一下 | 遇到加锁等
|
||
- 410： (已删除) 请求的数据已删除
|
||
- 411： (参数长度错误) 请求的字段过长
|
||
- 412： (未满足前提条件) 请先进行XX操作
|
||
- 413： (请求实体过大) 上次的文件过大
|
||
- 414： (请求的 URI 过长) 请求的 URI(通常为网址)过长，服务器无法处理。
|
||
- 415： (不支持的媒体类型) 文件格式不正确
|
||
- 416： (搜索条件有误) 搜索条件有误，如时间不正确等
|
||
- 417： (未满足期望值) 请求头部不正确
|
||
- 418： (彩蛋) 虽然出错了，但获取到了彩蛋
|
||
- 421： (备用)
|
||
- 422： (备用)
|
||
- 423： (备用)
|
||
- 424： (备用)
|
||
- 425： (备用)
|
||
- 426： (备用)
|
||
- 428： (备用)
|
||
- 429： (备用)
|
||
- 431： (备用)
|
||
- 451： (法律不允许) 该访问因法律的要求而被拒绝
|
||
- 500+ 500以上错误为服务器错误，将由框架统一输出
|
||
|
||
可使用全局辅助函数进行正确输出处理：
|
||
```
|
||
return res($data = null, $message = '', $status = 200, $headers = [], $options = 256)
|
||
```
|
||
|
||
可使用全局辅助函数进行错误输出处理：
|
||
```
|
||
// 其实不要return也是可以的，但是建议加上表示程序中断
|
||
return err($message = null, $code = -1, $data = null, $statusCode = null, $headers = [], $options = 0)
|
||
```
|
||
|
||
### 其他规范
|
||
- 数据库字段名 `必须` 遵循 `蛇形` 命名规范
|
||
- 缓存的键名 `必须` 遵循 `分式` 命名规范
|
||
- Redis的键名 `必须` 遵循 `分式` 命名规范
|
||
|
||
|
||
> 附: 辅助转换全局函数
|
||
|
||
```
|
||
// 转为大驼峰
|
||
studly_case($string);
|
||
|
||
// 转为小驼峰
|
||
camel_case($string);
|
||
|
||
// 转为蛇形
|
||
snake_case($string);
|
||
|
||
// 转为链式
|
||
kebab_case($string);
|
||
|
||
// 转为常数式
|
||
constent_cast($string);
|
||
|
||
// 转为标题式
|
||
title_case($string);
|
||
|
||
// 转为点式
|
||
dot_cast($string);
|
||
|
||
// 转为分式
|
||
semicolon_cast($string);
|
||
``` |