新人手册

Posted 2020-11-16 xulonglong

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了新人手册相关的知识，希望对你有一定的参考价值。

目标：让新人能够快速上手开发友好速搭定制插件

1. 如何开发？

1.1 开发规范

编码规范
- 命名
  - 接口名称：小驼峰，比如：/api/v1/user/verify/resetStep
  - 函数名称：小驼峰
  - 变量名称：小驼峰
- 函数大小：越小越好，不超过20行。
- 单元测试
  - 要求：
    - API测试100%
    - 主要的service测试
安全规范
- 密码规范
  - 不使用弱密码
  - 代码中的密码通过环境变量引入
  - 证书文件：不要直接放在代码中，保存到服务器后用环境变量的方式引入路径。
- npm包
  - 如何挑选高质量的 Node.js 模块？
  - 使用https://npms.io/查找包
  - npm install安装时fix高危漏洞: npm audit fix
- 开放性配置
  - 数据库: 正式环境的数据库只对内网开放。

git规范

提交代码
- 参考：egg提交代码规范
- 提交类型：
  - feat: 新功能
  - fix: 修复问题
  - docs: 修改文档
  - style: 修改代码格式，不影响代码逻辑
  - refactor: 重构代码，理论上不影响现有功能
  - perf: 提升性能
  - test: 增加修改测试用例
  - chore: 修改工具相关（包括但不限于文档、代码生成等）
  - deps: 升级依赖

格式

<type:提交 commit 的类型>(scope:修改文件的范围): <subject:用一句话清楚的描述这次提交做了什么>
<BLANK LINE>

<body补充 subject，适当增加原因、目的等相关因素，也可不写。>

<BLANK LINE>

<footer: 当有非兼容修改(Breaking Change)时必须在这里描述清楚,关联issue，如果功能点有新增或修改的，还需要关联文档 doc 和 egg-core 的 PR>

示例

fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9

Older IEs serialize html uppercased, but IE9 does not...
Would be better to expect case insensitive, unfortunately jasmine does
not allow to user regexps for throw expectations.

Document change on eggjs/egg#123

Closes #392

BREAKING CHANGE:

  Breaks foo.bar api, foo.baz should be used instead

项目文档规范

API文档

apidoc: 使用apidoc构建api文档
常用标签说明
- @api: api 方法和路径说明，格式@api {method} path [title]
- @apiVersion：版本
- @apiName：接口名称，每一个接口注释里都应该添加该字段，在导出的接口文档里会已该字段值作为导航子标题，如果两个接口的@apiVersion和@apiName一样，那么有一个接口的注释将会被覆盖(接口文档里不会展示)
- @apiGroup: 定义接口所属的接口组，虽然接口定义里不需要这个参数，但是您应该在每个接口注释里都添加这个参数，因为导出的接口文档会以接口组的形式导航展示。
- @apiDescription: api接口的详细描述
- @apiParam: 接口请求体参数
- @apiSuccess: 接口成功返回参数
- @apiSuccessExample: 返回成功示例
事例：

/**
* @api {GET} /api/v1/manager/course/:courseId/video 课程管理-查询课程的视频信息

* @apiVersion 1.0.0

* @apiName ManagerGetCourseVideo

* @apiGroup ManagerCourse

*

* @apiDescription 课程管理-查询课程的视频信息

*

* @apiParam (Path) {Number} courseId 课程ID

* @apiParam (Query) {Integer} [page=1]

* @apiParam (Query) {Integer} [limit=20]

* @apiParam (Query) {String} [name] 视频名称

* @apiParam (Query) {Date} [start_at] 上传开始时间

* @apiParam (Query) {Date} [end_at] 上传结束时间

* 

* @apiSuccess {String} cover_url 视频封面信息

* @apiSuccess {String} name 视频姓名

* @apiSuccess {String} length 文件大小

* @apiSuccess {String} createdAt 上传时间

* @apiSuccessExample {json} 成功

* {"code":200,"data":{"data":[{"id":50000,"owner_id":1,"owner_name":"","file_id":"5285890787095402127","name":"spider-man","cover_url":...,"complete":1,"op_cnt":0,"createdAt":"2019-06-26T11:48:18.329Z","updatedAt":"2019-07-03T08:24:56.631Z"}],"paging":{"page":1,"pageSize":20,"total":1}},"msg":""}

*/

DB表文档：
参考项目：kanjia, openedv-server

README模版

# demo

#### 介绍
这是一个测试项目

#### 软件架构
软件架构说明


#### 安装教程

1. xxxx
2. xxxx
3. xxxx

#### 使用说明

1. xxxx
2. xxxx
3. xxxx

#### 其他

1. xxxx
2. xxxx
3. xxxx

开发流程规范
- TDD开发（测试驱动开发）：
  - 优点：模块化、高内聚、低耦合、高效率
  - 介绍：先写测试用例，再写代码
  - 原则：FAIR，快速（fast），自动化（automated），独立（isolated），和可重复（repeatable）。
- 编码流程：
  - 梳理需求
  - 列出功能
  - 写测试用例
    - 正向测试：当前置条件满足时，验证代码的结果确实符合预期。
    - 反向测试：当前置条件或者输入不符合要求时，代码能够优雅地进行处理。
    - 异常测试：代码在应该抛出异常的地方正确地抛出了异常。
  - 编写代码
  - 通过测试
  - 提交

1.6 知识沉淀

代码片段
egg插件
- 如何开发egg插件
npm包
- 如何开发npm包

2. 如何部署？

2.1 使用公司公有服务器部署

参考：

2.2 使用客户私有服务器部署

2.2.1 容器服务（k8s）

开动客户服务器的容器服务
jenkins自动打包上传打包镜像

# 登陆镜像仓库
$ docker login -u user -p pw ccr.ccs.tencentyun.com
# 打包镜像
$ docker build -t ccr.ccs.tencentyun.com/yhsd/***:xxxx .
# 上传镜像
$ docker push ccr.ccs.tencentyun.com/yhsd/***:xxxx
# 删除本地镜像
$ docker rmi ccr.ccs.tencentyun.com/yhsd/***:xxxx