码农《五》

码农（第18期）

Node生态系统：成长，协作，分享

2015-07-22
实用的Node.js参考资料

资源URL

Node.js首页http://nodejs.org/

最新的Nodejs核心文挡http://nodejs.org/api/

Node.js博客http://blog.nodejs.org/

Node.js职位公告板http://jobs.nodejs.org/

Node.js包管理器（npm）的首页http://npmjs.org/

2015-07-22
因为GitHub要用Git，在继续GitHub之前，需要先配置Git。谢天谢地，GitHub分别为Mac、Windows和Linux准备了帮助页面（https://help.github.com/articles/set-up-git），帮你把Git配置好。Git配置好之后，你还需要配置GitHub，在它的网站上注册，并提供一个安全壳（SSH）公钥。SSH秘钥可以确保你跟GitHub交互的安全性。

注意，这些步骤只需要做一次，不是每次往GitHub中添加项目时都需要。1. GIT配置和GITHUB注册

要用GitHub，得配置好你的Git工具。你需要用下面这两条命令提供你的姓名和邮箱地址：git config --global user.name "Bob Dobbs"

git config --global user.email subgenius@example.com 接下来在GitHub网站上注册。访问注册页面（[https://github.com/signup/free](https://github.com/signup/free)），，填好表单，点击创建账号。

2015-07-22
2. 给GITHUB一个SSH公钥

注册完之后，你需要给GitHub一个SSH公钥（https://help.github.com/articles/generating-ssh-keys）。你将用这个公钥对Git事务进行验证。按照下面这些步骤操作：1. 在浏览器中访问https://github.com/settings/ssh；

2. 点击添加SSH秘钥。到这里后，你需要做什么就取决于你使用的操作系统了。GitHub会检测出你的操作系统，并给出相应的指令。

2015-07-22
添加一个项目到GitHub中

在GitHub上安顿好之后，你就可以往自己的账号下添加项目，提交内容了。为此你需要先为项目创建一个GitHub库，稍后详细介绍。之后在你的本地机器上创建一个Git库，在把作品推送到GitHub库之前你就在那里完成它。图4列出了这个过程。

2015-07-22
你还可以用GitHub的Web界面查看项目文件。

1. 创建一个GitHub库在GitHub上创建库需要下面这些步骤：

1. 在Web浏览器中登入github.com；2. 访问https://github.com/new；3. 填好结果表单，描述你的库，然后点击创建库；

4. GitHub为你的项目创建了一个空白的Git库和一个问题列表；5. GitHub会给出你用Git把代码推送到GitHub中所需的步骤。

理解这些步骤做了什么会对你有帮助的，所以我们会做一个例子来阐明Git最基本的用法。

2015-07-22
2. 设置一个空白的Git库

要往GitHub中添加一个示例项目，需要先创建一个Node模块的例子。我们要创建一个能缩短URL的模块，node-elf。先用下面的命令给项目创建一个临时目录：mkdir -p ~/tmp/node-elf

cd ~/tmp/node-elf 为了把这个目录当作Git库，需要输入下面的命令（它会创建一个.git目录存放库的元数据）：

git init

2015-07-22
3. 向Git库中添加一个文件

空白库设置好了，你可能想添加一些文件进去。作为例子，我们会添加一个包含URL缩短逻辑的文件。把下面的代码放到这个目录下名为index.js的文件里。代码清单1　缩短URL的Node模块

exports.initPathData = function(pathData) { //由shorten() 和expand()隐含调用的初始化函数

pathData = (pathData) ? pathData : {}; pathData.count = (pathData.count) ? pathData.count : 0;

pathData.map = (pathData.map) ? pathData.map : {}; }

exports.shorten = function(pathData, path) { //接受一个 “path”字符串，并返回一个跟它对应的短化URL

exports.initPathData(pathData); pathData.count++;

pathData.map[pathData.count] = path; return pathData.count.toString(36);

} exports.expand = function(pathData, shortened) { //接受之

前短化的URL并返回展开的URL exports.initPathData(pathData);

var pathIndex = parseInt(shortened, 36); return pathData.map[pathIndex];

} 接下来，让Git知道你想把这个文件放到库中。git的add命令跟其他的版本控制系统不一样。它不是把文件添加到库中，而是添加到Git的临时区。你可以把临时区看成是一个检查表，指明新添加的文件，或你修改过的文件，要把它们包含在库的下一次修订中：

git add index.js 这样Git就知道它应该跟踪这个文件。如果你想，还可以向临时区添加其他文件，但现在有这一个文件就够了。

要让Git知道你想在库中做个新修订，包含你放在临时区中修改过的文件，需要用commit命令。跟其他VCS中一样，commit命令可以用命令行选项-m指定一条消息，描述新修订所做的修改：git commit -m "Added URL shortening functionality."

你本地机器中的库现在已经包含新的修订了。要查看库修改的清单，请输入下面的命令：git log

2015-07-22
4. 从Git推送到GitHub

如果这时候你的机器突然被雷劈了，那所有的工作就要丢了。为了防范这种突发性事件，并充分利用GitHub的Web界面提供的好处，你得把本地Git库中的修改送到你的GitHub账号下。但在做这件事情之前，要先让Git知道应该把修改送到哪里去。为此你需要添加一个Git远程库。它们被称为remotes。下面这条命令就是往你的库上添加GitHub远程库的。用你的用户名替换掉username，注意node-elf.git，这是项目的名称：git remote add origin git@github.com:username/node-elf.git

远程库添加好，现在你可以把修改发送给GitHub了。在Git的术语表中，发送修改被称为库推送。在下面的命令中，你告诉Git把你的工作推送到前面定义的远程库origin中。所有Git库都可以有一或多个分支，从概念上区分库中的不同工作区。你要把工作推送到分支master中：git push -u origin master

推送命令中的选项-u告诉Git这个远程库是上游的远程库和分支。上游远程库是默认使用的远程库。在做过一次带-u的推送后，将来再推送时用下面这条命令就行了，它更好记：git push

如果到GitHub上去刷新你的库页面，应该能见到你的文件了。创建一个模块并把它放到GitHub上是重用它的快捷办法。比如说，如果你想在项目中使用你的样本模块，可以像下面这个例子一样输入这些命令：mkdir ~/tmp/my_project/node_modules

cd ~/tmp/my_project/node_modules git clone https://github.com/mcantelon/node-elf.git elf

cd .. 然后用require('elf')就可以使用这个模块了。注意，在克隆一个库时，命令行中的最后一个参数是你要把它克隆到哪里去的目录名。

你现在已经知道如何把项目添加到GitHub中了，包括如何在GitHub上创建一个库；如何在你的机器上创建Git库，并把文件添加到里面；以及如何把你的机器上的库推送到GitHub中。网上有很多优秀的资源可以支持你继续前行。如果你想寻求全面的Git使用指导，Scott Chacon，GitHub的创建者之一，写了一本非常全面的书，Pro Git，你可以买来看看，或者在线免费阅读（http://progit.org/）。如果你更喜欢手把手教学的方式，Git官方网站的文档页里列出了帮你起步的教程（http://git-scm.com/documentation）。

2015-07-22
用GitHub协作

现在你已经知道如何从头开始创建GitHub库了，接下来我们看看如何用GitHub跟其他人协作。假定你正在用一个第三方模块，并且遇到了bug。你可能会去检查这个模块的源码并找出解决办法，然后你可能会给代码的作者发封邮件，介绍你的解决办法，并把修改过的文件作为附件。但这样那位作者还需要做些繁琐的工作。他/她只能比较你的文件和最新的代码，然后再把修订从你的文件中拿出来放到最新的代码中。但如果这位作者用了GitHub，你可以克隆这个项目库，做些修改，然后通过GitHub的bug修订通知作者。GitHub会在Web页面上展示你的代码和你复制的版本的差异，并且如果bug修订可以接受的话，只需点击一次鼠标就能把你的修订合并到最新的代码中。按GitHub的说法，复制一个库被称为分叉（forking）。对项目分叉后，你可以在你的副本上做任何事情，不用担心对原始库造成影响。分叉不需要得到原作者的许可：任何人都可以分叉任何项目，并把他们的贡献提交回原始项目中。原作者可能不会认可你的贡献，但你仍然可以拥有你自己的修订版，继续独立地维护和增强它。如果你的分叉越来越受欢迎，其他人可能也会分叉你的分叉，并贡献他们自己的成果。

你对分叉做出修改后，可以用一个拉动（pull）请求把这些修改提交给原作者，这是一个询问库作者是否拉动变化进来的消息。拉动，按Git的说法，意是时从分支中引入工作，并合并到自己的工作中。图5描绘了GitHub协作的场景。图5　典型的GitHub开发场景现在我们来看一个为了协作对GitHub库进行分叉的例子。这个过程如图6所示。

2015-07-22
分叉把GitHub上的库复制到你的账号下，开启了协作的过程（称为分叉）（A）。然后你把分叉库克隆到自己的机器上（B），对它进行修改，提交这些修改（C），把你的工作推送会GitHub（D），并给原始库的所有者发送一个拉动请求，让他们考虑下你的修改（E）。如果他们想把你的修改纳入他们的库中，他们就会认可你的拉动请求。

比如说你想分叉的node-elf库，添加代码输出模块的版本号。这样模块的用户就可以肯定他们用的是正确的版本了。首先登入GitHub，进入这个库的主页：https://github.com/mcantelon/node-elf。点击页面上的分叉（Fork）按钮复制该库。结果页面跟原始库的页面类似，不过在库名下有类似“forked from mcantelon/node-elf”的说明。

分叉后，接下来是把库克隆到你的机器上，进行修改，把修改推送给GitHub。下面的命令会对node-elf库做这些操作：mkdir -p ~/tmp/forktest

cd ~/tmp/forktest git clone git@github.com:chickentown/node-elf.git

cd node-elf echo "exports.version = '0.0.2';" >> index.js

git add index.js git commit -m "Added specification of module version."

git push origin master 完成修改的推送后，在分叉库的页面上点击拉动请求（Pull Request），输入标题和消息主体，描述你的修改。点击发送拉动请求（Send Pull Request）。图7是包含常见内容的截屏。

图7　GitHub拉动请求的细节然后拉动请求会被添加到原始库的问题列表上。原始库的所有者可以评审你的修改，点击合并拉动请求（Merge Pull Request）引入它们，输入一条提交消息，点击确认合并（Confirm Merge）。然后这个问题就被自动关闭了。

在你跟别人合作创建出一个优秀的模块后，接下来就要把它推向全世界。最好的办法是把它添加到npm库中。

2015-07-22
为npm库做贡献

假定你这个URL短化的模块已经做了一段时间了，你觉得其他Node用户应该也能用到它。为了推广它，你可以在Node相关的Google群组上发帖，介绍它的功能。但这样你的受众群只是有限的一部分Node用户，并且在人们开始用上你的模块后，他们没办法了解模块的更新情况。为了解决可发现和提供更新的问题，你可以把它发布到npm上。有了npm，你可以轻松定义项目的依赖项，在安装你的模块时把那些依赖项也给自动安装上。如果你创建了一个专门保存内容（比如博客文章）评论的模块，可能会引入一个处理评论数据到MongoDB存储的模块作为依赖项。或者一个提供命令行工具的模块，会有一个解析命令行参数的辅助模块作为依赖项。

看到这里，你已经用npm装过很多东西了，从测试框架到数据库驱动无所不包，但你还什么都没发布过。下面我们要介绍把作品发布到npm上所需的步骤：1. 准备包；

2. 编写包规范；3. 测试包；

4. 发布包。我们从准备包开始。

2015-07-22
准备包

你想跟人分享的任何Node模块都应该搭配上相关资源，比如文档、例子、测试和相关的命令行工具。模块还应该有一个README文件，提供充足的信息让用户能够快速入门。包目录应该用子目录组织起来。表2列出了常规的子目录——bin、docs、example、lib和test——以及它们都用来做什么。

表2　Node项目中的常规子目录目录

用途bin

命令行脚本docs

文档example

程序的例子lib

程序的核心功能test

测试脚本及相关资源包组织好之后，你应该写一个包规范以便准备好把它发布到npm上。

2015-07-22
编写包规范

在把包发布到npm上时，需要包含一个机器可读的包规范文件。这个JSON文件的名称是package.json，其中有模块的相关信息，比如它的名称、描述、版本、依赖项，以及其他特性。Nodejitsu有一个很方便的网站，给出了一个package.json文件样本，当你把鼠标悬停在样本文件的任一部分上时还会显示对该部分内容的解释（http://package.json.nodejitsu.com/）。在package.json文件中，只有名称和版本是必须的。其他都是可选内容，但有一些，如果定义了，会让你的模块可用性更强。比如说bin，如果定义了的话，npm就知道包中的哪些文件是命令行工具，并让它们全局可用。

下面是一个规范样本：{

"name": "elf" , "version": "0.0.1"

, "description": "Toy URL shortener" , "author": "Mike Cantelon <mcantelon@example.com>"

, "main": "index" , "engines": { "node": "0.4.x" }

} 要查看package.json可用选项的完整文档，可以用下面的命令：

npm help json 因为手工生成JSON并不比手工编码XML有趣多少，所以我们来看一些可以让这个过程更轻松的工具。ngen就是这样的工具，装上这个npm包后，会有一个名为ngen的命令行工具。问几个问题之后，ngen会生成一个package.json文件。它还会生成npm包中通常会有的一些其他文件，比如Readme.md文件。

你可以用下面的命令安装ngen：npm install -g ngen 装上ngen后，你会有一个全局的ngen命令，如果你在项目的根目录下运行这个命令，它会问你一些与项目相关的问题，并生成一个package.json文件，以及编写Node包通常会有的其他文件。可能有些生成的文件你并不需要，可以删掉。生成的文件包括一个.gitignore文件，指定一些不应该添加到Git库中的文件和目录。还有一个.npmignore文件，它的作用跟.gitignore文件差不多，让npm知道将包发布到npm上时应该忽略哪些文件。

这里有一个运行ngen命令时的输出样例：Project name: elf

Enter your name: Mike Cantelon Enter your email: mcantelon@gmail.com

Project description: URL shortening library create : /Users/mike/programming/js/shorten/node_modules/

.gitignore create : /Users/mike/programming/js/shorten/ node_modules/.npmignore create : /Users/mike/programming/

js/shorten/node_modules/History.md create : /Users/mike/ programming/js/shorten/node_modules/index.js ...

生成package.json文件是向npm发布中最难的部分。这一步一完成，你就可以准备发布模块了。

2015-07-22
测试和发布包

发布模块到npm上需要三步，我们会逐一介绍：1. 在本地测试包的安装；

2. 如果你还没有，添加一个npm用户；3. 把包发布到npm上。

2015-07-22
1. 测试包的安装

在模块的根目录下使用npm的link命令可以在本地测试包。这个命令让你的包可以在你的机器上全局使用，Node可以像使用由npm安装的包那样使用它。sudo npm link

现在你的项目被全局链接了，你可以在link命令后面放上包名把它装在一个单独的测试目录中：npm link elf

包装好之后，在Node REPL中执行require函数引入这个模块来测试一下，像下面的代码这样。你应该能在结果中看到模块提供的变量或函数：node

> require('elf'); { version: '0.0.1',

initPathData: [Function], shorten: [Function],

expand: [Function] } 如果你的包通过了测试，并且你已经结束了它的开发工作，在模块的根目录下执行npm的unlink命令：

sudo npm unlink 之后你的模块就不再是全局可用的了，但稍后，在你完成模块到npm上的发布之后，你还可以用install命令像平常那样安装它。

测试过npm包之后，接下来是创建npm发布账号，如果你之前没有设置过的话。

2015-07-22
2. 添加npm用户

用下面的命令创建你自己的npm发布账号：npm adduser

它会提示你输入用户名、邮箱地址和密码。如果账号添加成功，你不会看到错误消息。

2015-07-22
3. 发布到npm上

接下来是发布。输入下面的命令把你的包发布到npm上：npm publish

你可能会看到警告，“经不安全的通道发送授权”，但如果你没看到其他错误，说明模块已经成功发布了。你可以用npm的view命令验证你的发布是否成功：npm view elf description 如果你想引入一或多个私有库作为npm包的依赖项，可以。可能你想用一个实用的辅助函数模块，但不把它公开发布到npm上。

要添加私有依赖项，在通常放依赖模块名称的地方，你可以放任何跟其他依赖项的名称不同的名称。在通常放版本号的地方，放Git库的URL。下面的例子是package.json文件的一个片段，最后一个依赖项是私有库："dependencies" : {

"optimist" : ">=0.1.3", "iniparser" : ">=1.0.1",

"mingy": ">=0.1.2", "elf": "git://github.com/mcantelon/node-elf.git"

}, 注意，私有模块也应该包含package.json文件。为了确保这些模块不会因为疏忽被发布出去，你可以在package.json文件中将private属性设为true： "private": true,

现在你已经掌握了设置、测试和发布模块到npm库上的知识。

duokanbookid:af273508f4a34ed08c1fdc43c5a8891a