很多天前已经翻译了一大半了,今天收收尾~

RESTful API With Node.js + MongoDB

Translated By 林凌灵  

翻译目的:练练手,同时了解别人的思维方式

原文地址:RESTful APIWith Node.js + MongoDB

---

12 Sep 2013

我是一名移动应用开发者,我需要某种后端服务用来频繁地处理用户数据到数据库中.当然,我可以使用后端即服务类的网站(Parse, Backendless, 等等…),(译者:国内比较出名的有Bmob).但自己解决总是更方便和实际的选择.

于是我决定去探索我完全未知的技术领域,那个现在非常流行,定位在容易让新人吸收,并且不需要过于深入了解和处理大型项目经验的项目.

本文将仔细介绍使用Node.js的Express.js框架结合操作MongoDB的Mongoose.js,来给移动APP来搭建一个rest api.对于访问限制,我们将使用 OAuth2orize 和 Passport.js 来实现 OAuth 2.0.

概要

1. Node.js + Express.js, 简洁的 web-server
2. 错误处理
3. RESTful API 要点,增删改查
4. MongoDB & Mongoose.js
5. 访问限制 — OAuth 2.0, Passport.js

1. Node.js + Express.js, 简洁的 web-server

Node.js 没有i/o 阻塞,这对于需要被多个客户端访问的API服务来说是非常棒的.express.js 是一个先进的,轻量级的框架,它能帮助我们快速专注地编写我们需要API.

那么让我们用单个文件server.js来创建一个项目吧~因为我们的项目依赖于Express.js,所以我们将先安装它.安装第三方模块我们将使用Node的包管理器(NPM),很简单.只要在你的项目根目录下:npm install 模块名 .

app.get('/api/articles', function(req, res) {res.send('This is not implemented now');
});app.post('/api/articles', function(req, res) {res.send('This is not implemented now');
});app.get('/api/articles/:id', function(req, res) {res.send('This is not implemented now');
});app.put('/api/articles/:id', function (req, res){res.send('This is not implemented now');    
});app.delete('/api/articles/:id', function (req, res){res.send('This is not implemented now');
});

测试 post/put/delete 我推荐大家使用一个封装了curl 的强大库httpie,我将给出使用这个工具发起请求的例子.

4. MongoDB & Mongoose.js

选择一个数据库,我再次被我渴望新事物的心引导:MongoDB - 最流行的 NoSQL 文档型数据库.Mongoose.js-一层封装,帮助我们更加舒适地创建函数式schema文档.

下载并安装mongodb,然后安装Mongoose : npm install mongoose.我将把数据库交互作为独立的模块放在libs/mongoose.js.

var mongoose    = require('mongoose');
var log         = require('./log')(module);mongoose.connect('mongodb://localhost/test1');
var db = mongoose.connection;db.on('error', function (err) {log.error('connection error:', err.message);
});
db.once('open', function callback () {log.info("Connected to DB!");
});var Schema = mongoose.Schema;// Schemas
var Images = new Schema({kind: {type: String,enum: ['thumbnail', 'detail'],required: true},url: { type: String, required: true }
});var Article = new Schema({title: { type: String, required: true },author: { type: String, required: true },description: { type: String, required: true },images: [Images],modified: { type: Date, default: Date.now }
});// validation
Article.path('title').validate(function (v) {return v.length > 5 && v.length < 70;
});var ArticleModel = mongoose.model('Article', Article);
module.exports.ArticleModel = ArticleModel;

在这个文件中,实现了数据库连接和对象模式定义.文章将包含图片对象.同时也实现了各种各样复杂的验证.

我将使用 nconf 模块 来储存数据库路径.同时,我们把服务器端口也移到这里.安装:npm i nconf .自定义封装将被放在 libs/config.js.

var nconf = require('nconf');nconf.argv().env().file({ file: './config.json' });module.exports = nconf;

All the settings will be stored in config.json at the project’s root.

{"port" : 1337,"mongoose": {"uri": "mongodb://localhost/test1"}
}

mongoose.js changes:

var config      = require('./config');mongoose.connect(config.get('mongoose:uri'));

server.js changes:

var config = require('./libs/config');app.listen(config.get('port'), function(){log.info('Express server listening on port ' + config.get('port'));
});

