@gitlon/validate

常用表单与业务校验函数。全部函数为独立命名导出，统一返回 ValidateResult 结果对象，失败时携带对应文案。

安装

pnpm add @gitlon/validate

也可安装聚合包：

pnpm add gitlon

导入

直接使用子包：

import {
  isBankCard,
  isChinese,
  isDate,
  isEmail,
  isEmpty,
  isEnglish,
  isIdCard,
  isInteger,
  isNumber,
  isPassword,
  isPhone,
  isPositiveNumber,
  isSocialCreditCode,
  isUrl,
} from '@gitlon/validate'

通过主包使用：

import { isEmail, isPassword, isPhone } from 'gitlon'

返回值

所有校验函数签名一致，入参为 unknown，返回 ValidateResult：

interface ValidateResult {
  success: boolean
  message: string
}

校验通过：

isEmail('[email protected]')
// { success: true, message: '' }

校验失败：

isEmail('user@example')
// { success: false, message: '邮箱格式不正确' }

规则：

• success 表示校验是否通过，message 在校验通过时为空字符串。
• 失败文案固定，可直接回填表单错误提示，无需在业务层再映射。
• 非法输入、空值、类型不符均返回失败对象，不抛异常。
• 需要布尔结果时取 success，例如 if (isEmail(value).success)。

下文示例中的注释统一简写为 // 通过 与 // 失败：文案。

API 总览

| 函数 | 校验内容 | | --- | --- | | isEmpty | 非空：空值、空白字符串、空数组、无可枚举属性对象均不通过 | | isNumber | 有限数字或可转换为有限数字的值 | | isInteger | 整数或整数字符串 | | isPositiveNumber | 大于 0 的数字或数字字符串 | | isEmail | 常用邮箱格式 | | isPhone | 中国大陆 11 位手机号 | | isUrl | 绝对 HTTP/HTTPS URL | | isIdCard | 中国大陆 18 位身份证格式及校验码 | | isBankCard | 12～19 位银行卡号及 Luhn 校验码 | | isSocialCreditCode | 18 位统一社会信用代码，数字与大写字母且排除 I、O、Z、S、V | | isDate | JavaScript 可解析日期 | | isChinese | 仅连续中文字符 | | isEnglish | 仅连续英文字母 | | isPassword | 可配置长度和字符要求的密码 |

空值

isEmpty(null)       // 失败：不能为空
isEmpty(undefined)  // 失败：不能为空
isEmpty('')         // 失败：不能为空
isEmpty('   ')      // 失败：不能为空
isEmpty([])         // 失败：不能为空
isEmpty({})         // 失败：不能为空

isEmpty(0)          // 通过
isEmpty(false)      // 通过
isEmpty([0])        // 通过
isEmpty({ id: 1 })  // 通过

function isEmpty(value: unknown): ValidateResult

规则：

• 字符串先执行 trim()，再判断是否为空。
• 数组按 length 判断。
• 对象按自身可枚举属性数量判断。
• Date、Map、Set 等没有自身可枚举属性的对象会被判定为空；该函数主要面向字符串、数组和普通对象。
• success 表示「不为空」，可直接用于必填校验；空值以外的任何合法取值均通过。

数字

isNumber(12)        // 通过
isNumber(-12.5)     // 通过
isNumber('12.5')    // 通过
isNumber('1e3')     // 通过

isNumber('')        // 失败：必须是数字
isNumber('   ')     // 失败：必须是数字
isNumber('12px')    // 失败：必须是数字
isNumber(NaN)       // 失败：必须是数字
isNumber(Infinity)  // 失败：必须是数字

function isNumber(value: unknown): ValidateResult
function isInteger(value: unknown): ValidateResult
function isPositiveNumber(value: unknown): ValidateResult

整数和正数示例：

isInteger(12)       // 通过
isInteger('12')     // 通过
isInteger(12.5)     // 失败：必须是整数

isPositiveNumber(1)    // 通过
isPositiveNumber('1')  // 通过
isPositiveNumber(0)    // 失败：必须是大于 0 的数字
isPositiveNumber(-1)   // 失败：必须是大于 0 的数字

isPositiveNumber 使用严格大于 0 的规则。

邮箱

isEmail('[email protected]') // 通过
isEmail('[email protected]') // 通过

isEmail('user@example')     // 失败：邮箱格式不正确
isEmail('@example.com')     // 失败：邮箱格式不正确

function isEmail(value: unknown): ValidateResult

用于常见表单邮箱格式判断，不追求覆盖完整 RFC 邮箱语法。校验不通过时统一返回 邮箱格式不正确。

手机号

isPhone('13812345678')   // 通过
isPhone('19812345678')   // 通过

isPhone('138 1234 5678') // 失败：手机号格式不正确
isPhone('12812345678')   // 失败：手机号格式不正确

function isPhone(value: unknown): ValidateResult

只接受未经分隔的中国大陆 11 位手机号，规则为 1[3-9]xxxxxxxxx。如需先清理和分组显示，使用 @gitlon/format 的 formatPhone。

URL

isUrl('https://example.com')      // 通过
isUrl('http://localhost:3000/a')  // 通过

isUrl('ftp://example.com')        // 失败：URL 必须使用 http 或 https 协议
isUrl('/users/1')                 // 失败：URL 格式不正确
isUrl('example.com')              // 失败：URL 格式不正确

function isUrl(value: unknown): ValidateResult

只接受带 http:// 或 https:// 协议的绝对 URL。可被 URL 解析但协议不为 HTTP/HTTPS 时返回 URL 必须使用 http 或 https 协议，其余情况返回 URL 格式不正确。

