抄得走- 用得到的 Koa 實踐總結

陸陽陽，微醫前端技術部前端開發工程師，做一條安靜的鹹魚。

爲什麼選擇 Koa

小王：爲什麼選擇Koa?
老王：因爲 Koa 比較輕量，幾乎沒有內置任何的額外功能。也是因爲這個原因，Koa 的靈活度是很高的，喜歡折騰的人可以嘗試下
小王：又輕量又幾乎沒有任何額外功能？那爲什麼不用原生Node？那個不是更輕？
老王：這個。。。。 我還是先說說怎麼用吧

有點長，心急的可以查看完整代碼  https://github.com/JustGreenHand/koa-app

搭建項目並啓動服務

經過一系列基操之後，生成如下所示的目錄結構：

接下來我們在啓動文件 app/index.js 文件中寫入最簡單的啓動服務代碼:

const Koa = require('koa');

const app = new Koa();

const port = '8082'
const host = '0.0.0.0'

app.use(async ctx => {
  ctx.body = 'Hello World';
});

app.listen(port, host, () => {
  console.log(`API server listening on ${host}:${port}`);
});

我們運行一下 node app/index.js 命令，這個時候，最簡單的 node 服務已經啓動起來了。瀏覽器裏訪問 http://localhost:8082 已經可以正常響應了

公衆號

改造路由

當項目功能慢慢多起來的時候，路由處理也相應的多了起來，app/index.js 代碼就成了下面這樣：

const Koa = require('koa');

const app = new Koa();

const port = '8082'
const host = '0.0.0.0'

app.use(async ctx => {
  const { path } = ctx
  if (path === '/a') {
    // 功能 A
    ctx.body = 'a';
  } else if (path === '/b') {
    // 功能 B
    ctx.body = 'b';
  } else if (path === '/c') {
    // 功能 C
    ctx.body = 'c';
  } else {
    ctx.body = 'hello world'
  }
});

app.listen(port, host, () => {
  console.log(`API server listening on ${host}:${port}`);
});

這種將所有路由和路由處理函數寫在一起的方式，後期會難以維護，代碼量長了容易找不到重點。所以我們將路由處理的部分從啓動文件 app/index.js 裏摘出來，單獨維護一個路由文件，並用第三方路由管理插件koa-router 來管理路由。我們在 app 目錄下新建 router 目錄，如下所示:

首先我們安裝下路由處理插件 (koa-ruoter 文檔): npm install koa-router -s, 再在 app/router/index.js 文件中編寫路由處理部分的代碼

const koaRouter = require('koa-router');
const router = new koaRouter();

router.get('/a', ctx => {
  ctx.body = 'a'
});

router.get('/b', ctx => {
  ctx.body = 'b'
});

router.get('/c', ctx => {
  ctx.body = 'c'
});

module.exports = router;

修改 app/index.js 的代碼，路由處理從 app/router/index.js 文件引入:

const Koa = require('koa');

const router = require('./router')

const app = new Koa();

const port = '8082'
const host = '0.0.0.0'

app.use(router.routes());
/*
    原先當路由存在，請求方式不匹配的時候，會報 404，
    加了這個中間件，會報請求方式不被允許
*/
app.use(router.allowedMethods());


app.listen(port, host, () => {
  console.log(`API server listening on ${host}:${port}`);
});

嘗試訪問 http://localhost:8082/a 返回結果與改造前一致。到這裏爲止，各個文件看起來是各司其職，功能拆分比較明確的。但是當接口越來越多的時候，我們的路由處理文件還是會越來越龐大，我們的目標是路由處理文件只關心路由的處理，具體業務邏輯不關心。所以這裏再次將路由處理文件進行任務拆分。

如上圖，這個階段我們新增了三個文件

• app/router/routes.js       路由列表文件

• app/contronllers/index.js  業務處理統一導出

• app/contronllers/test.js   業務處理文件

將各業務邏輯的代碼放在 controllers 下，示例文件 app/contronllers/test.js:

const list = async ctx => {
  ctx.body = '路由改造後的結果'
}

module.exports = {
  list
}

