本文介绍如何利用 Joi 的条件验证（.when()）机制，实现“Latitude/Longitude 二者任一提供即跳过地址字段校验，否则 AddressLine、City、PostalCode 必须全部非空”的业务规则。

本文介绍如何利用 joi 的条件验证（`.when()`）机制，实现“latitude/longitude 二者任一提供即跳过地址字段校验，否则 addressline、city、postalcode 必须全部非空”的业务规则。

在构建 API 请求校验逻辑时，常遇到“二选一”或“互斥必填”的复合验证需求。例如本例中的地址对象：系统既支持通过经纬度（Latitude/Longitude）精确定位，也支持通过结构化文本地址（AddressLine、City、PostalCode）模糊匹配。业务规则明确要求：只要 Latitude 或 Longitude 中至少一个为有效数值（非 null、非 undefined、非空字符串），则地址三字段可选；否则三者必须全部存在且非空。

Joi 并不直接支持“多字段联合条件判断”，但可通过嵌套 .when() 实现等效逻辑。核心思路是：以 Longitude 为第一判据，若其为 null，则强制校验地址字段；若其非 null，再进一步检查 Latitude —— 若 Latitude 也为 null，仍需地址字段；仅当二者均非 null 时，地址字段才可省略。

以下是完整、健壮的 Joi 校验 Schema 示例：

const Joi = require('joi');

const addressSchema = Joi.object({
  Longitude: Joi.number().allow(null, '').optional(),
  Latitude: Joi.number().allow(null, '').optional(),
  AddressLine: Joi.string()
    .when('Longitude', {
      is: Joi.exist().not(null).not(''),
      then: Joi.string().optional().allow(null, ''),
      otherwise: Joi.string()
        .when('Latitude', {
          is: Joi.exist().not(null).not(''),
          then: Joi.string().optional().allow(null, ''),
          otherwise: Joi.string().required().min(1).label('AddressLine')
        })
    })
    .label('AddressLine'),
  City: Joi.string()
    .when('Longitude', {
      is: Joi.exist().not(null).not(''),
      then: Joi.string().optional().allow(null, ''),
      otherwise: Joi.string()
        .when('Latitude', {
          is: Joi.exist().not(null).not(''),
          then: Joi.string().optional().allow(null, ''),
          otherwise: Joi.string().required().min(1).label('City')
        })
    })
    .label('City'),
  PostalCode: Joi.string()
    .when('Longitude', {
      is: Joi.exist().not(null).not(''),
      then: Joi.string().optional().allow(null, ''),
      otherwise: Joi.string()
        .when('Latitude', {
          is: Joi.exist().not(null).not(''),
          then: Joi.string().optional().allow(null, ''),
          otherwise: Joi.string().required().min(1).label('PostalCode')
        })
    })
    .label('PostalCode'),
}).unknown(true);

const dataSchema = Joi.object({
  Id: Joi.string().uuid().required().label('Task ID'),
  Address: addressSchema,
}).unknown(true);

function validateData(data) {
  return dataSchema.validate(data, { abortEarly: false });
}

module.exports = { validateData };

✅ 关键说明与最佳实践：

• 使用 Joi.exist().not(null).not('') 替代简单的 is: null，确保能正确识别 0、false 等 falsy 但合法的数值（Latitude/Longitude 可为 0）；
• 显式调用 .allow(null, '') 避免空字符串被默认拒绝；
• 地址字段在“必填分支”中添加 .min(1)，防止仅传入空白字符串；
• 启用 { abortEarly: false } 可一次性返回所有校验错误，提升调试效率；
• 将 Address Schema 单独提取为常量，增强可读性与复用性。

⚠️ 注意事项：

• Joi v17+ 中 Joi.forbidden() 不适用于条件分支的 then/otherwise，应改用 Joi.optional().allow(null, '') 或 Joi.any().valid(null).optional()；
• 若业务允许 Latitude/Longitude 为字符串形式（如 "40.7128"），需配合 .pattern() 或自定义转换；
• 前端提交时建议统一将空经纬度设为 null，避免因字符串 "null" 或空格导致校验失效。

通过上述方案，你既能精准满足“经纬度优先、地址兜底”的业务语义，又能保持校验逻辑清晰、可维护、可测试。