讓我們來重新設計一下 koa-router

前言

koa-router 是目前用的比較多的 Koa 的路由中間件之一，前段時間由於作者沒有精力繼續維護而將其公開售賣。我們有些項目也用到了這個庫，但是目前很多我們想要的特性都沒有，比如生成接口文檔。本身這個庫代碼實現還比較簡單，因此綜合考慮打算重寫一個。

項目地址：https://github.com/d-band/koa...

特性：

• 支持幾乎所有的 koa-router 特性
• 支持 params 校驗
• params 支持從 path, header, query, cookie 中獲取
• 支持 body parser
• 支持 request body 校驗
• 支持參數類型自動轉換
• 支持自動生成 OpenAPI

簡單例子：

index.js

import Koa from 'koa';
import Mapper from 'koa-mapper';
import * as service from './service';

const Mapper = new Mapper();

mapper.get('/users/:id/projects', {
  params: {
    id: { type: 'number' },
    status: { type: 'array<string>', in: 'query' },
    token: { type: 'string', in: 'header' }
  }
}, service.getProjects);

mapper.post('/users/:id/projects', {
  params: {
    id: { type: 'number' }
  },
  body: 'Project'
}, service.addProject);

mapper.schema('Project', {
  id: { type: 'number', required: true },
  name: { type: 'string', required: true },
  status: { type: 'array<Status>', required: true }
});

mapper.schema('Status', {
  id: { type: 'integer' },
  name: { type: 'string' }
}, {
  required: ['id', 'name']
});

app.use(mapper.routes());
app.use(mapper.allowedMethods());

app.listen(3000);

// open http://localhost:3000/openapi.json

service.js

export async function getProjects(ctx) {
  const { id, status, token } = ctx.params;

  await checkToken(id, token);

  ctx.body = await Project.findAll({
    where: {
      userId: id,
      status: { $in: status }
    }
  });
}

export async function addProject(ctx) {
  const { body } = ctx.request;

  ctx.body = await Project.create({
    ...body,
    userId: id
  });
}

路由定義：

mapper.get(path, [options], ...middlewares);
mapper.post(path, [options], ...middlewares);
mapper.put(path, [options], ...middlewares);
mapper.del(path, [options], ...middlewares);
...

options 爲可選參數，包含:

• name: 路由名稱
• params: 請求參數定義
• body: 請求 Body 定義
• 其他 OpenAPI 中 Operation Object 的參數

options.params 爲請求參數定義，如：

params = {
  id: { type: 'number' },
  name: { type: 'string', in: 'query' },
  user: { type: 'User', in: 'query' }
}

• type: 參數類型，包含基本類型（number、string、integer、date、time、datetime），數組類型（array<string>），自定義類型（如 User），自定義數組類型（array<User>），多個類型（number|string）
• in: 參數來源，包含 path，header，query，cookie
• 其他 OpenAPI 中 Parameter Object 的參數

自定義類型

mapper.define(schemaName, properties, options);
// or
mapper.schema(schemaName, properties, options);

支持類型組合，如：

mapper.schema('Status', {
  id: { type: 'integer' },
  name: { type: 'string' }
}, {
  required: ['id']
});
mapper.schema('Project', {
  id: { type: 'number', required: true },
  name: { type: 'string', required: true },
  status: { type: 'array<Status>', required: true }
});

支持繼承，如：

mapper.schema('Model', {
  id: { type: 'number' },
  createdAt: { type: 'datetime' },
  updatedAt: { type: 'datetime' }
});
mapper.schema('User: Model', {
  name: { type: 'string' }
});

Body Parser

mapper.post('/users', {
  body: 'User'
}, (ctx) => {
  const { id, name } = ctx.request.body;
});

支持文件上傳，如：

mapper.post('/uploadImage', {
  bodyparser: { multipart: true },
  body: {
    user: { type: 'number' },
    image: { type: 'file' }
  }
}, (ctx) => {
  const { user, image } = ctx.request.body;
});

結尾

目前 koa-mapper 剛發佈，測試覆蓋率達到 100%，有哪些有興趣的小夥伴歡迎一起維護。