將這部分業務處理代碼導入到 app/contronllers/index.js:

const test = require('./test');

module.exports = {
  test
};

這樣的好處是所有業務處理統一一個入口，利於維護。接下來編寫文件 app/router/routes.js:

const { test } = require('../controllers');

const routes = [
  {
    //  測試
    method: 'get',
    path: '/a',
    controller: test.list
  }
];

module.exports = routes;

這個時候，原本的 app/router/index.js 文件也需要做相應的修改了:

/* const Router = require('koa-router');
const router = new Router();

router.get('/a', ctx => {
  ctx.body = 'a'
});

router.get('/b', ctx => {
  ctx.body = 'b'
});

router.get('/c', ctx => {
  ctx.body = 'c'
});

module.exports = router; */


const koaRouter = require('koa-router');
const router = new koaRouter();

const routeList = require('./routes');

routeList.forEach(item => {
  const { method, path, controller } = item;
  //  router 第一個參數是 path， 後面跟上路由級中間件 controller（上面編寫的路由處理函數）
  router[method](path, controller);
});

module.exports = router;

經過上面的改造後，再次訪問下 http://localhost:8082/a，返回結果:

看起來沒啥問題，到這裏爲止路由改造已經完成，而且順便把啓動文件，路由文件，路由處理文件三部分拆開了

參數解析

一番實際操作後，發現 post 請求時，拿不到 body 裏的參數。如下截圖:
期望的返回值爲 {"a": 4}, 實際爲:

翻閱資料後這裏需要加上一個參數解析的中間件。考慮到後面可能會添加更多的中間件，在具體處理參數之前，先將當前的代碼再次進行改造下，將中間件處理單獨從啓動文件 app/index.js 裏摘出來，新建一個  app/middlewares 目錄，在該目錄中我們添加 index.js 文件:

const router = require('../router');

/**
 * 路由處理
 */
const mdRoute = router.routes();
const mdRouterAllowed = router.allowedMethods();

module.exports = [
  mdRoute,
  mdRouterAllowed
];

上面文件裏集中了所有用到的中間件，目前爲止是兩個路由處理的中間件，接下來改造下啓動文件 app/index.js:

const Koa = require('koa');

const compose = require('koa-compose');
const MD = require('./middlewares/');

const app = new Koa();

const port = '8082'
const host = '0.0.0.0'

app.use(compose(MD));

app.listen(port, host, () => {
  console.log(`API server listening on ${host}:${port}`);
});

這裏引入了一個插件 koa-compose，作用是簡化引用中間件的寫法。到這裏準備工作已經做好了，開始處理參數解析的問題

安裝第三方參數解析插件 koa-bodyparser 來幫我們處理 post 請求體中的參數。修改 app/middlewares/index.js 文件:

const koaBody = require('koa-bodyparser');

const router = require('../router');

/**
 * 參數解析
 * https://github.com/koajs/bodyparser
 */
const mdKoaBody = koaBody({
  enableTypes: [ 'json', 'form', 'text', 'xml' ],
  formLimit: '56kb',
  jsonLimit: '1mb',
  textLimit: '1mb',
  xmlLimit: '1mb',
  strict: true
});

/**
 * 路由處理
 */
const mdRoute = router.routes();
const mdRouterAllowed = router.allowedMethods();

module.exports = [
  mdKoaBody,
  mdRoute,
  mdRouterAllowed
];

因爲我們已經改造過啓動文件了，所以不需要在啓動文件裏再添加 app.use() 了。這裏再次嘗試用 post 請求:

發現已經是我們的預期結果了。不過這裏還是有個坑:

const mdKoaBody = koaBody({
  enableTypes: [ 'json', 'form', 'text', 'xml' ],
  formLimit: '56kb',
  jsonLimit: '1mb',
  textLimit: '1mb',
  xmlLimit: '1mb',
  strict: true
});

