抄得走, 用得到的 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