本文详解在 Joi.js 中实现“至少一个布尔字段必须为 true”的条件校验方案，通过 when() 与 Joi.equal(null, false) 精准捕获缺失、null 或 false 状态，并配合自定义错误提示与可复用函数封装，满足遗留系统严苛的验证需求。
本文详解在 joi.js 中实现“至少一个布尔字段必须为 true”的条件校验方案，通过 `when()` 与 `joi.equal(null, false)` 精准捕获缺失、`null` 或 `false` 状态，并配合自定义错误提示与可复用函数封装，满足遗留系统严苛的验证需求。
在构建健壮的 API 输入验证时，常会遇到“互斥但非空”类逻辑——例如要求对象中 a 和 b 两个布尔字段至少有一个显式为 true，而两者均可选、允许 undefined 或 null，但绝不允许同时为 false、全缺或全 null。Joi 原生不提供 oneOfTrue() 这类快捷方法，需巧妙组合 when()、Joi.equal() 与条件规则达成目标。
核心思路是：将其中一个字段设为“主控”，当它不为 true（即为 null、undefined 或 false）时，强制另一个字段必须存在且严格等于 true。注意：Joi.equal(null, false) 能同时匹配 null、undefined（因 Joi 默认将缺失值转为 undefined）及 false，完美覆盖所有“非真”状态。
以下是可直接运行的完整 Schema 示例：
const Joi = require('joi');
const exampleSchema = Joi.object({
a: Joi.boolean().optional(),
b: Joi.boolean()
.when('a', {
is: Joi.equal(null, false), // 当 a 缺失 / null / false 时触发
then: Joi.valid(true).required() // b 必须为 true 且存在
})
.messages({
'any.required': 'at least one of "a" or "b" must be strictly true',
'any.only': 'at least one of "a" or "b" must be strictly true'
})
});
✅ 该 Schema 通过全部测试用例：
- { a: false, b: false } → ❌ 失败（两者均为 false）
- { a: null, b: null } → ❌ 失败（均非 true）
- {} 或 { a: false } → ❌ 失败（a 不为 true，触发 b 必须 required 且 true，但 b 缺失）
- { a: true } 或 { b: true } → ✅ 通过
- { a: true, b: null } → ✅ 通过（a 已满足条件，b 无需校验）
⚠️ 关键注意事项：
- 不要使用 .valid(true) 单独约束：Joi.boolean().valid(true) 仍接受 undefined（因 undefined 不违反 valid(true)），必须搭配 .required() 强制存在。
- Joi.equal(null, false) 是关键：它等价于 Joi.valid(null, false).allow(undefined)，精准覆盖所有“非真”情形；若仅写 is: false，则无法捕获 undefined/null。
- 错误消息统一处理：.messages() 应同时覆盖 'any.required'（字段缺失）和 'any.only'（值不匹配），避免用户收到模糊提示。
- 双向校验？不必：上述单向配置已完备。若强行对 a 也加 when('b')，会导致循环依赖警告（Joi v17+），且逻辑冗余。
为提升可维护性，推荐封装为复用函数：
const oneMustBeTrue = (fieldA, fieldB) => {
const schema = {};
schema[fieldA] = Joi.boolean().optional();
schema[fieldB] = Joi.boolean()
.when(fieldA, {
is: Joi.equal(null, false),
then: Joi.valid(true).required()
})
.messages({
'any.required': `at least one of "${fieldA}" or "${fieldB}" must be strictly true`,
'any.only': `at least one of "${fieldA}" or "${fieldB}" must be strictly true`
});
return schema;
};
// 使用示例
const exampleSchema = Joi.object(oneMustBeTrue('a', 'b'));
此方案完全兼容 Joi v16/v17，无需引入 JSON Schema 或修改现有验证体系，是遗留系统增量增强验证能力的务实之选。
