目錄
npm包開發規範 1
背景： 2
Npm介紹 2
Npm 管理 2
Npm install 原理 2
Npm install 使用 2
Npm包結構 3
1.README.md 3
2.Package.json 4
Npm包代碼開發註釋規範 5
背景：
團隊開始嘗試使用npm私有倉庫來共享代碼，那就涉及npm的一些使用方法規範以及npm包的開發規範，本文檔既爲代碼共享發佈npm倉庫進行一些參數解釋和npm包發佈的強制要求。
Npm介紹
npm是用來管理nodejs第三方包的一個工具,利用它可以
1.安裝本地包/全局包 ；
2.將自己寫的包發佈到npmjs上面去,供全世界的開發者使用；
npm在安裝好node之後,就會自動安裝到node的安裝目錄中,一般是安裝在node根目錄的node_modules的子文件夾下,比如我的npm就安裝在 C:\Program Files\nodejs\node_modules
如何測試npm是否安裝成功,在終端中輸入 npm -v 如果能出現版本號就表示安裝成功。
Npm 管理
NPM 幫助 Node 完成第三方模塊的發佈、安裝和依賴。可以直接執行$ npm 查看所有命令。
使用$ npm init 可以快速生成一個 package.json 文件。
Npm install 原理
使用 npm install安裝依賴包是 NPM 最常用的功能，例如執行npm install express後，npm 向 registry 查詢模塊壓縮包的網址，下載壓縮包後 NPM 會在當前的 node_module 目錄下創建 express 目錄，將包解壓還原在此。
registry 是 NPM 模塊倉庫提供了一個查詢服務，例如 npmjs.org 的查詢服務網址 https://registry.npmjs.org/ ，加模塊名 https://registry.npmjs.org/vue 就得到包含 Vue 模塊所有版本的信息 JSON 對象，也可以使用$ npm view vue查詢。
Node 項目使用require(‘express’)引入 express 模塊時，require()方法在路徑分析時按照模塊路徑查找策略，沿當前路徑向上逐級查找node_module目錄，最終定位到 express 目錄。
包的安裝和模塊引入是相輔相成的， 可以進一步理解 Node 模塊加載原理。
Npm install 使用
npm install默認將包和 package.json 的依賴關係保存在dependencies，但在可以通過一些額外的標誌來控制它們的保存位置和方式：
-P or --save or --save-prod: 依賴在dependencies，默認值.
-D or --save-dev: 依賴在 devDependencies.
-O or --save-optional: 依賴在 optionalDependencies.
--no-save: 防止包依賴保存在 dependencies.
例如 npm install express -D 就會將 express 依賴關係保存在devDependencies。
在npm install一個模塊時經常糾結要安裝在devDependencies還是dependencies，從字面意思看前者用於生產環境，後者用於開發環境。
在官方的定義中，如果環境變量 NODE_ENV 設置爲 production，執行 npm install --production 時 npm 會默認安裝dependencies裏面的依賴項，不會去安裝devDependencies裏的。並且推薦dependencies裏配置正式運行時必須依賴的插件，devDependencies通常用來放我們開發或測試的工具，比如 Webpack，Gulp，babel，eslint等。
在實際開發過程中，Node 包的安裝是依據 require/import 模塊機制，無論是-P還是-D指令都會把依賴下載到 node_modules 文件夾，-P還是-D只是修改了dependencies對象，在安裝這個庫進行開發調試的時候，可以通過npm install一鍵安裝這兩個目錄下所有的依賴。
Npm包結構
------ src // 源代碼目錄 比如coffee,typescript,es6+等代碼的目錄
------ lib // 轉義生成的代碼目錄，比如babel轉義後的es5代碼的目錄
------ docs // 代碼相關的設計和使用文檔
------ README.md // 包說明
-------package.json // 用於定義了這個項目所需要的各種模塊，以及項目的配置信息（比如名稱、版本、許可證等元數據）
在這裏邊有兩個是比較重要的配置和編寫要求的文件一個是README.md另一個是package.json文件
1.README.md
1.1README.md作用及規範
作用：
README.md文件是一個npm包的入門手冊，裏面介紹了npm包達到什麼樣子的效果、需要搭建什麼樣的環境、具備什麼樣的技能等等。所以README文件寫得好不好，關係到這個項目能不能更容易的被其他人使用。下面詳細的介紹一下README.md文件要怎麼寫可以更好更直觀。
命名規範：
(1) README採用全大寫，主要是可以跟代碼文件直觀的區分開，readme.md乍一看有點像是代碼文件，不夠直觀。這不夠體現出它優先其他工程文件被閱讀的初衷；
(2) README文件的後綴名採用是.md。該種後綴的文件主要是採用markdown規則編寫的。採用markdown規則可以很方便的在文本中添加格式，編寫的關注點轉移到文檔內容本身，而不需要像富文本那樣要一直修改內容格式，或者像txt文本文檔那樣沒有格式，會造成閱讀混亂；
內容結構：
(1) [功能描述]：主要描述一下這個項目的主要功能列表。
(2) [開發環境]：羅列使用本工程項目所需要安裝的開發環境及配置，以及所需軟件的版本說明和對應的下載鏈接。
(3) [項目結構簡介]：簡單介紹項目模塊結構目錄樹，對用戶可以修改的文件做重點說明。
(4) [測試DEMO]：此處可以簡單介紹一下DEMO程序的思路，具體實現代碼放在example文件夾中。
(5) [作者列表]：對於多人合作的項目，可以在這裏簡單介紹並感謝所有參與開發的研發人員。
(6) [更新鏈接]：提供後續更新的代碼鏈接。
(7) [歷史版本]：對歷史版本更改 記錄做個簡單的羅列，讓用戶直觀的瞭解到哪些版本解決了哪些問題。
(8) [聯繫方式]：可以提供微信、郵箱等聯繫方式，其他人對這個工程不明白的地方可以通過該聯繫方式與你聯繫。
2.Package.json
2.1.package.json作用及使用簡介
作用：
package.json就是管理你本地安裝的npm包，用於定義了這個項目所需要的各種模塊，以及項目的配置信息（比如名稱、版本、許可證等元數據）。一個package.json文件可以做如下事情：
- 每個Node項目中及第三方包中都必須的；
- 它描述着Node項目或是第三方包的一些信息；
- 透過這些信息可以知道該Node項目或是第三方包運行起來要依賴於哪些第三方包；
- 還可以在裏面寫一些終端執行腳本,在package.json的scripts中進行定義；
- 展示項目所依賴的npm包
- 允許你指定一個包的版本[範圍]
- 讓你建立起穩定，意味着你可以更好的與其他開發者共享
使用簡介:
1.打開終端cmd或是powershell
2.切換到該Node項目的根目錄下面去
3.執行 npm init -y 或是 npm init 生成package.json
4.在開發過程中安裝第三方包的時候這樣寫 npm install --save 或是
npm install --save-dev
注意:
1.使用 npm init -y 的時候一定要注意,項目名稱不能是中文,否則報錯
2.npm init 生成package.json的時候,按照要求一步一步來
3.如果是開發階段需要的第三方包,使用 npm install --save-dev
4.如果是運行階段需要的第三方包,使用 npm install --save
package.json一些重要屬性說明:
name : 項目或是第三方包的名稱,也是其它項目導入時require()中的名稱
description : 這個項目或是第三方包功能的描述
main : 項目或是第三方包的入口文件
license : 授權方式,一般寫MIT
keywords : 發佈到npmjs中之後,其它開發者搜索我們這個第三方包的關鍵
字
scripts : 以後在終端執行的腳本
devDependencies : 開發階段依賴的包
dependencies : 運行階段依賴的包
author : 作者
version : 版本號
Npm包代碼開發註釋規範
註釋說明：
一. data屬性說明：
1、單行屬性，註釋寫在行尾
good:
activeName: ‘actList’,// 活動名稱
bad:
// 活動名稱
activeName: ‘actList’,
2、多行屬性，註釋寫在行上
good:
// 表格配置
tableConfig: [
{
name: “SKU”,
val: “product_model”
}, {
name: “活動已售”,
val: “sold”
}, {
name: “待拼成訂單”,
val: “pending”
},
],
bad:
tableConfig: [ // 表格配置
{
name: “SKU”,
val: “product_model”
}, {
name: “活動已售”,
val: “sold”
}, {
name: “待拼成訂單”,
val: “pending”
},
],
3、Array>Object結構的，只註釋第一個對象內部屬性接可。
good:
tableConfig: [
{
name: “SKU”,//表頭名字
val: “product_model”//對應的接口字
}, {
name: “活動已售”,
val: “sold”
}, {
name: “待拼成訂單”,
val: “pending”
},
],
bad:
tableConfig: [
{
name: “SKU”,//表頭名字
val: “product_model”//對應的接口字
}, {
name: “活動已售”,//表頭名字
val: “sold”//對應的接口字
}, {
name: “待拼成訂單”,//表頭名字
val: “pending”//對應的接口字
},
],
4、Object>簡單類型的，每一個屬性都進行說明，書寫位置，規則如上。
good:
params: {
email: null,// 郵箱
name: null,// 名稱
},
bad:
params: {
// 郵箱
email: null,
// 名稱
name: null,
},
二. props、computed、watch說明：
統一採用行上註釋
三. methods說明：
方法分爲兩種類型：
1、無參型
2、有參型
[1]、無參型，需進行功能說明。格式採用 “//”
good:
// 重置
reset(){
this.params = {}
this.page = 1
this.per_page = 10
this.search()
},
bad:
/**
- @desc 重置
/
reset(){
this.params = {}
this.page = 1
this.per_page = 10
this.search()
},
[2]、有參型，需進行功能、參數、返回值說明。如果是單參的，可以採用雙斜線在功能後追加說明。
good:
// 獲取全選的數組 languages [Array] 獲取數據的表單名稱
filterSelectAll(languages){
let arr = []
for(let i = 0;i<languages.length;i++){
arr.push(languages[i].key)
}
this.selectArr = arr
},
bad:
3、如果是多個參數的，採用多行註釋
good:
/*
*@desc 改變狀態
*@param id [String] 改變對象的id
*@param status [String] 改變對象的status
*@return config [Object] 配置對象
*/
changeStatus(id, status) {
let self = this
return config = {
url: api.changeBannerStatus,
loading: “loading”,
param: {
banner_position_id: id,
status: status
}
};
bad:
// 改變狀態 id [String] 改變對象的id ; status [String] 改變對象的status；return config [Object] 配置對象
changeStatus(id, status) {
let self = this
return config = {
url: api.changeBannerStatus,
loading: “loading”,
param: {
banner_position_id: id,
status: status
}
};
or:
// 改變狀態
// id [String] 改變對象的id
// status [String] 改變對象的status
// config [Object] 配置對象
changeStatus(id, status) {
let self = this
return config = {
url: api.changeBannerStatus,
loading: “loading”,
param: {
banner_position_id: id,
status: status
}
};
四. vue配置項說明：
統一行上註釋，格式 //
good:
export default {
// 組件名稱
name: ‘comName’,
// 父子通信
props: {},
// 註冊組件
components: {},
// 數據
data() {
return {}
},
// 方法
methods: {},
// 數據init
created(){},
// DOM加載完成
mounted(){}
}