美文网首页
Node+Express搭建个人博客(纯后端)-开发准备(二)

Node+Express搭建个人博客(纯后端)-开发准备(二)

作者: 毛浩先生 | 来源:发表于2018-09-19 18:20 被阅读0次

    技术栈

    • 平台: 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规范的文档中,有关于规范的细则和使用过程中可能出现的问题。

    standard规范的中文文档

    standard规范的github链接

    pre-commit链接

    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。
    

    相关参考

    Git commit message和工作流规范

    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接口文档的生成方式,详细的使用后面也不会过多涉及,下面附上相关链接。

    apidoc官方网站

    apidoc文档的官方示例

    下面附上项目的github地址:

    项目地址

    我的个人博客:

    毛浩先生的个人博客

    相关文章

      网友评论

          本文标题:Node+Express搭建个人博客(纯后端)-开发准备(二)

          本文链接:https://www.haomeiwen.com/subject/qitwnftx.html