Formily表单验证实战指南：从业务痛点到架构设计的完整解决方案-拓冰建站

Formily表单验证实战指南：从业务痛点到架构设计的完整解决方案

【免费下载链接】formily📱🚀 🧩 Cross Device & High Performance Normal Form/Dynamic(JSON Schema) Form/Form Builder -- Support React/React Native/Vue 2/Vue 3项目地址: https://gitcode.com/gh_mirrors/fo/formily

你是否曾为复杂表单验证而烦恼？当业务需求从简单的必填项检查演变为复杂的联动验证、异步校验时，传统表单方案往往力不从心。Formily作为跨设备、高性能的表单解决方案，其验证引擎@formily/validator提供了前所未有的灵活性和扩展性。本文将带你深入Formily验证系统的核心，从实际业务场景出发，探索如何构建健壮、可维护的表单验证体系。

痛点剖析：为什么传统表单验证方案总是不够用？

在真实业务场景中，表单验证远不止"必填"和"格式校验"那么简单。让我们看看几个典型痛点：

场景一：动态联动验证用户选择"企业用户"时，需要验证营业执照号；选择"个人用户"时，需要验证身份证号。传统方案需要在多个地方编写条件判断逻辑，代码分散且难以维护。

场景二：异步数据校验注册时检查用户名是否已存在、提交前验证库存是否充足，这些都需要与后端API交互。传统方案中，异步验证与同步验证混在一起，错误处理和loading状态管理复杂。

场景三：复合验证规则密码强度验证需要同时满足：长度8-20位、包含大小写字母、包含数字、包含特殊字符。传统方案要么写冗长的正则表达式，要么分散在多个验证函数中。

场景四：验证信息国际化同一个表单需要支持多语言环境，验证错误信息需要根据用户语言动态切换。传统方案需要在每个验证规则中硬编码多语言逻辑。

Formily的验证系统正是为了解决这些问题而生，它通过统一的验证引擎、灵活的规则组合、强大的扩展能力，让复杂表单验证变得简单而优雅。

架构设计：Formily验证系统的核心原理

Formily的验证架构基于响应式设计和插件化思想，让我们深入其核心实现：

验证引擎架构图

┌─────────────────────────────────────────────────────────────┐ │ Formily Validation Engine │ ├──────────────┬────────────────┬─────────────────────────────┤ │ Core │ Rules │ Extensions │ │ ┌─────────┐│ ┌──────────┐│ ┌───────────────────────┐│ │ │ Registry││ │ Built-in ││ │ Custom Validators ││ │ │ ││ │ Rules ││ │ ││ │ └─────────┘│ └──────────┘│ └───────────────────────┘│ ├──────────────┼────────────────┼─────────────────────────────┤ │ Pipeline │ Context │ Error Handling │ │ ┌─────────┐│ ┌──────────┐│ ┌───────────────────────┐│ │ │ Sync ││ │ Field ││ │ Message ││ │ │ Async ││ │ Form ││ │ Formatting ││ │ └─────────┘│ └──────────┘│ └───────────────────────┘│ └──────────────┴────────────────┴─────────────────────────────┘

核心源码解析

让我们查看Formily验证系统的核心实现。验证引擎的核心逻辑位于packages/validator/src/validator.ts：

// Formily验证器核心接口 interface Validator { (value: any, rule: any, context: ValidatorContext): string | undefined | Promise<string | undefined>; } // 验证上下文，包含完整的表单状态 interface ValidatorContext { form: Form; // 表单实例 field: Field; // 字段实例 path: string; // 字段路径 rules: any[]; // 验证规则数组 } // 验证规则注册器 class ValidatorRegistry { private rules: Map<string, Validator> = new Map(); register(name: string, validator: Validator): void { this.rules.set(name, validator); } validate(value: any, rules: any[], context: ValidatorContext): Promise<ValidationResult[]> { // 执行验证流水线 return Promise.all( rules.map(rule => this.executeRule(value, rule, context)) ); } }