從這段代碼可以稍微看出，koa-bodyparser 這個插件只能解析 4 種數據[ 'json', 'form', 'text', 'xml' ]，當我們上傳文件的時候，我們是獲取不到文件的。秉持自己不會造可以白嫖絕不自己造輪子的原則，我們又在網上找到了解決方法，引入新的插件 formidable，由於這部分代碼稍微有點多，所以我們在 app/middlewares 目錄下再單獨新建一個 formidable.js 文件，代碼如下:

const Formidable = require('formidable');

const { tempFilePath } = require('../config');

module.exports = () => {
  return async function (ctx, next) {
    const form = new Formidable({
      multiples: true, 
      //  上傳的臨時文件保存路徑
      uploadDir: `${process.cwd()}/${tempFilePath}`
    });

    // eslint-disable-next-line promise/param-names
    await new Promise((reslove, reject) => {
      form.parse(ctx.req, (err, fields, files) => {
        if (err) {
          reject(err);
        } else {
          ctx.request.body = fields;
          ctx.request.files = files;
          reslove();
        }
      });
    });

    await next();
  };
};

formidable 具體用法就不解釋了，有興趣的可以 查看文檔，這裏，我們將寫好的中間件在 app/middlewares/index.js 中使用:

/**
 * 引入第三方插件
 */
const koaBody = require('koa-bodyparser');

/**
 * 引入自定義文件
 */
const router = require('../router');
const formidable = require('./formidable');

/**
 * 參數解析
 * https://github.com/koajs/bodyparser
 */
const mdFormidable = formidable();
const mdKoaBody = koaBody({
  enableTypes: [ 'json', 'form', 'text', 'xml' ],
  formLimit: '56kb',
  jsonLimit: '1mb',
  textLimit: '1mb',
  xmlLimit: '1mb',
  strict: true
});

/**
 * 路由處理
 */
const mdRoute = router.routes();
const mdRouterAllowed = router.allowedMethods();

module.exports = [
  mdFormidable,
  mdKoaBody,
  mdRoute,
  mdRouterAllowed
];

寫到這裏應該是可以了，我們來測試下：

從結果看出，我們的期望結果已經拿到了。到這裏，參數解析算是處理好了

補充下 formidable.js 文件中使用的  const { tempFilePath } = require('../config')。這裏我們新加了個配置目錄 app/config，主要用來存在各種配置，目錄下有 5 個文件，分別是:

• app/config/index.js

• app/config/base.js

• app/config/dev.js

• ...除了index.js 文件，其他文件可以根據項目的實際情況來創建

這裏主要看下 app/config/index.js 文件:

const base = require('./base');
const dev = require('./dev');
const pre = require('./pre');
const pro = require('./pro');

const env = process.env.NODE_ENV || 'dev';

const configMap = {
  dev,
  pre,
  pro
}


module.exports = Object.assign(base, configMap[env]);

統一返回格式 & 錯誤處理

在實現錯誤處理和統一返回格式之前，我們再做一點小小的改造。前面我們創建了 config 目錄，裏面存了一些常量配置，接下來我們還會創建一個 common/utils.js 用來存放工具函數，如果每個引用到的地方都 require 來引入是比較麻煩的，所以我們把工具函數和常量配置放到 app.context 的屬性上，之後就不用頻繁引入了，可以通過 ctx.來訪問，改造 app/index.js 如下:

const Koa = require('koa');
const compose = require('koa-compose');

const MD = require('./middlewares/');
const config = require('./config')
const utils = require('./common/utils')

const app = new Koa();

const port = '8082'
const host = '0.0.0.0'

app.context.config = config;
app.context.utils = utils;

app.use(compose(MD));

app.listen(port, host, () => {
  console.log(`API server listening on ${host}:${port}`);
});

接下來開始正題，先來搞定統一返回格式的問題。這個第一反應就是寫個工具函數，不要太簡單:

const successRes = (data, msg) => {
    return {
        code: 0,
        data,
        msg: msg || 'success',
    }
}
const failRes = (code = 1, data, msg) => {
    return {
        code,
        data,
        msg: msg || 'fail',
    }
}

ctx.body = ctx.utils.successRes('aaa')
//  或
ctx.body = ctx.utils.failRes(10001)

