深入解析jquense/yup：如何扩展Schema类型与方法

前言

在表单验证领域，jquense/yup是一个功能强大且灵活的JavaScript对象模式验证库。本文将深入探讨如何扩展yup的Schema类型和方法，帮助开发者根据项目需求定制专属的验证逻辑。

基础扩展：复用Schema配置

对于简单的复用场景，我们可以创建基础Schema实例并在项目中共享使用。这种方式简单直接，且能保持完整的类型推断。

import * as yup from 'yup';

// 创建必填字符串Schema
const requiredString = yup.string().required().default('');

// 创建支持多种日期格式的Schema工厂函数
const momentDate = (parseFormats = ['MMM dd, yyy']) =>
  yup.date().transform(function (value, originalValue) {
    if (this.isType(value)) return value;
    
    // 使用Moment.js解析日期
    value = Moment(originalValue, parseFormats);
    return value.isValid() ? value.toDate() : yup.date.INVALID_DATE;
  });

关键点：

• yup的Schema是不可变(immutable)的，每次修改都会返回新实例
• 可以通过工厂函数创建可配置的Schema模板
• 使用transform方法可以实现自定义的值转换逻辑

方法扩展：为现有Schema添加新方法

yup提供了addMethod工具函数，允许我们为内置Schema类型添加自定义方法。

// 定义日期格式解析方法
function parseDateFromFormats(formats, parseStrict) {
  return this.transform(function (value, originalValue) {
    if (this.isType(value)) return value;
    
    value = Moment(originalValue, formats, parseStrict);
    return value.isValid() ? value.toDate() : yup.date.INVALID_DATE;
  });
}

// 将方法添加到yup.date类型
yup.addMethod(yup.date, 'format', parseDateFromFormats);

注意事项：

• addMethod会修改传入Schema的原型
• 在TypeScript中需要额外声明类型（本文不展开讨论）
• 新方法应该遵循yup的不可变原则，返回新实例而非修改原实例

高级扩展：创建全新Schema类型

当需要实现全新的验证类型时，可以通过继承现有Schema类来创建自定义Schema。

实现要点

1. 继承选择：

   • 避免直接继承抽象的Schema类
   • 选择最接近的现有Schema类型作为基类（如DateSchema）

2. 核心原则：

   • 永远不直接修改现有Schema实例
   • 转换函数不应改变输入值
   • 对于无效值，返回特定标识而非null

实战示例：MomentDateSchema

import { DateSchema } from 'yup';

class MomentDateSchema extends DateSchema {
  static create() {
    return new MomentDateSchema();
  }

  constructor() {
    super();
    this._validFormats = [];
    
    this.withMutation(() => {
      this.transform(function (value, originalValue) {
        if (this.isType(value)) return value;
        return Moment(originalValue, this._validFormats, true);
      });
    });
  }

  // 自定义类型检查逻辑
  _typeCheck(value) {
    return (
      super._typeCheck(value) || 
      (moment.isMoment(value) && value.isValid())
    );
  }

  // 添加format方法
  format(formats) {
    if (!formats) throw new Error('必须提供有效格式');
    let next = this.clone();
    next._validFormats = [].concat(formats);
    return next;
  }
}

使用示例：

const schema = new MomentDateSchema();
schema.format('YYYY-MM-DD').cast('It is 2012-05-25'); 
// 输出: Fri May 25 2012 00:00:00 GMT-0400 (Eastern Daylight Time)

最佳实践总结

1. 优先使用组合而非继承：大多数情况下，组合现有Schema和方法就能满足需求

2. 保持不可变性：所有自定义方法都应返回新实例

3. 明确无效状态：转换函数应返回明确的无效标识

4. 类型安全：确保自定义Schema在TypeScript中也能正确推断类型

5. 文档完善：为自定义方法编写清晰的文档说明

通过灵活运用这些扩展技术，开发者可以大幅提升yup在复杂场景下的适用性，构建出既强大又符合项目特定需求的验证系统。