egg-typebox-validate
基于 typebox 和 ajv 封装的 egg validate 插件。
为什么有这个项目
一直以来,在 typescript 的 egg 项目里,对参数校验 ctx.validate 是比较难受的,比如:
class HomeController extends Controller {
async index() {
const { ctx } = this;
// 写一遍 js 的类型校验
ctx.validate({
id: 'string',
name: {
type: 'string',
required: false,
},
timestamp: {
type: 'number',
required: false,
},
}, ctx.params);
// 写一遍 ts 的类型定义,为了后面拿参数定义
const params: {
id: string;
name?: string;
timestamp: number;
} = ctx.params;
...
ctx.body = params.id;
}
}
export default HomeController;
可以看到这里我们写了两遍的类型定义,一遍 js 的定义(用 parameter 库的规则),另一遍用 ts 的方式来强转我们的参数类型,方便我们后面写代码的时候能得到 ts 的类型效果。 对于简单的类型写起来还好,但是对于复杂点的参数定义,开发体验就不是那么好了。
这就是这个库想要解决的问题,对于参数校验,写一遍类型就够了:
+ import { Static, Type } from 'egg-typebox-validate/typebox';
class HomeController extends Controller {
async index() {
const { ctx } = this;
// 写 js 类型定义
- ctx.validate({
- id: 'string',
- name: {
- type: 'string',
- required: false,
- },
- timestamp: {
- type: 'number',
- required: false,
- },
- }, ctx.params);
+ const paramsSchema = Type.Object({
+ id: Type.String(),
+ name: Type.Optional(Type.String()),
+ timestamp: Type.Optional(Type.Integer()),
+ });
// 直接校验
+ ctx.tValidate(paramsSchema, ctx.params);
// 不用写 js 类型定义
+ const params: Static<typeof paramsSchema> = ctx.params;
- const params: {
- id: string;
- name?: string;
- timestamp: number;
- } = ctx.params;
...
ctx.body = params.id;
}
}
export default HomeController;
用 Static<typeof typebox>
推导出的 ts 类型:
怎么使用
- 安装
npm i egg-typebox-validate -S
- 在项目中配置
// config/plugin.ts
const plugin: EggPlugin = {
typeboxValidate: {
enable: true,
package: 'egg-typebox-validate',
},
};
- 在业务代码中使用
+ import { Static, Type } from 'egg-typebox-validate/typebox';
// 写在 controller 外面,静态化,性能更好,下面有 benchmark
+ const paramsSchema = Type.Object({
+ id: Type.String(),
+ name: Type.String(),
+ timestamp: Type.Integer(),
+ });
// 可以直接 export 出去,给下游 service 使用
+ export type ParamsType = Static<typeof paramsSchema>;
class HomeController extends Controller {
async index() {
const { ctx } = this;
// 直接校验
+ ctx.tValidate(paramsSchema, ctx.params);
// 不用写 js 类型定义
+ const params: ParamsType = ctx.params;
...
}
}
export default HomeController;
除了类型定义 write once 外,还有更多好处
- 类型组合方式特别香,能解决很多 DRY(Don't Repeat Yourself) 问题。比如有几张 db 表,都定义了 name 必填和 description 选填,那这个规则可以在各个实体类方法中被组合了。
Show me the code!
export const TYPEBOX_NAME_DESC_OBJECT = Type.Object({
name: Type.String(),
description: Type.Optional(Type.String()),
});
// type NameAndDesc = { name: string; description?: string }
type NameAndDesc = Static<typeof TYPEBOX_NAME_DESC_OBJECT>;
// controller User
async create() {
const { ctx } = this;
const USER_TYPEBOX = Type.Intersect([
TYPEBOX_NAME_DESC_OBJECT,
Type.Object({ avatar: Type.String() }),
])
ctx.tValidate(USER_TYPEBOX, ctx.request.body);
// 在编辑器都能正确得到提示
// type User = { name: string; description?: string } & { avatar: string }
const { name, description, avatar } = ctx.request.body as Static<typeof USER_TYPEBOX>;
...
}
// controller Photo
async create() {
const { ctx } = this;
const PHOTO_TYPEBOX = Type.Intersect([
TYPEBOX_NAME_DESC_OBJECT,
Type.Object({ location: Type.String() }),
])
ctx.tValidate(PHOTO_TYPEBOX, ctx.request.body);
// 在编辑器都能正确得到提示
// type Photo = { name: string; description?: string } & { location: string }
const { name, description, location } = ctx.request.body as Static<typeof PHOTO_TYPEBOX>;
...
}
- 校验规则使用的是业界标准的 json-schema 规范,内置很多开箱即用的类型。
'date-time',
'time',
'date',
'email',
'hostname',
'ipv4',
'ipv6',
'uri',
'uri-reference',
'uuid',
'uri-template',
'json-pointer',
'relative-json-pointer',
'regex'
- 写定义的时候写的是 js 对象(
Type.Number()
),有类型提示,语法也比较简单,有提示不容易写错;写 parameter 规范的时候,写字符串('nunber'
)有时候会不小心写错😂 ,再加上它对于复杂嵌套对象的写法还是比较困难的,我每次都会查文档,官方的文档也不全。但是 typebox,就很容易举一反三了。
与 egg-validate 性能比较
egg-typebox-validate 底层使用的是 ajv, 官网上宣称是 The fastest JSON validator for Node.js and browser.
结论是在静态化的场景下,ajv 的性能要比 parameter 好得多,快不是一个数量级,详见benchmark
suite
.add('#ajv', function() {
const rule = Type.Object({
name: Type.String(),
description: Type.Optional(Type.String()),
location: Type.Enum({shanghai: 'shanghai', hangzhou: 'hangzhou'}),
})
ajv.validate(rule, DATA);
})
.add('#ajv define once', function() {
ajv.validate(typeboxRule, DATA);
})
.add('#parameter', function() {
const rule = {
name: 'string',
description: {
type: 'string',
required: false,
},
location: ['shanghai', 'hangzhou'],
}
p.validate(rule, DATA);
})
.add('#parameter define once', function() {
p.validate(parameterRule, DATA);
})
在 MacBook Pro(2.2 GHz 六核Intel Core i7)上,跑出来结果是:
#ajv x 941 ops/sec ±3.97% (73 runs sampled)
#ajv define once x 17,188,370 ops/sec ±11.53% (73 runs sampled)
#parameter x 2,544,118 ops/sec ±4.68% (79 runs sampled)
#parameter define once x 2,541,590 ops/sec ±5.34% (77 runs sampled)
Fastest is #ajv define once
从 egg-validate 迁移到这个库的成本
- 把原来字符串式 js 对象写法迁移到 typebox 的对象写法。typebox 的写法还算简单和容易举一反三
- 把
ctx.validate
替换成ctx.tValidate
- 建议渐进式迁移,先迁简单的,对业务影响不大的
总结
切换到 egg-typebox-validate 校验后:
- 可以解决 ts 项目中参数校验代码写两遍类型的问题,提升代码重用率,可维护性等问题
- 用标准 json-schema 来做参数校验,是更加标准的业界做法,内置更多业界标准模型
API
-
ctx.tValidate
参数校验失败后,抛出错误,内部实现(错误码、错误标题等)逻辑和ctx.validate
的保持一致
+ import { Static, Type } from 'egg-typebox-validate/typebox';
ctx.tValidate(Type.Object({
name: Type.String(),
}), ctx.request.body);
-
ctx.tValidateWithoutThrow
直接校验,不抛出错误
+ import { Static, Type } from 'egg-typebox-validate/typebox';
const valid = ctx.tValidateWithoutThrow(Type.Object({
name: Type.String(),
}), ctx.request.body);
if (valid) {
...
} else {
const errors = this.app.ajv.errors
// handle errors
...
}
-
⭐ ⭐ ⭐ 装饰器 decorator@Validate([ [rule1, ctx => ctx.xx1], [rule2, ctx => ctx.xx2] ])
调用(写法更干净,推荐使用!️)
+ import { Validate, ValidateFactory } from 'egg-typebox-validate/decorator';
const ValidateWithRedirect = ValidateFactory(ctx => ctx.redirect('/422'));
class HomeController extends Controller {
+ @Validate([
+ [paramsSchema, ctx => ctx.params],
+ [bodySchema, ctx => ctx.request.body, (ctx, errors) => 'MyErrorPrefix: ' + errors.map(e => e.message).join(', ')],
+ ])
async index() {
const { ctx } = this;
// 直接校验
- ctx.tValidate(paramsSchema, ctx.params);
- ctx.tValidate(bodySchema, ctx.request.body);
// 不用写 js 类型定义
const params: ParamsType = ctx.params;
...
}
+ @ValidateWithRedirect([paramsSchema, ctx => ctx.params])
async post() {
// ...
}
}
export default HomeController;
目前装饰器只支持有 this.ctx
的 class 上使用,比如 controller,service 等。也可以通过内置的 ValidateFactory
自定义校验失败后的回调逻辑,更多使用案例可以看这个项目里写的测试用例。
怎么写 typebox 定义
参考 https://github.com/sinclairzx81/typebox#types
支持 ajv 对 string 的 transform 校验
比如:
const body = { name: ' david '}
ctx.tValidate(Type.Object({
name: Type.String({ minLength: 1, maxLength: 5, transform: ['trim'] })
}), body)
- 是可以通过校验的
- 会对 body 有副作用,改写 name 字段,trim name 字段,body 会变成
{ name: 'david' }
更多 ajv 对 string 的 transform 操作,详见 https://ajv.js.org/packages/ajv-keywords.html#transform
如何写自定义校验规则
比如想校验上传的 string 是否是合法的 json string,我们可以对 Type.String 的 format 做 patch,针对 string 加一个 'json-string' 的 format
- 在 config.default.ts 里 patch 默认 ajv 实例的规则
config.typeboxValidate = {
patchAjv: (ajv) => {
ajv.addFormat('json-string', {
type: 'string',
validate: (x) => {
try {
JSON.parse(x);
return true;
} catch (err) {
return false;
}
}
});
}
}
- 使用
async someFunc() {
const typebox = Type.Object({
jsonString: Type.Optional(Type.String({ format: 'json-string' })),
});
const res = ctx.tValidate(typebox, { a: '{"a":1}' }) // valid
const res = ctx.tValidate(typebox, { a: 'wrong{"a":1}' }) // invalid
}
当然也可以定义其他各种规则,比如我们常见的 semver 规范,那可以在我们的配置里继续 patch ajv string format
+ import { valid } from 'semver';
config.typeboxValidate = {
patchAjv: (ajv) => {
ajv.addFormat('json-string', {
type: 'string',
validate: (x) => {
try {
JSON.parse(x);
return true;
} catch (err) {
return false;
}
}
});
+ ajv.addFormat("semver", {
+ type: "string",
+ validate: (x) => valid(x) != null,
+ })
}
}
使用例子:
async someFunc() {
const typebox = Type.Object({
version: Type.String({ format: 'semver' }),
});
const res = ctx.tValidate(typebox, { a: '1.0.0' }) // valid
const res = ctx.tValidate(typebox, { a: 'a.b.c' }) // invalid
}
上面例子是 string 的例子,当然也可以对其他类型做其他 patch,比如 number,array 等,限制你的只有想象力。
全部 json-schema 支持的类型:https://json-schema.org/understanding-json-schema/reference/type.html