使用koa2+mongodb+ava構建RESTful api並測試

初涉nodejs後臺開發，在得知express和koa是同一個團隊開發之後果斷選擇了更前沿的koa2試水。結果發現koa生態是真的不成熟啊，不過開發起來也更有意思。

安裝依賴

此次我們使用koa-generator作爲腳手架創建項目，這個也不是官方腳手架，大家熟悉了可以隨便改。

npm install koa-generator -g
koa2 my-project
cd my-project

這樣就生成了一個基本的項目框架。
除此之外，必須要安裝的還有用來操作MongoDB的mongoose、用來進行單元測試的框架ava以及superkoa。

npm install --save mongoose
npm install --save-dev ava
npm install --save-dev superkoa

下面是我項目的package.json文件的依賴，其中mount-koa-routes是一個自動讀取routes文件的框架，可以不用。

"dependencies": {
    "debug": "^2.6.3",
    "koa": "^2.2.0",
    "koa-bodyparser": "^3.2.0",
    "koa-convert": "^1.2.0",
    "koa-json": "^2.0.2",
    "koa-logger": "^2.0.1",
    "koa-onerror": "^1.2.1",
    "koa-router": "^7.1.1",
    "koa-static": "^3.0.0",
    "koa-views": "^5.2.1",
    "mongoose": "^5.4.0",
    "mongoosedao": "^1.0.13",
    "mount-koa-routes": "^2.0.1",
    "pug": "^2.0.0-rc.1"
  },
  "devDependencies": {
    "ava": "^1.0.1",
    "nodemon": "^1.18.9",
    "superkoa": "^1.0.3",
  }

定義數據庫連接和Schema對象

此次我們要做的api是做一個能夠增刪改查分類的api。MongoDB是這幾年非常火爆的一個nosql數據庫。在嘗試過後確實趕緊nosql很爽。MongoDB的學習資料建議看這個：http://www.runoob.com/mongodb/mongodb-tutorial.html
搭建一個MongoDB數據庫要比Mysql和OracleDB快多了。
我們使用mongoose.js來處理MongoDB的相關操作。mongoose.js可以看作是nodejs上MongoDB的ORM框架，和java後端的hibernate以及android端的greenDAO類似。有過ORM框架經驗的上手非常容易。具體的mongoose學習看官網就非常好：https://mongoosejs.com/
首先我們在新建一個mongo-db.js來執行MongoDB的連接：

const mongoose = require('mongoose');

const connect = mongoose.connect('mongodb://www.zhangyesong.com:27017/test',
    {useNewUrlParser: true});
connect.then((() => {
    console.log('連接數據庫成功');
}), (error => {
    console.log('連接數據庫失敗' + error);
}));

是不是很簡單？然後在app.js引用就可以：

require('./config/mongo-db');

新建一個目錄用來存放所有的Scheme，在裏面新建一個文件category.js，如下：

const mongoose = require('mongoose');
const Schema = mongoose.Schema;

const CategorySchema = new Schema({
    _id: String,
    name: {type: String, required: true},
    parent: String,
    level: {type: Number, min: 0, max: 5},
});

const CategoryModel = mongoose.model('Category', CategorySchema);
module.exports = CategoryModel;

雖然MongoDB沒有表的概念只有Collection的概念，但是正常情況下我們肯定還是讓Collection裏的每條數據都有着相同的數據結構的。Schema就是定義Colletion裏面數據的結構的。
這裏我們給category定義了四個key。
_id是默認的數據的默認字段，全局唯一，默認類型是ObjectId，這裏我改成了String，由用戶自己來定義。
name記錄分類的名字。
parent記錄分類的上級分類。
level記錄分類的層級。
定義好Schema之後，創建model類然後export出去。

撰寫RESTful api

RESTful api設計風格越來越流行，接口不做成RESTful怎麼行呢？
我所掌握的RESTful api有以下兩個要點：

