编写REST API

REST API规范

编写REST API,实际上就是编写处理HTTP请求的async函数,不过,REST请求和普通的HTTP请求有几个特殊的地方:

  1. REST请求仍然是标准的HTTP请求,但是,除了GET请求外,POST、PUT等请求的body是JSON数据格式,请求的Content-Typeapplication/json
  2. REST响应返回的结果是JSON数据格式,因此,响应的Content-Type也是application/json

REST规范定义了资源的通用访问格式,虽然它不是一个强制要求,但遵守该规范可以让人易于理解。

例如,商品Product就是一种资源。获取所有Product的URL如下:

  1. GET /api/products

而获取某个指定的Product,例如,id为123的Product,其URL如下:

  1. GET /api/products/123

新建一个Product使用POST请求,JSON数据包含在body中,URL如下:

  1. POST /api/products

更新一个Product使用PUT请求,例如,更新id为123的Product,其URL如下:

  1. PUT /api/products/123

删除一个Product使用DELETE请求,例如,删除id为123的Product,其URL如下:

  1. DELETE /api/products/123

资源还可以按层次组织。例如,获取某个Product的所有评论,使用:

  1. GET /api/products/123/reviews

当我们只需要获取部分数据时,可通过参数限制返回的结果集,例如,返回第2页评论,每页10项,按时间排序:

  1. GET /api/products/123/reviews?page=2&size=10&sort=time

koa处理REST

既然我们已经使用koa作为Web框架处理HTTP请求,因此,我们仍然可以在koa中响应并处理REST请求。

我们先创建一个rest-hello的工程,结构如下:

  1. rest-hello/
  2. |
  3. +- .vscode/
  4. | |
  5. | +- launch.json <-- VSCode 配置文件
  6. |
  7. +- controllers/
  8. | |
  9. | +- api.js <-- REST API
  10. |
  11. +- app.js <-- 使用koajs
  12. |
  13. +- controller.js <-- 扫描注册Controller
  14. |
  15. +- package.json <-- 项目描述文件
  16. |
  17. +- node_modules/ <-- npm安装的所有依赖包

package.json中,我们需要如下依赖包:

  1. "dependencies": {
  2. "koa": "2.0.0",
  3. "koa-bodyparser": "3.2.0",
  4. "koa-router": "7.0.0"
  5. }

运行npm install安装依赖包。

app.js中,我们仍然使用标准的koa组件,并自动扫描加载controllers目录下的所有js文件:

  1. const app = new Koa();
  2. const controller = require('./controller');
  3. // parse request body:
  4. app.use(bodyParser());
  5. // add controller:
  6. app.use(controller());
  7. app.listen(3000);
  8. console.log('app started at port 3000...');

注意到app.use(bodyParser());这个语句,它给koa安装了一个解析HTTP请求body的处理函数。如果HTTP请求是JSON数据,我们就可以通过ctx.request.body直接访问解析后的JavaScript对象。

下面我们编写api.js,添加一个GET请求:

  1. // 存储Product列表,相当于模拟数据库:
  2. var products = [{
  3. name: 'iPhone',
  4. price: 6999
  5. }, {
  6. name: 'Kindle',
  7. price: 999
  8. }];
  9. module.exports = {
  10. 'GET /api/products': async (ctx, next) => {
  11. // 设置Content-Type:
  12. ctx.response.type = 'application/json';
  13. // 设置Response Body:
  14. ctx.response.body = {
  15. products: products
  16. };
  17. }
  18. }

在koa中,我们只需要给ctx.response.body赋值一个JavaScript对象,koa会自动把该对象序列化为JSON并输出到客户端。

我们在浏览器中访问http://localhost:3000/api/products,可以得到如下输出:

  1. {"products":[{"name":"iPhone","price":6999},{"name":"Kindle","price":999}]}

紧接着,我们再添加一个创建Product的API:

  1. module.exports = {
  2. 'GET /api/products': async (ctx, next) => {
  3. ...
  4. },
  5. 'POST /api/products': async (ctx, next) => {
  6. var p = {
  7. name: ctx.request.body.name,
  8. price: ctx.request.body.price
  9. };
  10. products.push(p);
  11. ctx.response.type = 'application/json';
  12. ctx.response.body = p;
  13. }
  14. };

这个POST请求无法在浏览器中直接测试。但是我们可以通过curl命令在命令提示符窗口测试这个API。我们输入如下命令:

  1. curl -H 'Content-Type: application/json' -X POST -d '{"name":"XBox","price":3999}' http://localhost:3000/api/products

得到的返回内容如下:

  1. {"name":"XBox","price":3999}

我们再在浏览器中访问http://localhost:3000/api/products,可以得到更新后的输出如下:

  1. {"products":[{"name":"iPhone","price":6999},{"name":"Kindle","price":999},{"name":"XBox","price":3999}]}

可见,在koa中处理REST请求是非常简单的。bodyParser()这个middleware可以解析请求的JSON数据并绑定到ctx.request.body上,输出JSON时我们先指定ctx.response.type = 'application/json',然后把JavaScript对象赋值给ctx.response.body就完成了REST请求的处理。

参考源码

rest-hello

读后有收获可以支付宝请作者喝咖啡,读后有疑问请加微信群讨论:

编写REST API - 图1 编写REST API - 图2