技術(shù)棧
- 平臺(tái)： Node.js（v8.9.3）
- 框架：Express（v4.16.0）
- 數(shù)據(jù)庫(kù)：MongoDB（v3.4.14）
開(kāi)發(fā)環(huán)境
Node與MongoDB的下載與安裝，請(qǐng)自行百度或谷歌，遍地都是，不再贅述。
相關(guān)規(guī)范
相關(guān)規(guī)范主要包括代碼規(guī)范、Git commit規(guī)范和API接口文檔規(guī)范。
代碼規(guī)范
代碼規(guī)范采用JavaScript Standard Style,以下簡(jiǎn)稱(chēng)standard規(guī)范。至于為什么使用這個(gè)代碼規(guī)范，沒(méi)有什么特殊原因，這是我使用過(guò)的第一個(gè)代碼規(guī)范，是我規(guī)范自己代碼的開(kāi)始，習(xí)慣而已，并且github上的start數(shù)也不算少。standard規(guī)范相比較ESLint而言，最舒服的一點(diǎn)就是不用配置，對(duì)我影響最大的一點(diǎn)是代碼中再也沒(méi)有出現(xiàn)分號(hào)，并且強(qiáng)迫癥再也受不了代碼中有分號(hào)【捂臉】，以至于后來(lái)使用ESLint時(shí)，也要配置為可以不寫(xiě)分號(hào)【再次捂臉】。
通過(guò)代碼規(guī)范，可以在編程過(guò)程中避免一些低級(jí)錯(cuò)誤，比如使用未定義的變量等，同時(shí)可以規(guī)范自己的代碼書(shū)寫(xiě)風(fēng)格，有了規(guī)范代碼的習(xí)慣，寫(xiě)出來(lái)的代碼賞心悅目，看著也舒服很多，一定程度上增加了代碼的可讀性，工作效率的提升也是必然的事情。
我聽(tīng)說(shuō)過(guò)，有的團(tuán)隊(duì)的代碼規(guī)范及其嚴(yán)格，比如一行代碼最大字符長(zhǎng)度不能超過(guò)120甚至80，每個(gè)函數(shù)的代碼行數(shù)不能超過(guò)50行等，存在必有意義吧，起初沒(méi)必要對(duì)自己這么嚴(yán)格，但是代碼規(guī)范還是要重視起來(lái)的。
工具配合
我使用的編輯器是VS Code,可以安裝StandardJS插件，非常方便。
同時(shí)可以配合一個(gè)npm的庫(kù)包pre-commit進(jìn)行代碼規(guī)范，因?yàn)椴灰?guī)范的代碼是不會(huì)影響程序的正常運(yùn)行的，但我們使用代碼規(guī)范的目的就是希望提交到代碼倉(cāng)庫(kù)的代碼都是規(guī)范的，pre-commit的作用就是在進(jìn)行commit操作時(shí)檢測(cè)所有代碼是否符合standard規(guī)范，如果不符合則不允許提交代碼。
相關(guān)參考
在standard規(guī)范的文檔中，有關(guān)于規(guī)范的細(xì)則和使用過(guò)程中可能出現(xiàn)的問(wèn)題。
Git commit規(guī)范
我們進(jìn)行commit操作時(shí)，填寫(xiě)的相關(guān)說(shuō)明一定是要有意義的，我記得在學(xué)習(xí)編程的最開(kāi)始，我們的對(duì)git的命令以及操作規(guī)范不清楚，所以commit的信息亂七八糟，經(jīng)常是“解決沖突”、“修改bug”這樣的說(shuō)明，在被批評(píng)之后，也僅僅是commit信息不再胡寫(xiě)。
項(xiàng)目的commit message規(guī)范使用的是主流的Angular規(guī)范，在實(shí)際的團(tuán)隊(duì)開(kāi)發(fā)中，通過(guò)對(duì)commit日志的規(guī)范，有助于代碼的review
、日志的自動(dòng)化生成以及項(xiàng)目發(fā)版，同時(shí)能夠很好地熟悉git工作流。在該項(xiàng)目中不涉及發(fā)版，只是簡(jiǎn)單的開(kāi)發(fā)，所以只是遵循了部分規(guī)范，在實(shí)際工作中，如果團(tuán)隊(duì)剛好涉及到git工作流的規(guī)范，那肯定是要遵循的。
Git commit日志基本規(guī)范
基礎(chǔ)語(yǔ)法模板
<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>
規(guī)范的基本說(shuō)明：
type代表本次提交的類(lèi)型，是新增feature還是修復(fù)bug或是修改文檔等，主要類(lèi)型及其說(shuō)明如下：
- feat：新增feature
- fix: 修復(fù)bug
- docs: 僅僅修改了文檔，比如README, CHANGELOG, CONTRIBUTE等等
- style: 僅僅修改了空格、格式縮進(jìn)、都好等等，不改變代碼邏輯
- refactor: 代碼重構(gòu)，沒(méi)有加新功能或者修復(fù)bug
- perf: 優(yōu)化相關(guān)，比如提升性能、體驗(yàn)
- test: 測(cè)試用例，包括單元測(cè)試、集成測(cè)試等
- chore: 改變構(gòu)建流程、或者增加依賴(lài)庫(kù)、工具等
- revert: 回滾到上一個(gè)版本
scope表明本次修改的范圍或者模塊，例如users。
subject是對(duì)變更內(nèi)容的簡(jiǎn)要描述。
BLANK LINE不用說(shuō)，就是字面意思的空白行。
body是對(duì)本次變更更加詳細(xì)的說(shuō)明，可以是發(fā)起本次變更的原因以及本次變更的解決思路和方法等。
footer處填寫(xiě)相關(guān)連接。
格式要求：
# 標(biāo)題行：50個(gè)字符以?xún)?nèi)，描述主要變更內(nèi)容
# （我是空行）
# 主體內(nèi)容：更詳細(xì)的說(shuō)明文本，建議72個(gè)字符以?xún)?nèi)。 需要描述的信息包括:
# （我是空行）
# * 為什么這個(gè)變更是必須的? 它可能是用來(lái)修復(fù)一個(gè)bug，增加一個(gè)feature，提升性能、可靠性、穩(wěn)定性等等
# * 他如何解決這個(gè)問(wèn)題? 具體描述解決問(wèn)題的步驟
# * 是否存在副作用、風(fēng)險(xiǎn)?
#
# 尾部：如果需要的話可以添加一個(gè)鏈接到issue地址或者其它文檔，或者關(guān)閉某個(gè)issue。
相關(guān)參考
API接口文檔規(guī)范
我寫(xiě)過(guò)的第一個(gè)接口文檔，是word形式的，寫(xiě)了大概三個(gè)接口就受不了了，word寫(xiě)接口，太不舒服了，后來(lái)用showdoc工具寫(xiě)接口文檔，好用了很多，但是沒(méi)有很好地體現(xiàn)文檔的維護(hù)記錄，再后來(lái)，參加工作之后接觸了解了apidoc，相對(duì)而言，它也算主流之一，使用簡(jiǎn)單并且支持多語(yǔ)言，所以就開(kāi)始使用apidoc作為生成接口文檔的工具，接口文檔在代碼中以注解的形式書(shū)寫(xiě)，然后通過(guò)apidoc的相關(guān)命令生成接口文檔，配合git剛好可以很好地體現(xiàn)接口文檔的維護(hù)記錄。當(dāng)然，還有其他選擇，個(gè)人喜好而已。
apidoc編寫(xiě)接口示例
代碼實(shí)例：
/**
* @api {POST} /user create a user
* @apiDescription 用戶(hù)新增的接口
* @apiName 用戶(hù)注冊(cè)
* @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: '該用戶(hù)已經(jīng)存在'
* }
*/
截圖實(shí)例：
相關(guān)參考
這里只確定API接口文檔的生成方式，詳細(xì)的使用后面也不會(huì)過(guò)多涉及，下面附上相關(guān)鏈接。
下面附上項(xiàng)目的github地址：
我的個(gè)人博客：