• url要使用表示資源的名字，比如我這裏就是category或categories，儘量不要使用動詞。
• 使用GET來做query請求，POST做創建請求，PATCH做修改請求，DELETE做刪除請求，反正就是把Http請求用對，不用什麼都用GET和POST一把幹完。

想詳細學習以下RESTful的同學可以看看阮一峯老師的這篇博客：http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html
這裏面爭議比較大的是query請求靈活多變，url上有時候強行用資源名稱反而會導致接口語義不清。因此我這裏只保證query以外的請求符合REST風格。

首先我們對所有的返回簡單封裝以下：

exports.createOKResponse = function(data) {
    return {
        error: 0,
        data: data,
    }
};

exports.createFailedResponse = function(error, message) {
    return {
        error: error,
        message: message,
    }
};

然後api接口代碼如下：

const response = require('../util/response-util');
const router = require("koa-router")();
const CategoryModel = require('../model/category');

router.post('/', async (ctx) => {
    let requestCategory = ctx.request.body;
    if (!checkCategory(requestCategory)) {
        ctx.body = response.createFailedResponse(400, 'bad request params');
        return;
    }

    let result = await CategoryModel.create(requestCategory);
    if (result) {
        ctx.body = response.createOKResponse(result);
    } else {
        ctx.body = response.createFailedResponse(500, 'create category failed');
    }
});

router.delete('/', async (ctx) => {
    let _id = ctx.query._id;
    if (!_id) {
        ctx.body = response.createFailedResponse(400, 'bad request params');
        return;
    }

    let result = await CategoryModel.findByIdAndDelete({_id});
    if (result) ctx.body = response.createOKResponse(result);
    else ctx.body = response.createFailedResponse(500, 'delete category fail')
});

router.patch('/', async (ctx) => {
    let requestCategory = ctx.request.body;
    let _id = requestCategory._id;
    if (!_id) {
        ctx.body = response.createFailedResponse(400, 'bad request params');
        return;
    }

    let category = await CategoryModel.findById(_id);
    if (!category) {
        ctx.body = response.createFailedResponse(404, 'can not find such category');
        return
    }

    if(requestCategory.name) category.name = requestCategory.name;
    if(requestCategory.parent) category.parent = requestCategory.parent;
    if(requestCategory.level) category.level = requestCategory.level;

    let result = await category.save();
    if (result) ctx.body = response.createOKResponse(result);
    else ctx.body = response.createFailedResponse(500, 'update category fail')
});

router.get('/list', async (ctx) => {
    let parent = ctx.query.parent;
    if (!parent) {
        ctx.body = response.createFailedResponse(400, 'bad request params');
    }

    let result = await CategoryModel.find({parent: parent}).select('_id name parent level').exec();
    if (result) {
        ctx.body = response.createOKResponse(result);
    } else {
        ctx.body = response.createFailedResponse(500, 'find categories failed');
    }
});

function checkCategory(category) {
    return !(category.level > 5 || category.level < 0 || !category.level || !category.name || !category._id);
}

module.exports = router;

可以看到mongoose處理數據庫的增刪改查請求都是異步，使用es7的await語句做異步是不是非常的爽？

單元測試

單元測試可以幫助發現很大比例的bug，ava是一新一代的nodejs測試框架，可以異步測試（雖然這次我需要的是同步- -）具體的使用說明可以看官方github主頁：https://github.com/avajs/ava
在寫測試代碼的時候尷尬了，我們請求接口是異步，執行測試用例也是異步，但是對category四個接口的測試我是想有順序地執行的（比如我得先創建一個測試分類然後才能修改、查詢、刪除，沒有順序的話沒辦法每次跑單元測試都通過）。棘手的是我好像並想不到同步執行單元測試的方法- -最後還是查詢官方文檔得知的，在test後面加上.serial即可。看來ava還是爲我們考慮到了這一點的。superkoa是基於supertest的做的一個可以讓我們在ava測試代碼裏調用koa的框架，使用起來非常的簡單。
新建一個test文件夾，添加一個test.js文件，全部的測試代碼如下：