这个架构设计的关键优势在于：

插件化规则系统：可以动态注册和卸载验证规则
统一的验证上下文：所有验证规则都能访问完整的表单状态
异步友好的设计：同步和异步验证使用相同的API
错误信息标准化：统一的错误格式便于国际化处理

实战演练：解决复杂业务场景的验证需求

场景一：动态联动验证的实现

假设我们需要实现一个用户类型选择表单，企业用户需要验证营业执照，个人用户需要验证身份证：

import { createForm, registerValidateRules } from '@formily/core'; import { createSchemaField } from '@formily/react'; import { Form, FormItem, Input, Select } from '@formily/antd'; // 注册自定义验证规则 registerValidateRules({ businessLicense(value, rule, ctx) { const userType = ctx.form.values.userType; if (userType === 'enterprise' && !value) { return '请输入营业执照号'; } if (value && !/^[A-Z0-9]{15}$/.test(value)) { return '营业执照号格式不正确'; } }, idCard(value, rule, ctx) { const userType = ctx.form.values.userType; if (userType === 'personal' && !value) { return '请输入身份证号'; } if (value && !/^\d{17}[\dX]$/.test(value)) { return '身份证号格式不正确'; } } }); const form = createForm({ effects: (form) => { // 监听用户类型变化，动态调整验证规则 form.onFieldValueChange('userType', (field) => { const userType = field.value; const licenseField = form.query('license').take(); const idCardField = form.query('idCard').take(); if (userType === 'enterprise') { licenseField?.setRequired(true); idCardField?.setRequired(false); } else if (userType === 'personal') { licenseField?.setRequired(false); idCardField?.setRequired(true); } }); } }); const SchemaField = createSchemaField({ components: { FormItem, Input, Select } }); export default () => ( <Form form={form}> <SchemaField> <SchemaField.String name="userType" title="用户类型" required enum={[ { label: '个人用户', value: 'personal' }, { label: '企业用户', value: 'enterprise' } ]} x-component="Select" x-decorator="FormItem" /> <SchemaField.String name="license" title="营业执照号" x-validator="businessLicense" x-component="Input" x-decorator="FormItem" x-reactions={{ fulfill: { state: { visible: "{{$form.values.userType === 'enterprise'}}" } } }} /> <SchemaField.String name="idCard" title="身份证号" x-validator="idCard" x-component="Input" x-decorator="FormItem" x-reactions={{ fulfill: { state: { visible: "{{$form.values.userType === 'personal'}}" } } }} /> </SchemaField> </Form> );

场景二：高性能异步验证优化

异步验证容易成为性能瓶颈，Formily提供了多种优化策略：

import { debounce } from 'lodash'; // 优化方案1：防抖验证 const debouncedValidate = debounce(async (value) => { if (!value) return ''; try { const exists = await checkUsernameExists(value); return exists ? '用户名已存在' : ''; } catch (error) { return '验证服务暂时不可用'; } }, 500); // 优化方案2：缓存验证结果 const validationCache = new Map(); async function validateWithCache(value, validator) { if (validationCache.has(value)) { return validationCache.get(value); } const result = await validator(value); validationCache.set(value, result); return result; } // 优化方案3：批量验证 async function batchValidate(fields) { const promises = fields.map(field => field.validate().catch(error => ({ field: field.path, error: error.message })) ); const results = await Promise.allSettled(promises); return results.filter(r => r.status === 'rejected'); } // 实际应用示例 <SchemaField.String name="username" title="用户名" required x-validator={async (value) => { // 空值快速返回 if (!value || value.length < 3) { return '用户名至少3个字符'; } // 使用防抖和缓存 return validateWithCache(value, debouncedValidate); }} x-component="Input" x-decorator="FormItem" />

场景三：复合验证规则的最佳实践

对于复杂的密码强度验证，我们可以创建可复用的验证规则组合：

