实践Node.js项目：打造可扩展的Web应用

【编者按】Node.js是一个用于创建Web服务的平台，以创新设计和高效著称。《Node.js项目实践：构建可扩展的Web应用》通过专业的讲解方式，帮助开发者逐步学习如何使用专业的开发工具构建一系列基于Node.js的Web应用。下面为该书的节选内容。

使用Express.js和Hapi构建Node.js REST API服务

在当下的Web开发中，瘦客户端和瘦服务端的架构变得越来越流行，瘦客户端一般基于Backbone.js、Anglers JS、Ember.js等框架构建，而瘦服务端通常代表着REST风格的Web API服务。这种模式现在越来越流行，已经有Parse.com等不少网站选择尝试把后端建成服务的形式。它有如下一些优点：

• 只需要一套REST API接口，便可以同时为多种客户端提供服务，其中也包括Web应用（还有移动端以及第三方应用等）。
• 把客户端和服务分离开还有一点好处，以后更换客户端时不会影响到核心的业务逻辑，同样，更换服务端也不会。
• 由于用户界面（UI/UX）本身是难以进行自动化测试的，尤其是使用了事件驱动的用户界面以及单页面应用等，同时跨浏览器情形更加大了测试的难度。但是，当我们把业务逻辑分开成不同的后端API之后，对逻辑部分的测试（无论是功能测试还是单元测试）就变得十分容易了。

因此，现在许多新项目都选择使用REST API加客户端的方式进行开发。虽然有些项目开发初期只需要Web端，但是开发者应该会预见到，当项目需要再开发新的客户端时，他们可以省去不少重复性的工作。

这一章中我们将会介绍如何使用Node.js构建REST API服务，将分为以下小节：

• RESTful API基础
• 项目依赖
• 使用Mocha和superagent进行测试
• 使用Express和Mongoskin构建REST API服务器
• 重构：基于Hapi.js的REST API服务器

REST API服务能够处理创建、检索、修改、删除对象的请求。为了方便查看，本章所有代码都放在practicalnode中的ch8文件夹中。

注意：在本章的示例中，我们将使用一种“不加分号”的风格，分号在JavaScript中本就是可有可无的。除非在for循环中或在以括号开头的表达式或代码段（例如，立即调用函数（iiFe））之前。使用这种风格是为了给你一种不同的编码体验，它可加快编码速度，也可以使代码看起来更加美观，同时还能提高代码的一致性，因为开发者经常会遗漏分号（遗漏分号不会影响程序的正常运行），此外还有一些人认为减少分号有助于提高代码的可读性。

RESTful API基础

分布式系统的逐渐增多，促进了RESTful API的流行，因为在分布式系统中，每次请求都需要携带关于客户端的足够的信息。从某种意义上讲，RESTful是无状态的，因为没有任何关于客户端状态的信息被存储在服务器上，这样也就保证了每次请求都能够被任意服务器处理，而得到相同的结果。

RESTful的独立特性包括以下几种（换句话说，如果API是RESTful的，它通常会遵循这些原则）：

• RESTful API具有更好的可扩展性的支持，因为不同的组件可以独立部署到不同的服务器上。
• 它使用简单的动作和内容替换SOAP（Simple Object Access Protocol）协议。
• 它使用不同的HTTP请求方式，如GET、POST、DELETE、PUT、OPTIONS等。
• JSON并不是唯一可选的内容格式（不过它是最流行的），可选的格式还有可扩展标记语言（Extensible Markup Language，XML）、逗号分隔值（comma-separated values，CSV）等。这一点不同于SOAP，后者是一种协议，而RESTful作为一种设计风格，在内容格式的选择上更加灵活。

表1所示的是一组对消息进行增删改查（CRUD）操作的REST API的示例。

表1 REST API风格的CURD操作示例

REST并不是一种协议，它是一种架构，相比我们熟悉的SOAP等协议，它更加灵活。REST API的地址可以类似这种/messages/list.html或者这种/messages/list.xml，它取决于我们期望使用的内容格式。

PUT和DELETE请求是幂等的，换句话说，当服务器收到多条相同的请求时，均能得到相同的结果。

GET请求同样是幂等的。但是POST请求是非幂等的，所以重复请求可能会引发状态改变或其他未知异常。

我们实现REST API服务器时利用Express.js中间件的app.param和app.use方法，执行CURD操作。所以，我们的应用需要能够处理以下几种地址格式的请求，并返回JSON格式的数据（collectionName代表了集合，如消息、评论、用户等）：