這麼寫也沒有問題，但是其實可以更加純粹點，充分利用 koa 洋蔥模型的優勢，讓 ctx.body 更加簡潔，返回的就是正確的結果，如: ctx.body = data，想到這裏，那還是添加中間件了。這裏需要加兩個，一個錯誤處理，一個統一返回格式，這兩個是相關聯的，所以在一起寫了

文件 app/middlewares/response.js

const response = () => {
  return async (ctx, next) => {
    ctx.res.fail = ({ code, data, msg }) => {
      ctx.body = {
        code,
        data,
        msg,
      };
    };

    ctx.res.success = msg => {
      ctx.body = {
        code: 0,
        data: ctx.body,
        msg: msg || 'success',
      };
    };

    await next();
  };
};

module.exports = response;

文件 app/middlewares/error.js

const error = () => {
  return async (ctx, next) => {
    try {
      await next();
      if (ctx.status === 200) {
        ctx.res.success();
      }
    } catch (err) {
      if (err.code) {
        // 自己主動拋出的錯誤
        ctx.res.fail({ code: err.code, msg: err.message });
      } else {
        // 程序運行時的錯誤
        ctx.app.emit('error', err, ctx);
      }
    }
  };
};

module.exports = error;

在 app/middlewares/index.js 文件中引入上面的兩個中間件:

/**
 * 引入第三方插件
 */
const koaBody = require('koa-bodyparser');

/**
 * 引入自定義文件
 */
const router = require('../router');
const formidable = require('./formidable');
const response = require('./response');
const error = require('./error');

/**
 * 參數解析
 * https://github.com/koajs/bodyparser
 */
const mdFormidable = formidable();
const mdKoaBody = koaBody({
  enableTypes: [ 'json', 'form', 'text', 'xml' ],
  formLimit: '56kb',
  jsonLimit: '1mb',
  textLimit: '1mb',
  xmlLimit: '1mb',
  strict: true
});

/**
 * 統一返回格式
 */
const mdResHandler = response();
/**
 * 錯誤處理
 */
const mdErrorHandler = error();

/**
 * 路由處理
 */
const mdRoute = router.routes();
const mdRouterAllowed = router.allowedMethods();

module.exports = [
  mdFormidable,
  mdKoaBody,
  mdResHandler,
  mdErrorHandler,
  mdRoute,
  mdRouterAllowed
];

從這裏看出，我們所有的返回值是在 app/middlewares/error.js 裏攔截了一下，如果狀態碼是 200，用成功的工具函數包裝返回，如果不是則又分爲兩種情況：一種是我們自己拋出的，包含業務錯誤碼的情況 (這種情況我們用失敗的工具函數包裝返回)；另一種是程序運行時報的錯，這個往往是我們代碼寫的有問題 (這種情況我們觸發 koa 的錯誤處理事件去處理)，針對失敗的第二種情況，我們還需要修改啓動文件 app/index.js，添加如下代碼:

app.on('error', (err, ctx) => {
  if (ctx) {
    ctx.body = {
      code: 9999,
      message: `程序運行時報錯：${err.message}`
    };
  }
});

完成上面的操作之後我們再來測試下我們的代碼: 當 app/controllers/test.js 中代碼如下時:

const list = async ctx => {
  ctx.body = '返回結果'
}

請求接口，返回值如下:

符合我們的預期

接下來我們修改 app/controllers/test.js， 業務中拋出業務錯誤碼

const list = async ctx => {
  const data = ''
  ctx.utils.assert(data, ctx.utils.throwError(10001, '驗證碼失效'))
  ctx.body = '返回結果'
}

再次返送請求，結果如下:

符合預期

再次修改 app/controllers/test.js 故意寫錯代碼

const list = async ctx => {
  const b = a;
  ctx.body = '返回結果'
}

再次發送請求看下結果:

符合預期

到這爲止，錯誤處理搞定了，統一返回格式也搞定了，可以搞其他的了

跨域設置

這個應該是最簡單的了，直接使用插件 @koa/cors (查看文檔)，因爲這個代碼量比較少，所以直接在文件 app/middlewares/index.js 裏添加內容:

const cors = require('@koa/cors');