// 创建密码强度验证器工厂 function createPasswordValidator(options = {}) { const { minLength = 8, maxLength = 20, requireUppercase = true, requireLowercase = true, requireNumbers = true, requireSpecialChars = true } = options; return function passwordValidator(value) { if (!value) return ''; const errors = []; // 长度检查 if (value.length < minLength) { errors.push(`密码长度不能少于${minLength}位`); } if (value.length > maxLength) { errors.push(`密码长度不能超过${maxLength}位`); } // 复杂度检查 if (requireUppercase && !/[A-Z]/.test(value)) { errors.push('必须包含大写字母'); } if (requireLowercase && !/[a-z]/.test(value)) { errors.push('必须包含小写字母'); } if (requireNumbers && !/\d/.test(value)) { errors.push('必须包含数字'); } if (requireSpecialChars && !/[!@#$%^&*(),.?":{}|<>]/.test(value)) { errors.push('必须包含特殊字符'); } return errors.length > 0 ? errors.join('；') : ''; }; } // 注册为全局规则 registerValidateRules({ passwordStrength: createPasswordValidator({ minLength: 8, requireSpecialChars: false // 根据业务需求调整 }) }); // 使用示例 <SchemaField.String name="password" title="密码" required x-validator="passwordStrength" x-component="Input.Password" x-decorator="FormItem" />

性能优化与最佳实践

1. 验证时机优化

Formily支持多种验证触发时机，合理选择可以显著提升性能：

触发时机	适用场景	性能影响
onInput	实时反馈（如密码强度）	高频率，需防抖
onBlur	表单字段验证	中等频率，用户体验好
onSubmit	最终提交验证	低频，性能最优
onChange	联动验证	根据业务需求调整

// 按需配置验证触发时机 const form = createForm({ validateFirst: true, // 遇到第一个错误就停止验证 effects(form) { // 关键字段实时验证 form.onFieldInput('password', (field) => { field.validate({ triggerType: 'onInput' }); }); // 非关键字段失焦验证 form.onFieldBlur('username', (field) => { field.validate({ triggerType: 'onBlur' }); }); } });

2. 验证规则缓存策略

对于计算密集型的验证规则，使用缓存可以大幅提升性能：

// 验证结果缓存 const validationCache = new Map(); // 带缓存的验证函数 function cachedValidator(validator, cacheKey) { return async function(value, rule, ctx) { const key = `${cacheKey}:${value}`; if (validationCache.has(key)) { return validationCache.get(key); } const result = await validator(value, rule, ctx); validationCache.set(key, result); // 定期清理缓存 if (validationCache.size > 1000) { const keys = Array.from(validationCache.keys()); for (let i = 0; i < 100; i++) { validationCache.delete(keys[i]); } } return result; }; } // 复杂计算验证规则 const complexValidator = cachedValidator(async (value) => { // 模拟复杂计算 await new Promise(resolve => setTimeout(resolve, 100)); return value === 'test' ? '不能使用test作为值' : ''; }, 'complex-check');

3. 错误处理与用户体验

良好的错误处理能提升用户体验，Formily提供了丰富的错误处理API：

// 统一错误处理器 function createErrorHandler(form) { return { // 获取所有错误 getAllErrors() { return Array.from(form.fields.values()) .filter(field => field.invalid) .map(field => ({ path: field.path.toString(), errors: field.errors, component: field.component?.[1]?.name })); }, // 聚焦到第一个错误字段 focusFirstError() { const firstErrorField = Array.from(form.fields.values()) .find(field => field.invalid); if (firstErrorField) { const element = document.querySelector( `[data-formily-path="${firstErrorField.path}"]` ); element?.focus?.(); element?.scrollIntoView?.({ behavior: 'smooth', block: 'center' }); } }, // 格式化错误信息用于显示 formatErrors() { return this.getAllErrors().map(error => ({ field: error.path, messages: error.errors.map(err => err.message || err), component: error.component })); } }; } // 在表单提交时使用 const handleSubmit = async () => { const isValid = await form.validate(); if (!isValid) { const errorHandler = createErrorHandler(form); const errors = errorHandler.formatErrors(); // 显示错误摘要 showErrorSummary(errors); // 聚焦到第一个错误 errorHandler.focusFirstError(); return; } // 提交表单 await submitForm(form.values); };