Let’s add CRUD actions in existing routes.

var ArticleModel    = require('./libs/mongoose').ArticleModel;app.get('/api/articles', function(req, res) {return ArticleModel.find(function (err, articles) {if (!err) {return res.send(articles);} else {res.statusCode = 500;log.error('Internal error(%d): %s',res.statusCode,err.message);return res.send({ error: 'Server error' });}});
});app.post('/api/articles', function(req, res) {var article= new ArticleModel({title: req.body.title,author: req.body.author,description: req.body.description,images: req.body.images});article.save(function (err) {if (!err) {log.info("article created");return res.send({ status: 'OK', article:article });} else {console.log(err);if(err.name == 'ValidationError') {res.statusCode = 400;res.send({ error: 'Validation error' });} else {res.statusCode = 500;res.send({ error: 'Server error' });}log.error('Internal error(%d): %s',res.statusCode,err.message);}});
});app.get('/api/articles/:id', function(req, res) {return ArticleModel.findById(req.params.id, function (err, article) {if(!article) {res.statusCode = 404;return res.send({ error: 'Not found' });}if (!err) {return res.send({ status: 'OK', article:article });} else {res.statusCode = 500;log.error('Internal error(%d): %s',res.statusCode,err.message);return res.send({ error: 'Server error' });}});
});app.put('/api/articles/:id', function (req, res){return ArticleModel.findById(req.params.id, function (err, article) {if(!article) {res.statusCode = 404;return res.send({ error: 'Not found' });}article.title = req.body.title;article.description = req.body.description;article.author = req.body.author;article.images = req.body.images;return article.save(function (err) {if (!err) {log.info("article updated");return res.send({ status: 'OK', article:article });} else {if(err.name == 'ValidationError') {res.statusCode = 400;res.send({ error: 'Validation error' });} else {res.statusCode = 500;res.send({ error: 'Server error' });}log.error('Internal error(%d): %s',res.statusCode,err.message);}});});
});app.delete('/api/articles/:id', function (req, res){return ArticleModel.findById(req.params.id, function (err, article) {if(!article) {res.statusCode = 404;return res.send({ error: 'Not found' });}return article.remove(function (err) {if (!err) {log.info("article removed");return res.send({ status: 'OK' });} else {res.statusCode = 500;log.error('Internal error(%d): %s',res.statusCode,err.message);return res.send({ error: 'Server error' });}});});
});

所以的操作都非常清晰了,感谢Mongoose 和 自解释模型.现在,在我们开始运行node.js 之前,我我们先运行mongodb 服务器:mongo-一个实用的客户端工具用于处理数据库.服务本身就是mongod自己.

使用httpie 发送请求的例子:

<code class="sh hljs" data-origin="" <pre><code="" post="" http:="" localhost:1337="" api="" articles="" title="TestArticle" author="John Doe" description="lorem ipsum dolar sit amet" images:="[{"kind":"thumbnail", "url":"http://habrahabr.ru/images/write-topic.png"}, {"kind":"detail", "url":"http://habrahabr.ru/images/write-topic.png"}]" "="" style="display: block;border: 1px solid rgb(204, 204, 204); white-space: pre; padding: 0.5em; margin: 0px;border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-break: break-all; word-wrap: break-word; border: 1px solid rgb(204, 204, 204); padding: 0px 5px; margin: 0px 2px;font-size: 0.9em; font-family: Consolas, Inconsolata, Courier, monospace;display: block; overflow-x: auto; padding: 0.5em; background-color: rgb(253, 246, 227); color: rgb(101, 123, 131); background-position: initial initial; background-repeat: initial initial;">http POST http://localhost:1337/api/articles title=TestArticle author='John Doe' description='lorem ipsum dolar sit amet' images:='[{"kind":"thumbnail", "url":"http://habrahabr.ru/images/write-topic.png"}, {"kind":"detail", "url":"http://habrahabr.ru/images/write-topic.png"}]'http http://localhost:1337/api/articleshttp http://localhost:1337/api/articles/52306b6a0df1064e9d000003http PUT http://localhost:1337/api/articles/52306b6a0df1064e9d000003 title=TestArticle2 author='John Doe' description='lorem ipsum dolar sit amet' images:='[{"kind":"thumbnail", "url":"http://habrahabr.ru/images/write-topic.png"}, {"kind":"detail", "url":"http://habrahabr.ru/images/write-topic.png"}]'http DELETE http://localhost:1337/api/articles/52306b6a0df1064e9d000003

