技术栈
- 平台: Node.js(v8.9.3)
- 框架:Express(v4.16.0)
- 数据库:MongoDB(v3.4.14)
开发环境
Node与MongoDB的下载与安装,请自行百度或谷歌,遍地都是,不再赘述。
相关规范
相关规范主要包括代码规范
、Git commit规范
和API接口文档规范
。
代码规范
代码规范采用JavaScript Standard Style
,以下简称standard规范
。至于为什么使用这个代码规范,没有什么特殊原因,这是我使用过的第一个代码规范,是我规范自己代码的开始,习惯而已,并且github上的start数也不算少。standard规范
相比较ESLint
而言,最舒服的一点就是不用配置,对我影响最大的一点是代码中再也没有出现分号,并且强迫症再也受不了代码中有分号【捂脸】,以至于后来使用ESLint
时,也要配置为可以不写分号【再次捂脸】。
通过代码规范,可以在编程过程中避免一些低级错误,比如使用未定义的变量等,同时可以规范自己的代码书写风格,有了规范代码的习惯,写出来的代码赏心悦目,看着也舒服很多,一定程度上增加了代码的可读性,工作效率的提升也是必然的事情。
我听说过,有的团队的代码规范及其严格,比如一行代码最大字符长度不能超过120甚至80,每个函数的代码行数不能超过50行等,存在必有意义吧,起初没必要对自己这么严格,但是代码规范还是要重视起来的。
工具配合
我使用的编辑器是VS Code
,可以安装StandardJS
插件,非常方便。
同时可以配合一个npm的库包pre-commit
进行代码规范,因为不规范的代码是不会影响程序的正常运行的,但我们使用代码规范的目的就是希望提交到代码仓库的代码都是规范的,pre-commit
的作用就是在进行commit
操作时检测所有代码是否符合standard规范
,如果不符合则不允许提交代码。
相关参考
在standard规范
的文档中,有关于规范的细则和使用过程中可能出现的问题。
Git commit规范
我们进行commit
操作时,填写的相关说明一定是要有意义的,我记得在学习编程的最开始,我们的对git
的命令以及操作规范不清楚,所以commit
的信息乱七八糟,经常是“解决冲突”、“修改bug”这样的说明,在被批评之后,也仅仅是commit
信息不再胡写。
项目的commit message规范使用的是主流的Angular
规范,在实际的团队开发中,通过对commit日志的规范,有助于代码的review
、日志的自动化生成以及项目发版,同时能够很好地熟悉git工作流。在该项目中不涉及发版,只是简单的开发,所以只是遵循了部分规范,在实际工作中,如果团队刚好涉及到git工作流的规范,那肯定是要遵循的。
Git commit日志基本规范
基础语法模板
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
规范的基本说明:
type
代表本次提交的类型,是新增feature还是修复bug或是修改文档等,主要类型及其说明如下:
- feat:新增feature
- fix: 修复bug
- docs: 仅仅修改了文档,比如README, CHANGELOG, CONTRIBUTE等等
- style: 仅仅修改了空格、格式缩进、都好等等,不改变代码逻辑
- refactor: 代码重构,没有加新功能或者修复bug
- perf: 优化相关,比如提升性能、体验
- test: 测试用例,包括单元测试、集成测试等
- chore: 改变构建流程、或者增加依赖库、工具等
- revert: 回滚到上一个版本
scope
表明本次修改的范围或者模块,例如users。
subject
是对变更内容的简要描述。
BLANK LINE
不用说,就是字面意思的空白行。
body
是对本次变更更加详细的说明,可以是发起本次变更的原因以及本次变更的解决思路和方法等。
footer
处填写相关连接。
格式要求:
# 标题行:50个字符以内,描述主要变更内容
# (我是空行)
# 主体内容:更详细的说明文本,建议72个字符以内。 需要描述的信息包括:
# (我是空行)
# * 为什么这个变更是必须的? 它可能是用来修复一个bug,增加一个feature,提升性能、可靠性、稳定性等等
# * 他如何解决这个问题? 具体描述解决问题的步骤
# * 是否存在副作用、风险?
#
# 尾部:如果需要的话可以添加一个链接到issue地址或者其它文档,或者关闭某个issue。
相关参考
API接口文档规范
我写过的第一个接口文档,是word形式的,写了大概三个接口就受不了了,word写接口,太不舒服了,后来用showdoc
工具写接口文档,好用了很多,但是没有很好地体现文档的维护记录,再后来,参加工作之后接触了解了apidoc
,相对而言,它也算主流之一,使用简单并且支持多语言,所以就开始使用apidoc
作为生成接口文档的工具,接口文档在代码中以注解的形式书写,然后通过apidoc
的相关命令生成接口文档,配合git
刚好可以很好地体现接口文档的维护记录。当然,还有其他选择,个人喜好而已。
apidoc编写接口示例
代码实例:
/**
* @api {POST} /user create a user
* @apiDescription 用户新增的接口
* @apiName 用户注册
* @apiGroup User
* @apiUse userParams
* @apiSuccessExample Success-Response:
* {
* errorCode: 0,
* status: 200,
* data: {
* _id: '123',
* name: 'morehao',
* createdAt: '20180913',
* updatedAt: '20180913',
* lastLogin: '暂未登录'
* }
* }
* @apiErrorExample {json} Error-Response:
* {
* status: 200,
* errorCode: 20100,
* errorMsg: '该用户已经存在'
* }
*/
截图实例:
image
image
相关参考
这里只确定API接口文档的生成方式,详细的使用后面也不会过多涉及,下面附上相关链接。
下面附上项目的github地址:
我的个人博客:
网友评论