目录
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(){}
}