/**
 * 跨域處理
 */
const mdCors = cors({
  origin: '*',
  credentials: true,
  allowMethods: [ 'GET', 'HEAD', 'PUT', 'POST', 'DELETE', 'PATCH' ]
});

module.exports = [
  mdFormidable,
  mdKoaBody,
  mdCors,
  mdResHandler,
  mdErrorHandler,
  mdRoute,
  mdRouterAllowed
];

大功告成

添加日誌

這裏採用 log4js 查看文檔 來記錄請求日誌，添加文件 app/middlewares/log.js :

const log4js = require('log4js');
const { outDir, flag, level } = require('../config').logConfig;

log4js.configure({
  appenders: { cheese: { type: 'file', filename: `${outDir}/receive.log` } },
  categories: { default: { appenders: [ 'cheese' ], level: 'info' } },
  pm2: true
});

const logger = log4js.getLogger();
logger.level = level;

module.exports = () => {
  return async (ctx, next) => {
    const { method, path, origin, query, body, headers, ip } = ctx.request;
    const data = {
      method,
      path,
      origin,
      query,
      body,
      ip,
      headers
    };
    await next();
    if (flag) {
      const { status, params } = ctx;
      data.status = status;
      data.params = params;
      data.result = ctx.body || 'no content';
      if (ctx.body.code !== 0) {
        logger.error(JSON.stringify(data));
      } else {
        logger.info(JSON.stringify(data));
      }
    }
  };
};

在 app/middlewares/index.js 中引入上面寫的日誌中間件:

const log = require('./log');

/**
 * 記錄請求日誌
 */
const mdLogger = log();

module.exports = [
  mdFormidable,
  mdKoaBody,
  mdCors,
  mdLogger,
  mdResHandler,
  mdErrorHandler,
  mdRoute,
  mdRouterAllowed
];

我們看下請求效果:

[2021-03-31T21:44:40.919] [INFO] default - {"method":"GET","path":"/a","origin":"http://localhost:8082","query":{"name":"張三","age":"12"},"body":{},"ip":"127.0.0.1","headers":{"user-agent":"PostmanRuntime/7.26.8","accept":"*/*","cache-control":"no-cache","postman-token":"d8be0c95-10f6-438c-aa37-1006be317081","host":"localhost:8082","accept-encoding":"gzip, deflate, br","connection":"keep-alive"},"status":200,"params":{},"result":{"code":0,"data":"返回結果","msg":"success"}}
[2021-03-31T21:54:55.595] [ERROR] default - {"method":"GET","path":"/a","origin":"http://localhost:8082","query":{"name":"張三","age":"12"},"body":{},"ip":"127.0.0.1","headers":{"user-agent":"PostmanRuntime/7.26.8","accept":"*/*","cache-control":"no-cache","postman-token":"86b581e4-07cf-4b04-9b01-5e56c19f696f","host":"localhost:8082","accept-encoding":"gzip, deflate, br","connection":"keep-alive"},"status":200,"params":{},"result":{"code":9999,"message":"程序運行時報錯：b is not defined"}}

到這裏日誌模塊也好了。

參數校驗

前面忘記了對參數做校驗，不管是業務邏輯上的需要，還是爲了避免程序運行時的錯誤，參數校驗是非常有必要的。還是那句話，我們可以把參數校驗放在對應的 controller 裏去做，類似這樣:

const list = async ctx => {
  const { name, age } = ctx.request.query
  if (!name) ctx.utils.assert(false, ctx.utils.throwError(10001, 'name 是必須的'))
  if (!age) ctx.utils.assert(false, ctx.utils.throwError(10001, 'age 是必須的'))
  ctx.body = name + age
}

但是當參數較多時，controller 會顯得非常龐大，而且我們一眼看不到這個函數的重點，而且我要寫很多重複的沒用的代碼，類似 ctx.utils.assert(false, ctx.utils.throwError(10001, 'name 是必須的')) ，我希望我在 controller 層一上來就能寫一些業務代碼，最合理的還是將參數校驗放在中間件中去統一處理，這裏我們採用第三方插件 @hapi/joi 來處理，在 app/middlewares/ 下添加 paramValidator.js 文件：

