TypeBox 项目中如何实现邮箱格式验证

在 TypeBox 项目中，开发者经常需要验证用户输入的邮箱格式是否有效。本文将详细介绍如何在 TypeBox 中实现邮箱格式验证，并分享一些最佳实践。

为什么需要自定义格式验证

TypeBox 作为一个轻量级的类型验证库，默认不包含常见的字符串格式验证实现（如邮箱、URL等）。这种设计决策是为了保持核心库的轻量性，同时给予开发者最大的灵活性。因此，当我们需要验证邮箱格式时，必须自行注册相应的验证逻辑。

实现邮箱验证的完整方案

1. 注册邮箱格式验证器

首先需要通过 TypeBox 的 FormatRegistry 来注册邮箱验证逻辑：

import { FormatRegistry } from '@sinclair/typebox'

FormatRegistry.Set('email', value => {
  return /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i.test(value)
})

这个正则表达式能够验证大多数合法的邮箱地址格式。

2. 自定义错误消息处理

TypeBox 提供了自定义错误消息处理的机制，我们可以利用它来简化错误处理流程：

import { SetErrorFunction, DefaultErrorFunction } from '@sinclair/typebox/errors'

SetErrorFunction((parameter) => {
  return 'errorMessage' in parameter.schema
    ? parameter.schema.errorMessage
    : DefaultErrorFunction(parameter)
})

3. 定义包含邮箱验证的Schema

现在可以定义一个包含邮箱验证的表单Schema：

import { Type as T } from '@sinclair/typebox'

const ContactFormSchema = T.Object({
  name: T.String({ minLength: 2, errorMessage: "姓名必填" }),
  email: T.String({ format: "email", errorMessage: "邮箱格式无效" }),
  message: T.String({ minLength: 10, errorMessage: "消息内容太短" })
})

4. 执行验证

最后，执行验证并处理结果：

import { Value } from '@sinclair/typebox/value'

const errors = Array.from(Value.Errors(ContactFormSchema, { 
  name: '', 
  email: '无效邮箱', 
  message: '...' 
}))

验证结果示例

当验证失败时，返回的错误信息会包含我们预设的自定义错误消息：

[
  {
    "type": 52,
    "schema": { /* 省略 */ },
    "path": "/name",
    "value": "",
    "message": "姓名必填",
    "errors": []
  },
  {
    "type": 50,
    "schema": { /* 省略 */ },
    "path": "/email",
    "value": "无效邮箱",
    "message": "邮箱格式无效",
    "errors": []
  },
  {
    "type": 52,
    "schema": { /* 省略 */ },
    "path": "/message",
    "value": "...",
    "message": "消息内容太短",
    "errors": []
  }
]

扩展建议

1. 常用格式预定义：可以创建一个单独的文件存放各种常用格式验证器（如URL、日期时间等），方便项目复用。

2. 国际化支持：通过动态设置errorMessage，可以实现多语言错误提示。

3. 性能优化：对于高频使用的格式验证器，可以考虑使用更高效的正则表达式或验证算法。

通过以上方法，开发者可以在TypeBox项目中灵活地实现各种格式验证需求，包括但不限于邮箱验证。这种设计既保持了核心库的简洁性，又提供了足够的扩展能力来满足各种业务场景的需求。