开发文档案例

2019-04-24

2019-08-07

工程实践

技术文档

/

开发规范

/

API 设计

能愿动词#

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

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

开发流程规范:#

应该使用自定义表单验证类,避免方法体过多类似功能代码段.

编写方法时应该声明返回类型

1
 `public function create(Create $request)
2
: JsonResponse {`

每个方法 必须 写上规范注释.
用户信息访问 应该 使用Auth门面, Auth已经过框架自动载入,具体使用方法参照现有代码.
应该 使用一个return 进行数据返回.
固定值访问应该 使用config()访问语义化词汇获得如config('common_config.premium.min').
编写业务代码时遵循依赖框架原则,框架可以提供便利的尽量使用框架提供的功能.
controller层仅作为基础判断使用,繁杂业务逻辑 应该 在Service层进行处理.
对存入数据的操作应该使用模型处理.
对一对多,多对多,多对一等模型数据访问时,尽量 使用框架自带的模型关联功能
关键性操作流程 应该 注入事件方便业务功能.
数据库表增删改 必须 使用数据库迁移
创建表后应该编写相应的数据工厂文件.
开发时应该先编写对应的单元测试.
应该 对表单数据进行类型校验,可以在表单验证中加上.

其他规范应该参照: Laravel 项目开发规范

接口#

请求接口 必须 统一使用api路由, POST请求统一放置在POST请求路由组;
- POST 请求路由 必须 使用 post 路由前缀, 中间件应该 使用与之相对的中间件
- 表单校验:接口路由指向的方法中请求信息参数 必须 使用自定表单验证类依赖注入校验表单填写是否正确, 自定义表单验证类中应在类体中使用 use UnifiedFormat; 处理表单验证类自动处理的返回内容适用到项目.
Api的路由 必须 使用 name 方法标注, 标注中以 . 分隔, 标注代表着此接口的权限管理项的标注, 用于后期添加权限; 注意标注的末尾动作如下表格, 其他行为应该使用功能翻译英文标记

Api.前缀.功能(英文并可以多个 . 分隔).操作词

动词描述是否幂等
show 获取资源，单个是
index 获取资源，多个是
create 创建资源否
PATCH 更新资源，客户端提供部分的资源数据否
DELETE 删除资源是
应该 使用 api 资源 返回数据资源.
响应响应使用Res门面 use Res; 可使用具体方法在 app/Http/Controllers/Auth/Api/ResponseMsg.php 具体使用规则参考部分接口控制器代码

动词	描述	是否幂等
show	获取资源，单个	是
index	获取资源，多个	是
create	创建资源	否
PATCH	更新资源，客户端提供部分的资源数据	否
DELETE	删除资源	是