架构扩展：自定义验证引擎的高级用法

1. 创建领域特定的验证器

对于特定业务领域，可以创建专门的验证器：

// 金融领域验证器 class FinancialValidator { // 银行卡号验证（Luhn算法） static bankCard(value) { if (!value) return ''; // 移除空格和连字符 const cleaned = value.replace(/[\s-]/g, ''); if (!/^\d{13,19}$/.test(cleaned)) { return '银行卡号格式不正确'; } // Luhn算法验证 let sum = 0; let alternate = false; for (let i = cleaned.length - 1; i >= 0; i--) { let digit = parseInt(cleaned.charAt(i), 10); if (alternate) { digit *= 2; if (digit > 9) { digit = (digit % 10) + 1; } } sum += digit; alternate = !alternate; } return sum % 10 === 0 ? '' : '银行卡号无效'; } // 金额验证（支持千分位分隔符） static amount(value, options = {}) { if (!value) return ''; const { min, max, allowNegative = false } = options; const cleaned = value.replace(/,/g, ''); const numValue = parseFloat(cleaned); if (isNaN(numValue)) { return '请输入有效的金额'; } if (!allowNegative && numValue < 0) { return '金额不能为负数'; } if (min !== undefined && numValue < min) { return `金额不能小于${min}`; } if (max !== undefined && numValue > max) { return `金额不能大于${max}`; } return ''; } } // 注册到Formily registerValidateRules({ bankCard: FinancialValidator.bankCard, amount: FinancialValidator.amount });

2. 验证规则组合器

对于复杂的验证逻辑，可以创建规则组合器：

// 验证规则组合器 class ValidatorComposer { constructor() { this.rules = []; } // 添加规则 add(validator, options = {}) { this.rules.push({ validator, options }); return this; } // 异步执行所有规则 async validate(value, context) { const results = []; for (const { validator, options } of this.rules) { const result = await validator(value, options, context); if (result) { results.push(result); // 如果配置了validateFirst，遇到第一个错误就停止 if (options.validateFirst) { break; } } } return results; } // 创建验证函数 compile() { return async (value, rule, context) => { const errors = await this.validate(value, context); return errors.length > 0 ? errors.join('；') : ''; }; } } // 使用示例：创建用户注册验证器 const registerValidator = new ValidatorComposer() .add((value) => !value ? '用户名不能为空' : '', { validateFirst: true }) .add((value) => value.length < 3 ? '用户名至少3个字符' : '') .add((value) => !/^[a-zA-Z0-9_]+$/.test(value) ? '只能包含字母、数字和下划线' : '') .add(async (value) => { const exists = await checkUsernameExists(value); return exists ? '用户名已存在' : ''; }) .compile(); // 在表单中使用 <SchemaField.String name="username" title="用户名" x-validator={registerValidator} x-component="Input" x-decorator="FormItem" />

3. 验证规则可视化配置

对于需要业务人员配置验证规则的系统，可以创建可视化配置界面：

// 验证规则配置接口 interface ValidationRuleConfig { type: 'required' | 'pattern' | 'range' | 'custom'; message: string; params?: Record<string, any>; enabled: boolean; } // 配置到验证规则的转换器 function configToValidator(configs: ValidationRuleConfig[]) { return async function(value, rule, context) { for (const config of configs) { if (!config.enabled) continue; let error = ''; switch (config.type) { case 'required': if (!value) error = config.message; break; case 'pattern': if (value && !new RegExp(config.params?.pattern).test(value)) { error = config.message; } break; case 'range': if (value !== undefined && value !== null) { const { min, max } = config.params || {}; if (min !== undefined && value < min) { error = config.message.replace('{min}', min); } if (max !== undefined && value > max) { error = config.message.replace('{max}', max); } } break; case 'custom': if (config.params?.validator) { error = await config.params.validator(value, context); } break; } if (error) return error; } return ''; }; } // 从数据库或配置文件中加载验证规则 async function loadValidationRules(fieldId) { const configs = await fetchValidationConfigs(fieldId); return configToValidator(configs); }

