joi

概述

joi 是 Node.js 中老牌的数据校验库，通过声明式 Schema 定义规则，校验请求体、查询参数等。支持链式 API、类型丰富、错误信息友好。适合 Express/Koa 等框架。

安装：

npm install joi

核心函数

joi.object() — 创建 Schema

const Joi = require('joi')

// 字符串校验
const schema = Joi.object({
  name: Joi.string().min(2).max(50).required(),
  email: Joi.string().email().required(),
  password: Joi.string().pattern(/^[a-zA-Z0-9]{8,30}$/).required(),
  url: Joi.string().uri(),
  phone: Joi.string().pattern(/^1[3-9]\d{9}$/),
  age: Joi.number().min(0).max(150),
  page: Joi.number().integer().min(1).default(1),
  role: Joi.string().valid('admin', 'user', 'guest'),
  tags: Joi.array().items(Joi.string()),
  config: Joi.object({
    theme: Joi.string()
  }),
  status: Joi.boolean().truthy('yes').falsy('no'),
  createdAt: Joi.date().iso()
})

// 校验
const { error, value } = schema.validate(data, { abortEarly: false })
// error — 校验失败信息
// value — 通过校验的数据（含默认值）

常用类型

Joi.string()                  // 字符串
Joi.number()                  // 数字
Joi.boolean()                 // 布尔
Joi.array().items(Joi.string()) // 数组
Joi.object({ ... })           // 对象
Joi.date()                    // 日期
Joi.binary()                  // Buffer/二进制
Joi.alternatives()            // 联合类型
Joi.any()                     // 任意类型
Joi.symbol()                  // Symbol
Joi.func()                    // 函数

链式规则

Joi.string()
  .min(2)                    // 最小长度
  .max(100)                  // 最大长度
  .length(11)                // 固定长度
  .pattern(/^\d+$/)          // 正则
  .email()                   // 邮箱
  .uri()                     // URL
  .uuid()                    // UUID
  .alphanum()               // 仅字母数字
  .token()                  // 字母数字下划线
  .lowercase()              // 自动转小写
  .uppercase()              // 自动转大写
  .trim()                   // 自动去除首尾空格
  .required()               // 必填
  .optional()               // 可选
  .allow('')                // 允许的值（包含空字符串）
  .invalid('admin')         // 不允许的值
  .default('xxx')           // 默认值
  .valid('a', 'b')          // 枚举
  .label('用户名')           // 错误中显示的名称
  .description('描述')      // 文档用
  .example('xxx')           // 文档用

校验选项

schema.validate(data, {
  abortEarly: false,         // 收集所有错误（默认 true）
  stripUnknown: true,        // 删除未知字段
  convert: true,             // 自动类型转换
  allowUnknown: false,       // 允许未知字段
  cache: true,               // 缓存编译结果
  context: {},               // 上下文（自定义规则中可用）
  messages: {}               // 自定义错误信息
})

常见问题