当前位置：首页 > news >正文

tschema扩展开发：自定义验证器和类型转换器实现终极指南 [特殊字符]

news 2026/7/17 9:57:58

tschema扩展开发：自定义验证器和类型转换器实现终极指南 🚀

【免费下载链接】tschemaA tiny (500b) utility to build JSON schema types.项目地址: https://gitcode.com/gh_mirrors/ts/tschema

tschema是一个轻量级的JSON Schema类型构建工具，只有500字节大小！它为TypeScript开发者提供了强大的类型定义和验证能力。本文将为您详细介绍如何扩展tschema，创建自定义验证器和类型转换器，让您的类型系统更加灵活和强大。

为什么需要tschema扩展开发？🤔

tschema的核心功能已经非常强大，但实际项目中我们经常需要特定的验证规则或类型转换逻辑。例如，你可能需要验证邮箱格式、手机号格式，或者将字符串转换为特定格式的日期对象。通过扩展开发，你可以为tschema添加这些自定义功能，让类型系统更好地服务于你的业务需求。

tschema扩展开发基础 📚

理解tschema的核心结构

tschema的核心代码位于mod.ts文件中，它定义了所有的类型和验证器。要创建自定义扩展，首先需要理解tschema的内部工作机制。

tschema使用TypeScript的泛型和条件类型来推断类型信息。例如，Infer<T>类型用于从tschema类型定义中提取TypeScript类型：

// 从mod.ts中提取的类型推断逻辑 export type Infer<T> = T extends _null ? null : T extends _boolean ? boolean : T extends _string<infer E> ? E : T extends _number<infer E> | _integer<infer E> ? E // ... 更多类型推断

创建自定义验证器

让我们创建一个简单的邮箱验证器作为示例：

import * as t from 'tschema'; // 自定义邮箱验证器 function email(options?: t.Annotations & { pattern?: string }) { return { ...options, type: 'string' as const, format: 'email', pattern: options?.pattern || '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$' }; } // 使用自定义验证器 const UserSchema = t.object({ name: t.string(), email: email({ description: '用户邮箱地址', pattern: '^[\\w.%+-]+@[\\w.-]+\\.[a-zA-Z]{2,}$' }), age: t.integer({ minimum: 0 }) }); // 自动推断TypeScript类型 type User = t.Infer<typeof UserSchema>; // -> { name: string; email: string; age: number }

实现类型转换器

类型转换器可以将一种类型转换为另一种类型。例如，将字符串转换为日期对象：

// 自定义日期转换器 function dateString(options?: t.Annotations) { const base = t.string({ ...options, pattern: '^\\d{4}-\\d{2}-\\d{2}$' }); // 添加自定义元数据 return { ...base, _custom: { transform: (value: string) => new Date(value), validate: (value: string) => !isNaN(Date.parse(value)) } }; } // 使用日期转换器 const EventSchema = t.object({ title: t.string(), date: dateString({ description: '事件日期 (YYYY-MM-DD)' }) });

高级扩展技巧 🔧

组合验证器

你可以组合多个验证器创建更复杂的验证规则：

// 创建密码验证器（组合多个规则） function password(options?: t.Annotations & { minLength?: number; requireUppercase?: boolean; requireNumbers?: boolean; }) { const { minLength = 8, requireUppercase = true, requireNumbers = true, ...rest } = options || {}; let pattern = ''; if (requireUppercase) pattern += '(?=.*[A-Z])'; if (requireNumbers) pattern += '(?=.*\\d)'; pattern += `.{${minLength},}`; return t.string({ ...rest, minLength, pattern: `^${pattern}$`, description: `密码至少${minLength}位${requireUppercase ? '，包含大写字母' : ''}${requireNumbers ? '和数字' : ''}` }); }

创建条件验证器

有时候我们需要根据其他字段的值来验证当前字段：

// 条件验证器示例 function conditionalField( condition: (data: any) => boolean, validator: t.Type ) { return { ...validator, _conditional: { condition, validator } }; } // 使用条件验证 const OrderSchema = t.object({ paymentMethod: t.enum(['credit_card', 'paypal', 'bank_transfer']), cardNumber: conditionalField( (data) => data.paymentMethod === 'credit_card', t.string({ pattern: '^\\d{16}$' }) ) });

实战案例：自定义验证器库 🏗️

让我们创建一个完整的自定义验证器库：

// custom-validators.ts import * as t from 'tschema'; // 手机号验证器（中国格式） export function chinesePhone(options?: t.Annotations) { return t.string({ ...options, pattern: '^1[3-9]\\d{9}$', description: '中国手机号 (11位数字，以1开头)' }); } // 身份证验证器 export function chineseIDCard(options?: t.Annotations) { return t.string({ ...options, pattern: '^[1-9]\\d{5}(18|19|20)\\d{2}((0[1-9])|(1[0-2]))(([0-2][1-9])|10|20|30|31)\\d{3}[0-9Xx]$', description: '中国居民身份证号码' }); } // URL路径验证器 export function urlPath(options?: t.Annotations) { return t.string({ ...options, pattern: '^/[a-zA-Z0-9_\\-\\./]*$', description: 'URL路径 (以/开头)' }); } // 金额验证器（保留两位小数） export function money(options?: t.Annotations & { min?: number; max?: number }) { const { min, max, ...rest } = options || {}; return t.number({ ...rest, minimum: min, maximum: max, multipleOf: 0.01, description: `金额${min !== undefined ? ` (最小${min})` : ''}${max !== undefined ? ` (最大${max})` : ''}` }); }

测试你的扩展 🔍

创建扩展后，务必进行充分的测试：

// test-custom-validators.ts import { chinesePhone, chineseIDCard } from './custom-validators.ts'; import * as t from 'tschema'; const UserSchema = t.object({ name: t.string(), phone: chinesePhone(), idCard: chineseIDCard() }); // 测试有效数据 const validUser = { name: '张三', phone: '13800138000', idCard: '110101199001011234' }; // 测试无效数据 const invalidUser = { name: '李四', phone: '12345678901', // 无效手机号 idCard: '123456789012345678' // 无效身份证 };