module.exports = paramSchema => {
  return async function (ctx, next) {
    let body = ctx.request.body;
    try {
      if (typeof body === 'string' && body.length) body = JSON.parse(body);
    } catch (error) {}
    const paramMap = {
      router: ctx.request.params,
      query: ctx.request.query,
      body
    };

    if (!paramSchema) return next();

    const schemaKeys = Object.getOwnPropertyNames(paramSchema);
    if (!schemaKeys.length) return next();

    // eslint-disable-next-line array-callback-return
    schemaKeys.some(item => {
      const validObj = paramMap[item];

      const validResult = paramSchema[item].validate(validObj, {
        allowUnknown: true
      });

      if (validResult.error) {
        ctx.utils.assert(false, ctx.utils.throwError(9998, validResult.error.message));
      }
    });
    await next();
  };
};

這次這個參數校驗中間件我們不在 app/middlewares/index.js 中使用， 我們改造下 app/router/index.js:

// const koaRouter = require('koa-router');
// const router = new koaRouter();

// const routeList = require('./routes');


// routeList.forEach(item => {
//   const { method, path, controller } = item;
//   router[method](path, controller);
// });

// module.exports = router;

const koaRouter = require('koa-router');
const router = new koaRouter();

const routeList = require('./routes');
const paramValidator = require('../middlewares/paramValidator');

routeList.forEach(item => {
  const { method, path, controller, valid } = item;
  router[method](path, paramValidator(valid), controller);
});

module.exports = router;

koa-router 是可以添加多個路由級中間件的，我們將參數校驗放在這裏處理。然後我們添加新的目錄 schema，用來存放參數校驗部分的代碼，添加兩個文件:

• app/schema/index.js

const scmTest = require('./test');

module.exports = {
  scmTest
};

• app/schema/test.js

const Joi = require('@hapi/joi');

const list = {
  query: Joi.object({
    name: Joi.string().required(),
    age: Joi.number().required()
  })
};

module.exports = {
  list
};

我們可以看到在 app/router/index.js 中一段代碼:

  const { method, path, controller, valid } = item;
  router[method](path, paramValidator(valid), controller);

這裏需要一個valid屬性來校驗參數，所以我們接着改造 app/router/routes.js 文件如下:

const { test } = require('../controllers');
const { scmTest } = require('../schema/index')

const routes = [
  {
    //  測試
    method: 'get',
    path: '/a',
    valid: scmTest.list,
    controller: test.list
  }
];

module.exports = routes;

現在我們修改 controller 中的代碼，將我們自己手動寫的參數校驗去掉，改成:

const list = async ctx => {
  const { name, age } = ctx.request.query
  ctx.body = name + age
}

這裏我們沒有對參數進行校驗了，我們嘗試發送請求看看結果:

在請求參數中，我們把 age 這個參數去掉了，可以看到返回結果是我們預期的，到這爲止參數校驗也搞定了，@hapi/joi 更多的使用方法請 查看文檔

數據庫操作

當涉及到數據庫操作時，我們可以在 app 下再新增一個 service 目錄。將數據庫操作從 controller 目錄下分離出來放在 service 目錄下，兩個目錄各司其職，一個專注業務處理，一個專注數據庫層面的增刪改查。另外再添加一個 model 目錄，用來定義數據庫表結構，具體的這裏暫時不介紹了。

目前爲止目錄結構

總結

其他更多的公共邏輯都可以放在中間件層面去做，例如登錄校驗、權限校驗等。到目前爲止上面細節上還有很多問題沒來得及做處理，比如統一返回格式的那個中間件，如果返回的是個文件其實會有問題，後期還會對很多細節進行優化。

上面是我個人總結的實踐，有不合理的地方或建議大家幫忙指出來，共同學習交流進步

參考資料

• 完整代碼:

  https://github.com/JustGreenHand/koa-app

本文由 Readfog 進行 AMP 轉碼，版權歸原作者所有。
來源：https://mp.weixin.qq.com/s/siGxYq7TvcD3g580BZJkRw