身份证

isIdCard('11010519491231002X') // 通过
isIdCard('11010519491231002x') // 通过

isIdCard('110105194912310021') // 失败：身份证号校验码错误
isIdCard('110105491231002')    // 失败：身份证号格式不正确

function isIdCard(value: unknown): ValidateResult

校验：

• 18 位格式；
• 前 17 位为数字；
• 末位为数字或 X；
• 加权校验码。

不校验行政区划、出生日期是否真实存在，也不代表身份证真实有效。

银行卡

isBankCard('4111111111111111') // 通过
isBankCard('5555555555554444') // 通过

isBankCard('123456789012')     // 失败：银行卡号校验码错误
isBankCard('4111 1111 1111 1111') // 失败：银行卡号必须为 12～19 位数字

function isBankCard(value: unknown): ValidateResult

只接受 12～19 位纯数字，并执行 Luhn 校验。不识别发卡行，也不保证卡号真实存在。含空格或横线的展示值需先清理。

统一社会信用代码

isSocialCreditCode('91330100MA27X9Q42W') // 通过

isSocialCreditCode('91330100MA27X9Q42')  // 失败：统一社会信用代码必须为 18 位
isSocialCreditCode('91330100ma27x9q42w') // 失败：统一社会信用代码只能由数字和大写字母组成，且不含 I、O、Z、S、V
isSocialCreditCode('91330100MA27X9Q42I') // 失败：统一社会信用代码只能由数字和大写字母组成，且不含 I、O、Z、S、V

function isSocialCreditCode(value: unknown): ValidateResult

按顺序校验：

• 先校验位数，必须为 18 位，不足或超出均返回 统一社会信用代码必须为 18 位；
• 再校验字符集，只接受数字 0-9 与大写英文字母，且排除 I、O、Z、S、V。

不校验 GB 32100 规定的第 18 位校验码，也不校验登记管理部门、机构类别与行政区划是否真实存在；小写字母不会自动转换为大写，需在业务层预先处理。

日期

isDate('2026-09-15')          // 通过
isDate('2026-09-15T10:30:00') // 通过
isDate(new Date())            // 通过
isDate(Date.now())            // 通过

isDate('not-a-date')          // 失败：日期格式不正确
isDate(null)                  // 失败：日期格式不正确
isDate('')                    // 失败：日期格式不正确

function isDate(value: unknown): ValidateResult

字符串和数字交给原生 Date 解析。解析规则及结果可能受运行环境和时区影响；需要严格格式校验时，应在业务层明确格式后再判断。

中文与英文

isChinese('你好世界') // 通过
isChinese('你好 world') // 失败：只能包含中文字符
isChinese('中文123') // 失败：只能包含中文字符

isEnglish('Hello')    // 通过
isEnglish('hello world') // 失败：只能包含英文字母
isEnglish('hello123') // 失败：只能包含英文字母

function isChinese(value: unknown): ValidateResult
function isEnglish(value: unknown): ValidateResult

• isChinese 只接受 \u4e00～\u9fff 范围内的连续字符。
• isEnglish 只接受 A-Z、a-z 连续字母。
• 空格、数字和标点均不通过。

密码

默认要求 6～20 位，同时包含字母和数字：

isPassword('Gitlon123') // 通过
isPassword('123456')    // 失败：密码必须包含字母
isPassword('abcdef')    // 失败：密码必须包含数字
isPassword('abc')       // 失败：密码长度须为 6～20 位

自定义规则：

isPassword('Gitlon!123', {
  minLength: 8,
  maxLength: 30,
  requireLetter: true,
  requireNumber: true,
  requireSpecial: true,
})
// 通过

interface PasswordValidateOptions {
  minLength?: number
  maxLength?: number
  requireLetter?: boolean
  requireNumber?: boolean
  requireSpecial?: boolean
}

function isPassword(value: unknown, options?: PasswordValidateOptions): ValidateResult

| 选项 | 默认值 | 说明 | | --- | --- | --- | | minLength | 6 | 最小长度 | | maxLength | 20 | 最大长度 | | requireLetter | true | 至少包含一个英文字母 | | requireNumber | true | 至少包含一个数字 | | requireSpecial | false | 至少包含一个非字母、非数字字符 |

按长度、字母、数字、特殊字符的顺序依次判断，首个不满足的条件决定 message；入参不是字符串时返回 密码格式不正确。失败文案中的长度区间会跟随 minLength、maxLength 取值变化。

不限制特殊字符集合，也不检查弱密码、连续字符、泄露密码或业务账号信息。

类型导入

import type { PasswordValidateOptions, ValidateResult } from '@gitlon/validate'

使用聚合包时：

import type { PasswordValidateOptions, ValidateResult } from 'gitlon'

表单示例

import { isEmail, isEmpty, isPassword, isPhone } from '@gitlon/validate'

interface RegisterForm {
  email: string
  password: string
  phone: string
}

function validateRegister(form: RegisterForm): Record<string, string> {
  const errors: Record<string, string> = {}

  const required = isEmpty(form.email)
  if (!required.success) {
    errors.email = '请输入邮箱'
  } else {
    const format = isEmail(form.email)
    if (!format.success) errors.email = format.message
  }

  const phone = isPhone(form.phone)
  if (!phone.success) errors.phone = phone.message

  const password = isPassword(form.password)
  if (!password.success) errors.password = password.message

  return errors
}

校验函数只判断当前值是否符合格式并给出文案，不负责字段命名、异步请求、唯一性校验或真实性校验。