开发文档案例

Author Avatar
天才在左疯子在后 4月24日
  • 在其它设备中阅读本文章

能愿动词

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

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

开发流程规范:

  1. 应该使用自定义表单验证类, 避免方法体过多类似功能代码段.
  2. 编写方法时应该声明返回类型

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

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

接口

  1. 请求
    接口 必须 统一使用api路由, POST请求统一放置在 POST 请求路由组;

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

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

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

注意事项

  1. 使用复杂多表查询时注意软删除和一些模型无感知提供的功能的处理.
  2. 编写代码之前 应该 读懂 框架核心架构

api 系统剥离

只需要修改 auth config/auth.php defaults=>guard 三维数组中 web 变为 otcapi, apiverify 中间件中 handle 方法 注释内容开启, 未注释内容注释

本文链接:https://fenxiangy.com/technology-php/kai-fa-wen-dang-an-li.html
文章属于博主原创,转载请注明本文链接

评论已关闭