import test from 'ava';
import superKoa from 'superkoa';
import app from '../app';

test('hello full-stacker', async t => {
    let res = await superKoa(app).get('/');
    t.is(200, res.status);
    t.is(res.text, 'Hello full stacker!')
});

test.serial('create category', async t => {
    let testCategory = {
        _id:'test',
        name:'測試分類',
        parent:'root',
        level:1
    };
    let res = await superKoa(app)
        .post('/category')
        .send(testCategory);
    t.is(200, res.status);
    t.is(0, res.body.error);
    t.is('測試分類', res.body.data.name);
});

test.serial('update category', async t => {
    let res = await superKoa(app)
        .patch('/category')
        .send({_id: 'test', name: '測試分類2'});
    t.is(200, res.status);
    t.is(0, res.body.error);
    t.is('測試分類2', res.body.data.name);
});

test.serial('query categories by parent', async t => {
    let res = await superKoa(app)
        .get('/category/list?parent=root');
    t.is(200, res.status);
    t.is(0, res.body.error);
    t.true(res.body.data.length > 0);
});

test.serial('delete category', async t => {
    let res = await superKoa(app)
        .delete('/category?_id=test');
    t.is(200, res.status);
    t.is(0, res.body.error);
});

然後把package.json下的script標籤下的test命令改爲"test": "ava -v"
現在我們來執行下單元測試：

▶ npm test

> [email protected] test /Users/judy/WeChatProjects/full-stacker/full-stacker-api
> ava -v

mount route /category.js 
mount route /index.js 

******************************************************
                MoaJS Apis Dump
******************************************************

┌─────────────────────────────────────────────────────────────────────────────┬────────┬────────────────┐
│ File                                                                        │ Method │ Path           │
├─────────────────────────────────────────────────────────────────────────────┼────────┼────────────────┤
│ /Users/judy/WeChatProjects/full-stacker/full-stacker-api/routes/category.js │ POST   │ /category/     │
├─────────────────────────────────────────────────────────────────────────────┼────────┼────────────────┤
│ /Users/judy/WeChatProjects/full-stacker/full-stacker-api/routes/category.js │ DELETE │ /category/     │
├─────────────────────────────────────────────────────────────────────────────┼────────┼────────────────┤
│ /Users/judy/WeChatProjects/full-stacker/full-stacker-api/routes/category.js │ PATCH  │ /category/     │
├─────────────────────────────────────────────────────────────────────────────┼────────┼────────────────┤
│ /Users/judy/WeChatProjects/full-stacker/full-stacker-api/routes/category.js │ GET    │ /category/list │
├─────────────────────────────────────────────────────────────────────────────┼────────┼────────────────┤
│ /Users/judy/WeChatProjects/full-stacker/full-stacker-api/routes/index.js    │ GET    │                │
└─────────────────────────────────────────────────────────────────────────────┴────────┴────────────────┘
  <-- POST /category
連接數據庫成功
POST /category - 4358ms
  --> POST /category 200 4,364ms 89b
  ✔ create category (4.4s)
  <-- PATCH /category
PATCH /category - 87ms
  --> PATCH /category 200 89ms 90b
  ✔ update category
  <-- GET /category/list?parent=root
GET /category/list?parent=root - 26ms
  --> GET /category/list?parent=root 200 34ms 270b
  ✔ query categories by parent
  <-- DELETE /category?_id=test
DELETE /category?_id=test - 27ms
  --> DELETE /category?_id=test 200 28ms 90b
  ✔ delete category
  <-- GET /
GET / - 1ms
  --> GET / 200 3ms 19b
  ✔ hello full-stacker

  5 tests passed

看着單元測試全部通過有着莫名的快感，不知道大家是否也一樣呢～
最貼一下代碼地址，目前這個項目剛剛開始，也是我的nodejs試水項目。新司機上路，有問題請大家斧正。
https://github.com/ZhangYeSong/full-stacker