测试策略与质量保障

1. 单元测试验证规则

确保验证规则的可靠性：

import { Validator } from '@formily/validator'; describe('Formily Validation Rules', () => { let validator: Validator; beforeEach(() => { validator = new Validator(); }); test('required rule validation', async () => { const rule = { required: true, message: '字段不能为空' }; // 测试空值 const result1 = await validator.validate('', [rule]); expect(result1[0].message).toBe('字段不能为空'); // 测试非空值 const result2 = await validator.validate('value', [rule]); expect(result2[0]).toBeUndefined(); }); test('custom rule validation', async () => { const customRule = { validator: (value) => value === 'test' ? '不能使用test' : '' }; const result1 = await validator.validate('test', [customRule]); expect(result1[0].message).toBe('不能使用test'); const result2 = await validator.validate('other', [customRule]); expect(result2[0]).toBeUndefined(); }); test('async rule validation', async () => { const asyncRule = { validator: async (value) => { await new Promise(resolve => setTimeout(resolve, 100)); return value === 'async' ? '异步验证失败' : ''; } }; const result = await validator.validate('async', [asyncRule]); expect(result[0].message).toBe('异步验证失败'); }); });

2. 集成测试表单验证流程

describe('Form Validation Integration', () => { test('complete form validation flow', async () => { const form = createForm({ initialValues: { username: '', password: '', confirmPassword: '' } }); const field1 = form.createField({ name: 'username', required: true, validator: (value) => !value ? '用户名必填' : '' }); const field2 = form.createField({ name: 'password', required: true, validator: (value) => value && value.length < 6 ? '密码至少6位' : '' }); // 验证整个表单 const isValid = await form.validate(); expect(isValid).toBe(false); // 检查具体错误 expect(field1.errors).toContain('用户名必填'); expect(field2.errors).toContain('密码至少6位'); // 修复错误后重新验证 field1.value = 'testuser'; field2.value = 'password123'; const isValidAfter = await form.validate(); expect(isValidAfter).toBe(true); }); });

3. 性能测试与监控

// 性能测试工具 class ValidationPerformanceTester { constructor() { this.metrics = { totalValidations: 0, totalTime: 0, averageTime: 0, maxTime: 0, minTime: Infinity }; } async testValidator(validator, testCases) { const startTime = performance.now(); for (const testCase of testCases) { const caseStart = performance.now(); await validator.validate(testCase.value, testCase.rules); const caseTime = performance.now() - caseStart; this.metrics.totalValidations++; this.metrics.totalTime += caseTime; this.metrics.maxTime = Math.max(this.metrics.maxTime, caseTime); this.metrics.minTime = Math.min(this.metrics.minTime, caseTime); } this.metrics.averageTime = this.metrics.totalTime / this.metrics.totalValidations; this.metrics.totalDuration = performance.now() - startTime; return this.metrics; } generateReport() { return { ...this.metrics, operationsPerSecond: (this.metrics.totalValidations / this.metrics.totalDuration) * 1000 }; } } // 使用示例 const tester = new ValidationPerformanceTester(); const validator = new Validator(); const testCases = Array.from({ length: 1000 }, (_, i) => ({ value: `test${i}`, rules: [ { required: true }, { min: 3 }, { pattern: /^[a-zA-Z0-9]+$/ } ] })); const report = await tester.testValidator(validator, testCases); console.log('性能测试报告:', report);