共计 2637 个字符，预计需要花费 7 分钟才能阅读完成。
前言
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%，有哪些有兴趣的小伙伴欢迎一起维护。
