鹏展博

外观

joi

约 515 字

NodeJS Browser

概述

Joi 官方文档

Joi 由 Hapi.js 团队开发，是一个强大的 JavaScript 数据验证库，专注于为 Node.js 和浏览器环境提供声明式的对象模式描述与验证能力。

特性

  • 声明式 Schema 定义

    Joi 通过链式 API 定义数据模式（Schema），以简洁的语法描述数据结构与规则。例如：

    const schema = Joi.object({
  username: Joi.string().alphanum().min(3).max(30).required(),
  email: Joi.string().email().required(),
  password: Joi.string().regex(/^[a-zA-Z0-9]{3,30}$/),
  birthdate: Joi.date().min('1900-01-01').max('now'),
  address: Joi.object({
    street: Joi.string().required(),
    city: Joi.string().required()
  })
})
    • 类型支持：覆盖 string, number, boolean, date, array, object, binary 等基础与复合类型
    • 链式规则：如 .min(), .max(), .regex(), .email(), .required() 等，可组合使用

  • 嵌套结构与复杂验证

    • 支持多级对象嵌套（如 address.city）

    • 条件验证：通过 Joi.when() 实现动态规则（如当性别为男性时要求填写 maleSpecificField）

      const schema = Joi.object({
  sex: Joi.number().valid(0, 1),
  name2: Joi.when('sex', { is: 1, then: Joi.string().required() })
})

  • 字段依赖与互斥

    • .with('fieldA', 'fieldB')：若 fieldA 存在，则 fieldB 必填。
    • .without('fieldA', 'fieldB')：fieldA 和 fieldB 不能同时存在

  • 数据清洗与转换

    • 自动格式化数据（如字符串转日期、数字转字符串）
    • 移除非法字段（strip()）或设置默认值（.default('value')）

  • 错误处理

    • 返回详细错误信息（包括错误字段、类型及原因），支持自定义错误消息（.error(new Error('自定义消息'))）
    • 控制错误报告策略：abortEarly: false 可收集所有错误而非在首次失败时终止

安装

npm
npm install joi
pnpm
pnpm add joi
yarn
yarn add joi

使用

import joi from 'joi'

// 定义 Schema
const schema = Joi.object({
  username: Joi.string().min(3).required(),
  age: Joi.number().integer().min(18).default(20),
  hobbies: Joi.array().items(Joi.string()).min(1)
})

// 验证数据
const data = { username: 'Tom', age: 25 }
const { error, value } = schema.validate(data, { abortEarly: false })

if (error) {
  console.error(error.details) // 输出所有错误详情
}
else {
  console.log(value) // 输出清洗后数据（包含默认值）
}

使用场景

  • API 请求验证
  • 配置文件校验
  • 表单与用户输入
  • 数据库模型验证