这个阶段,你可以从github检出本项目

5. 访问控制 — OAuth 2.0, Passport.js

我们将使用 OAuth2. 或许这是多余的,但在将来这种方法将促进与其他授权方法的集成.

Passport.js 模块将负责访问控制.对于OAuth2 服务器,我将使用与其同一个作者的 OAuth2orize ,访问令牌将被储存在MongoDB中.

首先你需要安装下面全部的模块:
Faker
oauth2orize
passport
passport-http
passport-http-bearer
passport-oauth2-client-password

然后,你需要加入 mongoose.js 这个schema 给 users 和 tokens:

var crypto = require('crypto');// User
var User = new Schema({username: {type: String,unique: true,required: true},hashedPassword: {type: String,required: true},salt: {type: String,required: true},created: {type: Date,default: Date.now}
});User.methods.encryptPassword = function(password) {return crypto.createHmac('sha1', this.salt).update(password).digest('hex');//more secure – return crypto.pbkdf2Sync(password, this.salt, 10000, 512);
};User.virtual('userId').get(function () {return this.id;});User.virtual('password').set(function(password) {this._plainPassword = password;this.salt = crypto.randomBytes(32).toString('base64');//more secure - this.salt = crypto.randomBytes(128).toString('base64');this.hashedPassword = this.encryptPassword(password);}).get(function() { return this._plainPassword; });User.methods.checkPassword = function(password) {return this.encryptPassword(password) === this.hashedPassword;
};var UserModel = mongoose.model('User', User);// Client
var Client = new Schema({name: {type: String,unique: true,required: true},clientId: {type: String,unique: true,required: true},clientSecret: {type: String,required: true}
});var ClientModel = mongoose.model('Client', Client);// AccessToken
var AccessToken = new Schema({userId: {type: String,required: true},clientId: {type: String,required: true},token: {type: String,unique: true,required: true},created: {type: Date,default: Date.now}
});var AccessTokenModel = mongoose.model('AccessToken', AccessToken);// RefreshToken
var RefreshToken = new Schema({userId: {type: String,required: true},clientId: {type: String,required: true},token: {type: String,unique: true,required: true},created: {type: Date,default: Date.now}
});var RefreshTokenModel = mongoose.model('RefreshToken', RefreshToken);module.exports.UserModel = UserModel;
module.exports.ClientModel = ClientModel;
module.exports.AccessTokenModel = AccessTokenModel;
module.exports.RefreshTokenModel = RefreshTokenModel;

password虚拟属性举例了mongoose如何方便地在模型中嵌入逻辑.哈希算法和加盐(译者:加密加盐都是为了保护数据)不在本文的讨论范围,它的具体实现这里就不说了.

数据库对象:

User –一个用户有name,password以及相应的盐.
Client – 一个代表用户做出请求的客户端,需要具有name和secretcode.
AccessToken – token (即不记名类型), 颁发给客户端应用的, 具有时间限制(译者:就像cookie里的sessionid).
RefreshToken –另一种类型的token,允许你重新获得一个不记名的token而不需要通过密码获得.

在 config.json中配置token的生存时间:

{"port" : 1337,"security": {"tokenLife" : 3600},"mongoose": {"uri": "mongodb://localhost/testAPI"}
}

我在独立的模块中实现了OAuth2 服务器 以及认证逻辑.在auth.js 和passport.js 中策略已经写好了.我们载入3个策略—两个是用于OAuth2的username-password流的,一个是用于检查token的.

var config                  = require('./config');
var passport                = require('passport');
var BasicStrategy           = require('passport-http').BasicStrategy;
var ClientPasswordStrategy  = require('passport-oauth2-client-password').Strategy;
var BearerStrategy          = require('passport-http-bearer').Strategy;
var UserModel               = require('./mongoose').UserModel;
var ClientModel             = require('./mongoose').ClientModel;
var AccessTokenModel        = require('./mongoose').AccessTokenModel;
var RefreshTokenModel       = require('./mongoose').RefreshTokenModel;passport.use(new BasicStrategy(function(username, password, done) {ClientModel.findOne({ clientId: username }, function(err, client) {if (err) { return done(err); }if (!client) { return done(null, false); }if (client.clientSecret != password) { return done(null, false); }return done(null, client);});}
));passport.use(new ClientPasswordStrategy(function(clientId, clientSecret, done) {ClientModel.findOne({ clientId: clientId }, function(err, client) {if (err) { return done(err); }if (!client) { return done(null, false); }if (client.clientSecret != clientSecret) { return done(null, false); }return done(null, client);});}
));passport.use(newBearerStrategy(function(accessToken, done) {AccessTokenModel.findOne({ token: accessToken }, function(err, token) {if (err) { return done(err); }if (!token) { return done(null, false); }if( Math.round((Date.now()-token.created)/1000) > config.get('security:tokenLife') ) {AccessTokenModel.remove({ token: accessToken }, function (err) {if (err) return done(err);});return done(null, false, { message: 'Token expired' });}UserModel.findById(token.userId, function(err, user) {if (err) { return done(err); }if (!user) { return done(null, false, { message: 'Unknown user' }); }var info = { scope: '*' }done(null, user, info);});});}
));

oauth2.js is responsible for the issuance and renewal of the token. One token exchange strategy is for username-password flow, another is to refresh tokens.

oauth2.js 负责颁发和更新token.其中一个token交互策略是给username-password 流的,另一个是用于刷新token的.

var oauth2orize         = require('oauth2orize');
var passport            = require('passport');
var crypto              = require('crypto');
var config              = require('./config');
var UserModel           = require('./mongoose').UserModel;
var ClientModel         = require('./mongoose').ClientModel;
var AccessTokenModel    = require('./mongoose').AccessTokenModel;
var RefreshTokenModel   = require('./mongoose').RefreshTokenModel;// create OAuth 2.0 server
var server = oauth2orize.createServer();// Exchange username & password for access token.
server.exchange(oauth2orize.exchange.password(function(client, username, password, scope, done) {UserModel.findOne({ username: username }, function(err, user) {if (err) { return done(err); }if (!user) { return done(null, false); }if (!user.checkPassword(password)) { return done(null, false); }RefreshTokenModel.remove({ userId: user.userId, clientId: client.clientId }, function (err) {if (err) return done(err);});AccessTokenModel.remove({ userId: user.userId, clientId: client.clientId }, function (err) {if (err) return done(err);});var tokenValue = crypto.randomBytes(32).toString('base64');var refreshTokenValue = crypto.randomBytes(32).toString('base64');var token = new AccessTokenModel({ token: tokenValue, clientId: client.clientId, userId: user.userId });var refreshToken = new RefreshTokenModel({ token: refreshTokenValue, clientId: client.clientId, userId: user.userId });refreshToken.save(function (err) {if (err) { return done(err); }});var info = { scope: '*' }token.save(function (err, token) {if (err) { return done(err); }done(null, tokenValue, refreshTokenValue, { 'expires_in': config.get('security:tokenLife') });});});
}));// Exchange refreshToken for access token.
server.exchange(oauth2orize.exchange.refreshToken(function(client, refreshToken, scope, done) {RefreshTokenModel.findOne({ token: refreshToken }, function(err, token) {if (err) { return done(err); }if (!token) { return done(null, false); }if (!token) { return done(null, false); }UserModel.findById(token.userId, function(err, user) {if (err) { return done(err); }if (!user) { return done(null, false); }RefreshTokenModel.remove({ userId: user.userId, clientId: client.clientId }, function (err) {if (err) return done(err);});AccessTokenModel.remove({ userId: user.userId, clientId: client.clientId }, function (err) {if (err) return done(err);});var tokenValue = crypto.randomBytes(32).toString('base64');var refreshTokenValue = crypto.randomBytes(32).toString('base64');var token = new AccessTokenModel({ token: tokenValue, clientId: client.clientId, userId: user.userId });var refreshToken = new RefreshTokenModel({ token: refreshTokenValue, clientId: client.clientId, userId: user.userId });refreshToken.save(function (err) {if (err) { return done(err); }});var info = { scope: '*' }token.save(function (err, token) {if (err) { return done(err); }done(null, tokenValue, refreshTokenValue, { 'expires_in': config.get('security:tokenLife') });});});});
}));// token endpoint
exports.token = [passport.authenticate(['basic', 'oauth2-client-password'], { session: false }),server.token(),server.errorHandler()
]

在server.js加载这个模块:

var oauth2 = require('./libs/oauth2');app.use(passport.initialize());require('./libs/auth');app.post('/oauth/token', oauth2.token);app.get('/api/userInfo',passport.authenticate('bearer', { session: false }),function(req, res) {// req.authInfo is set using the `info` argument supplied by// `BearerStrategy`.  It is typically used to indicate scope of the token,// and used in access control checks.  For illustrative purposes, this// example simply returns the scope in the response.res.json({ user_id: req.user.userId, name: req.user.username, scope: req.authInfo.scope })}
);

例如,限制访问localhost:1337/api/userInfo.

To check the auth logic we should create a user and a client in our database. Use this node application, which will create the necessary objects and remove redundant from collections. It helpsquickly clean the tokens and users for testing.

这个检查逻辑,我们需要在数据库创建一个user和client.我们将使用node程序来创建必要的对象和移除冗余的集合.这可以帮助我们在测试时迅速地清空token

var log                 = require('./libs/log')(module);
var mongoose            = require('./libs/mongoose').mongoose;
var UserModel           = require('./libs/mongoose').UserModel;
var ClientModel         = require('./libs/mongoose').ClientModel;
var AccessTokenModel    = require('./libs/mongoose').AccessTokenModel;
var RefreshTokenModel   = require('./libs/mongoose').RefreshTokenModel;
var faker               = require('Faker');UserModel.remove({}, function(err) {var user = new UserModel({ username: "andrey", password: "simplepassword" });user.save(function(err, user) {if(err) return log.error(err);else log.info("New user - %s:%s",user.username,user.password);});for(i=0; i<4; i++) {var user = new UserModel({ username: faker.random.first_name().toLowerCase(), password: faker.Lorem.words(1)[0] });user.save(function(err, user) {if(err) return log.error(err);else log.info("New user - %s:%s",user.username,user.password);});}
});ClientModel.remove({}, function(err) {var client = new ClientModel({ name: "OurService iOS client v1", clientId: "mobileV1", clientSecret:"abc123456" });client.save(function(err, client) {if(err) return log.error(err);else log.info("New client - %s:%s",client.clientId,client.clientSecret);});
});
AccessTokenModel.remove({}, function (err) {if (err) return log.error(err);
});
RefreshTokenModel.remove({}, function (err) {if (err) return log.error(err);
});setTimeout(function() {mongoose.disconnect();
}, 3000);

如果你使用dataGgen.js,用一下命令测试授权将适合你.这里我们再次看看httpie的使用.

http POST http://localhost:1337/oauth/token grant_type=password client_id=mobileV1 client_secret=abc123456 username=andrey password=simplepasswordhttp POST http://localhost:1337/oauth/token grant_type=refresh_token client_id=mobileV1 client_secret=abc123456 refresh_token=TOKENhttp http://localhost:1337/api/userinfo Authorization:'Bearer TOKEN'

注意!在生产环境尽量使用HTTPS,这是OAuth2的隐含内容.还有,不要不忘记对密码进行正确的哈希处理.重申一下,你可在github找到这个项目.

开启本例前,你要先运行 npm install在你项目的根目录,然后运行mongod,node dataGen.js (等待它完成),然后运行node server.js.

如果有哪个部分有需要更清楚地描述,请给我留言.

总而言之,我想说node.js是一个伟大的、方便的服务器解决方案。MongoDB面向文档的方法是一个很不同寻常的但又确实是一个有用的工具。它还有很多功能我还不习惯。nodejs有一个很大的社区,有很多开源项目。例如,oauth2orize和password.js就是Jared Hanson带来精彩的项目,这很好地促进了项目的实现。

---

Evgeny Aleksandrov
iOS developer
evgeny@aleksandrov.ws

github.com/ealeksandrov
twitter.com/ealeksandrov