• POST/collections/{collectionName}：请求创建一个对象，返回新建对象的ID
• GET/collections/{collectionName}/{id}：根据请求ID返回查询到的对象
• GET/collections/{collectionName}/：请求返回集合中的全部元素，在这个例子中，限制最多返回10个元素，并根据ID排序
• PUT/collections/{collectionName}/{id}：根据请求ID更新相应的对象
• DELETE/collections/{collectionName}/{id}：根据请求ID删除相应的对象

项目依赖

现在开始我们的项目，第一步是安装项目依赖的组件。在这一章中，我们会使用到Mongoskin——一个MongoDB操作库，它比原生的MongoDB Node.js驱动使用起来方便很多。此外，相比Mongoose，Mongoskin更轻量而且是无模式的。如果希望了解更多信息，可以参看这里的对比
https://github.com/kissjs/node-mongoskin#comparation。

Express.js是一个对Node.js核心http模块进行包装的库。它架构在Connect中间件之上，为开发者提供了相当多的便利。有些人可能会拿Express.js框架和Ruby的Sinatra框架进行对比，因为它们的特征都是特别灵活并且可配置性强。

首先，需要创建一个ch8/rest-express文件夹：

$ mkdir rest-express$ cd rest-express

我们在上一章提到过，Node.js/NPM提供了多种方式安装依赖，包括：

• 手动一个个安装
• 把依赖写入到package.json文件中
• 下载并复制模块目录

为了简单起见，我们这里使用第二种，也就是写到package.json文件中。你需要创建一个package.json文件，然后把依赖模块相关的部分复制进去，也可以复制下面的整个文件：

{"name": "rest-express","version": "0.0.1","description": "REST API application with Express, Mongoskin, MongoDB, Mocha and Superagent","main": "index.js","directories": {"test": "test"},"scripts": {  "test": "mocha test -R spec"},"author": "AzatMardan","license": "BSD","dependencies": {  "express": "4.1.2",  "mongoskin": "1.4.1",  "body-parser": "1.0.2",  "morgan": "1.0.1" },  "devDependencies": {    "mocha": "1.16.2",   "superagent": "0.15.7",   "expect.js": "0.2.0"}}

然后，只需要执行一行命令就可以安装应用程序所依赖的模块了：

$ npm install

完成之后，node_modules文件夹中会多出几个子文件夹：superagent、express、mongoskin以及expect等。如果你希望更改package.json定义的模块版本，请一定查阅模块的更新日志，获取模块准确的版本号。

使用Mocha和Superagent进行测试

在实现应用之前，我们首先来编写测试用例，用来测试将要实现的REST API服务器。在TDD模式中，可以借助这些测试用例来创建一个脱离Node.js的JSON REST API服务器，这里会使用到Express.js框架和操作MongoDB的Mongoskin库。

在这一节中，我们借助Mocha和superagent库。这个测试是通过发送HTTP请求到服务器执行基本的CURD操作。

如果你已经了解Mocha的使用，或者希望直接进入Express.js应用的实现部分，你可以跳过这一小节。你也可以直接在命令行中使用curl命令进行测试。

假设我们的环境中已经安装了Node.js、NPM和MongoDB，现在创建一个新文件夹（或者就使用你写测试用例的文件夹）。我们使用Moncha作为命令行工具，然后用Express.js和superagent作为本地库。用下面的命令安装Mocha CLI（如果不行的话请参考$ mocha -V），在终端运行下面这行命令：

提示：我们可以把Mocha库安装到项目文件夹中，这样便可以在不同的项目中使用不同版本的Mocha，在测试时只需要进入
./node_modules/mocha/bin/mocha目录即可。还有一种更好的办法，就是使用Makefile。

现在让我们在这个ch8/rest-express文件夹中创建一个test/index.js文件，它将包含6个测试用例：

1. 创建一个新对象
2. 通过对象ID检索对象
3. 检索整个集合
4. 通过对象ID更新对象
5. 通过对象ID检查对象是否更新
6. 通过对象ID删除对象

SuperAgent的链式函数使发送HTTP请求变成一件很容易的事，这里每个用例中都会用到。文件从引入依赖模块开始：

var superagent = require('superagent')var expect = require('expect.js')

然后，我们开始写第一个测试用例，它被包括在一个用例组（包含描述信息和回调函数）中。测试的思想非常简单。我们创建一系列发送到本地服务器的HTTP请求（由superagent发出），不同的用例发送到不同的URL，在请求中会携带一些数据，并把处理逻辑写在请求的回调函数中。TDD中的多个断言之间的关联非常紧密，就像面包和黄油一样。

如果需要严格的测试，可以考虑BDD模式，但这里我们的项目还不需要。

describe('express rest api server', function{  var id it('post object', function(done){   superagent.post('http://localhost:3000/collections/test')    .send({ name: 'John',      email: 'john@rpjs.co'    })   .end(function(e,res){     expect(e).to.eql(null)     expect(res.body.length).to.eql(1)     expect(res.body[0]._id.length).to.eql(24)     id = res.body[0]._id   done})})

如你所见，我们检查了下面这些内容：

• 返回的错误对象需要为空（eql(null)）
• 响应对象的数组应该含有且只含有一个元素（to.eql(1)）
• 第一个响应对象中应该包含一个24字节长度的_id属性，它是一个标准的MongoDB对象ID类型。

我们把新创建的对象的ID保存到全局变量中，在后面的查找、更新以及产出操作中还会用到。这里有一个用例用来测试检索对象。注意一下，这里superagent的请求方法改成了get，而且需要在URL中包含对象ID。你可以把console.log的注释取消掉，这样就可以在控制台中查看到完整的HTTP响应数据：

it('retrieves an object', function(done){  superagent.get('http://localhost:3000/collections/test/'+id)   .end(function(e, res){     expect(e).to.eql(null)     expect(typeofres.body).to.eql('object')     expect(res.body._id.length).to.eql(24)     expect(res.body._id).to.eql(id)     done  })})

在测试异步代码中，不要漏掉这里的done函数，否则Mocha的测试程序会在收到服务器响应之前结束。

接下来的用例在处理响应返回的ID数组时用到了map函数，使它显得更有趣一些。我们使用contain方法在这个数组中查找我们的ID（存在id变量中），它比原生的indexOf方法更加优雅。得到的结果会保留最多不超过10条记录，按照ID倒序排序，由于我们的对象刚刚添加进去，所以会在第一条：

it('retrieves a collection', function(done){  superagent.get('http://localhost:3000/collections/test')    .end(function(e, res){      expect(e).to.eql(null)      expect(res.body.length).to.be.above(0)      expect(res.body.map(function (item){         returnitem._id      })).to.contain(id)     done   })})

接下来要测试的是更新对象。通过给superagent的请求函数传一个参数对象，向服务端提交一些数据，然后断言这个操作返回的结果是msg=success：

it('updates an object', function(done){    superagent.put('http://localhost:3000/collections/test/'+id)     .send({name: 'Peter',       email: 'peter@yahoo.com'})     .end(function(e, res){       expect(e).to.eql(null)       expect(typeofres.body).to.eql('object')       expect(res.body.msg).to.eql('success')       done    })})

最后两个用例，一个是还原前面做的修改，另一个是删掉这个对象，和前面两个测试用例的做法非常类似。下面是完整的
ch8/rest-express/test/index.js文件的代码：

var superagent = require('superagent')var expect = require('expect.js')describe('express rest api server', function{  var id  it('post object', function(done){    superagent.post('http://localhost:3000/collections/test')      .send({ name: 'John',        email: 'john@rpjs.co'      })      .end(function(e,res){        expect(e).to.eql(null)        expect(res.body.length).to.eql(1)        expect(res.body[0]._id.length).to.eql(24)        id = res.body[0]._id        done      })})it('retrieves an object', function(done){  superagent.get('http://localhost:3000/collections/test/'+id)      .end(function(e, res){        expect(e).to.eql(null)        expect(typeofres.body).to.eql('object')        expect(res.body._id.length).to.eql(24)        expect(res.body._id).to.eql(id)        done    })})it('retrieves a collection', function(done){  superagent.get('http://localhost:3000/collections/test')    .end(function(e, res){      expect(e).to.eql(null)      expect(res.body.length).to.be.above(0)      expect(res.body.map(function (item){         return item._id      })).to.contain(id)      done   })})it('updates an object', function(done){  superagent.put('http://localhost:3000/collections/test/'+id)    .send({name: 'Peter',      email: 'peter@yahoo.com'})    .end(function(e, res){      expect(e).to.eql(null)      expect(typeofres.body).to.eql('object')      expect(res.body.msg).to.eql('success')      done    })})it('checks an updated object', function(done){  superagent.get('http://localhost:3000/collections/test/'+id)    .end(function(e, res){      expect(e).to.eql(null)      expect(typeofres.body).to.eql('object')      expect(res.body._id.length).to.eql(24)      expect(res.body._id).to.eql(id)      expect(res.body.name).to.eql('Peter')      done    })})it('removes an object', function(done){  superagent.del('http://localhost:3000/collections/test/'+id)    .end(function(e, res){      expect(e).to.eql(null)      expect(typeofres.body).to.eql('object')      expect(res.body.msg).to.eql('success')      done    })  })})

现在我们来运行这个测试，在命令行中运行$mocha test/index.js或者npm test。不过得到的结果一定是失败，因为服务器还没有启动。

如果你有多个项目，需要使用多个版本的Mocha，那么你可以把Mocha安装到项目目录的node_modules文件夹下，然后执行：
./node_modules/mocha/bin/mocha./test。

注意：默认情况下，Mocha只返回少量的信息。如果需要得到更详细的结果，可以使用-R<name>参数(即：$ mocha test -R spec或者$ mocha test-R list)。

使用Express和Mongoskin实现REST API服务器

现在我们创建一个ch8/rest-express/index.js文件作为程序的入口文件。

首先，当然是引入所有的依赖组件：

var express = require('express'),   mongoskin = require('mongoskin'),   bodyParser = require('body-parser'),   logger = require('morgan')

Express.js从3.x版本开始，简化了实例化应用的方法，使用下面一行代码来创建一个服务器对象：

var app = express

我们使用bodyParser.urlencoded和bodyParser.json两个中间件从响应体中提取参数和数据。通过app.use函数调用这些中间件（这些代码看起来似乎更像是配置语句）：

app.use(bodyParser.urlencoded)app.use(bodyParser.json)app.use(logger)

express.logger中间件并不是必需的，它的作用是方便我们监控请求。中间件是Express.js和Connect中一种非常强大的设计，它使组织和复用代码变得十分简便。

express.urlencoded和express.json可以帮我们省去解析HTTP响应体的麻烦，Mongoskin则帮我们实现了用一行代码连接到MongoDB数据库：

注意：如果你需要连接到远程数据库（例如，MongoHQ），需要使用到统一资源标示符（URI）（注意，其中不含空格）：mongodb://[username:password@]host1[:port1][,host2[:port2],... [,hostN[:portN]]][/[database][?options]]，用你真实的用户名、密码、主机地址、端口号替换其中对应的位置。

下面的语句是一个辅助函数，用来把普通的十六进制字符串转化成MongoDB ObjectID数据类型：

var id = mongoskin.helper.toObjectID

app.param方法是Express.js中间件的另一种形式。它的作用是当URL中出现对应的参数时进行一些操作。在我们这个例子中，当URL中出现以冒号开头的collectionName（在后面的路由规则中能看到）时，我们会选择一个特定的集合：

app.param('collectionName', function(req, res, next, collectionName){   req.collection = db.collection(collectionName)   return next})

为了达到更好的用户体验，这里添加一个根路由，用来提示用户在他们访问的URL中包含要查找的集合名字：

app.get('/', function(req, res, next) {   res.send('Select a collection, e.g., /collections/messages')})

下面是非常重要的逻辑，它实现了对列表按_id属性进行排序，并限制最多只返回10个元素：

app.get('/collections/:collectionName', function(req, res, next) {   req.collection.find({},{      limit:10, sort: [['_id',-1]]   }).toArray(function(e, results){      if (e) return next(e)      res.send(results)   })})

不知道你注意到URL中出现的:collectionName字符串没有？它配合之前的app.param中间件，给我们提供了一个req.collection对象，我们把它指向数据库中一个特殊的集合。

创建对象的接口（
POST/collections/:collectionName）比较容易，因为我们只需要把整个请求传给MongoDB就行了。

app.post('/collections/:collectionName', function(req, res, next) {   req.collection.insert(req.body, {}, function(e, results){      if (e) return next(e)      res.send(results)   })})

这种方法，或者叫架构，通常被称作“自由JSON格式的REST API”，因为客户端可以抛出任意格式的数据，而服务器总能进行正常的响应（一个非常好的例子是刚被Facebook收购的Parse.com的后端接口）。

检索单一对象的方法比find方法速度更快，但是它们使用的是不同的接口（请注意，前者会直接返回结果对象，而不是句柄）。同样，我们借助Express.js的魔法，从:id中提取到ID参数，它被保存在req.params.id中：

app.get('/collections/:collectionName/:id', function(req, res, next) {   req.collection.findOne({      _id: id(req.params.id)   }, function(e, result){     if (e) return next(e)     res.send(result)   })})

PUT请求的有趣之处在于，update方法返回的不是变更的对象，而是变更对象的计数。同时，{$set:req.body}是一种特殊的MongoDB操作（操作名以$符开头），它用来设置值。

第二个参数{safe:true,multi:false}是一个保存配置的对象，它用来告诉MongoDB，等到执行结束后才运行回调，并且只处理一条（第一条）请求。

app.put('/collections/:collectionName/:id', function(req, res, next) {  req.collection.update({     _id: id(req.params.id)   }, {$set:req.body}, {safe:true, multi:false},   function(e, result){     if (e) return next(e)     res.send((result === 1) ? {msg:'success'} : {msg:'error'})    }  );})

最后一个，DELETE请求，它同样会返回定义好的JSON格式的信息（JSON对象包含一个msg属性，当处理成功时它的内容是字符串success，如果处理失败则是编码后的错误消息）：

app.del('/collections/:collectionName/:id', function(req, res, next) {  req.collection.remove({    _id: id(req.params.id)   },   function(e, result){     if (e) return next(e)     res.send((result === 1) ? {msg:'success'} : {msg:'error'})    }  );})

注意：在Express.js中，app.del方法是app.delete方法的一个别名。

最后一行代码用来启动服务器，并监听3000端口：

app.listen(3000, function{   console.log ('Server is running')})

下面是Express.js 4.1.2 REST API服务器的完整代码（ch8/rest-express/index.js），供你参考：

var express = require('express'),  mongoskin = require('mongoskin'),  bodyParser = require('body-parser'),  logger = require('morgan')var app = expressapp.use(bodyParser.urlencoded)app.use(bodyParser.json)app.use(logger)var db = mongoskin.db('mongodb://@localhost:27017/test', {safe:true})var id = mongoskin.helper.toObjectIDapp.param('collectionName', function(req, res, next, collectionName){  req.collection = db.collection(collectionName)  return next})app.get('/', function(req, res, next) {  res.send('Select a collection, e.g., /collections/messages')})app.get('/collections/:collectionName', function(req, res, next) {  req.collection.find({}, {limit: 10, sort: [['_id', -1]]})    .toArray(function(e, results){       if (e) return next(e)         res.send(results)       }    )})app.post('/collections/:collectionName', function(req, res, next) {  req.collection.insert(req.body, {}, function(e, results){    if (e) return next(e)    res.send(results)  })})app.get('/collections/:collectionName/:id', function(req, res, next) {  req.collecjtion.findOne({_id: id(req.params.id)}, function(e, result){    if (e) return next(e)    res.send(result)  })})app.put('/collections/:collectionName/:id', function(req, res, next) {  req.collection.update({_id: id(req.params.id)},    {$set: req.body},    {safe: true, multi: false}, function(e, result){    if (e) return next(e)    res.send((result === 1) ? {msg:'success'} : {msg:'error'})  })})app.del('/collections/:collectionName/:id', function(req, res, next) {  req.collection.remove({_id: id(req.params.id)}, function(e, result){    if (e) return next(e)    res.send((result === 1) ? {msg:'success'} : {msg:'error'})  })})app.listen(3000, function{  console.log ('Server is running')})

现在在命令行中执行：

$ node .

这条命令和$ node index是等价的。

然后，新开一个命令行窗口（前面一个不要关），运行测试程序：

$ mocha test

如果希望得到一个更好看的结果报告，可以运行下面这个命令（参见图1）：

$ mocha test -R nyan

图1 谁会不喜欢包含一个Nyan猫的库呢

如果你确实不喜欢Mocha或者BDD（和TDD），CURL是另一种可选方案，它的使用方式如图2所示：

curl <a href="http://localhost:3000/collections/curl-test">http://localhost:3000/collections/curl-test</a>

图2 使用CURL进行一次GET请求

注意：你还可以使用浏览器来发起GET请求。例如，在服务器开启时通过浏览器访问
http://localhost:3000/test。使用CURL发送POST请求也十分方便（参见图3）：

$ curl -d "name=peter&email=peter337@rpjs.co" <a href="http://localhost:3000/collections/">http://localhost:3000/collections/</a>curl-test

图3 通过CURL发送POST请求后收到的响应

发送DELETE或PUT请求需要使用参数--request NAME，当然不要忘记在URL中添加ID，例如：

$ curl --request DELETE <a href="http://localhost:3000/collections/curl-test/52f6828a23985a6565000008">http://localhost:3000/collections/curl-test/52f6828a23985a6565000008</a>