阅读class-validator文档

class-validatorg官方总结文档

允许使用基于 装饰器 和 非装饰器 的验证。在内部使用validator.js执行验证。类验证器可以在 浏览器 和node.js平台 上工作。

1.Usage

创建你的类，并在你想要验证的属性上放置一些验证装饰器:

// 引入 class-validator 库中的验证函数和装饰器
import {
  validate,
  validateOrReject,
  Contains,
  IsInt,
  Length,
  IsEmail,
  IsFQDN,
  IsDate,
  Min,
  Max,
} from 'class-validator';
​
// 定义一个名为 Post 的类，用于演示验证功能
export class Post {
  // 通过装饰器指定 title 属性的验证规则，长度必须在 10 到 20 之间
  @Length(10, 20)
  title: string;
​
  // 通过装饰器指定 text 属性的验证规则，必须包含字符串 'hello'
  @Contains('hello')
  text: string;
​
  // 通过装饰器指定 rating 属性的验证规则，必须是整数，且在 0 到 10 之间
  @IsInt()
  @Min(0)
  @Max(10)
  rating: number;
​
  // 通过装饰器指定 email 属性的验证规则，必须是有效的电子邮件地址
  @IsEmail()
  email: string;
​
  // 通过装饰器指定 site 属性的验证规则，必须是有效的完全限定域名（FQDN）
  @IsFQDN()
  site: string;
​
  // 通过装饰器指定 createDate 属性的验证规则，必须是有效的日期对象
  @IsDate()
  createDate: Date;
}
​
// 创建一个 Post 类的实例
let post = new Post();
post.title = 'Hello'; // 不符合长度规则，不应通过验证
post.text = 'this is a great post about hell world'; // 不包含 'hello'，不应通过验证
post.rating = 11; // 超出范围，不应通过验证
post.email = 'google.com'; // 不是有效的电子邮件地址，不应通过验证
post.site = 'googlecom'; // 不是有效的完全限定域名，不应通过验证
​
// 使用 validate 函数异步验证 post 对象，返回一个包含验证错误的数组
validate(post).then(errors => {
  // 如果存在验证错误，则输出错误信息
  if (errors.length > 0) {
    console.log('validation failed. errors: ', errors);
  } else {
    // 没有验证错误，输出验证成功信息
    console.log('validation succeed');
  }
});
​
// 使用 validateOrReject 函数异步验证 post 对象，返回一个 Promise
validateOrReject(post).catch(errors => {
  // 如果存在验证错误，则输出错误信息
  console.log('Promise rejected (validation failed). Errors: ', errors);
});
​
// 或者使用 async/await 语法进行异步验证，并捕获验证错误
async function validateOrRejectExample(input) {
  try {
    await validateOrReject(input);
  } catch (errors) {
    console.log('Caught promise rejection (validation failed). Errors: ', errors);
  }
}
​

2.通过选择

validate函数可选地 期望一个 ValidatorOptions对象 作为 第二个参数

// 定义了用于配置验证器行为的接口 ValidatorOptions
export interface ValidatorOptions {
  // 是否跳过缺失的属性，默认为 false
  skipMissingProperties?: boolean;
​
  // 是否启用白名单过滤，默认为 false
  whitelist?: boolean;
​
  // 是否禁止非白名单属性，默认为 false
  forbidNonWhitelisted?: boolean;
​
  // 可以指定要应用的验证组
  groups?: string[];
​
  // 是否忽略默认消息，默认为 false
  dismissDefaultMessages?: boolean;
​
  // 验证错误的配置
  validationError?: {
    // 是否在验证错误时返回目标对象，默认为 true
    target?: boolean;
    
    // 是否在验证错误时返回值，默认为 true
    value?: boolean;
  };
​
  // 是否禁止未知的值，默认为 false
  forbidUnknownValues?: boolean;
​
  // 是否在遇到第一个错误时停止验证，默认为 false
  stopAtFirstError?: boolean;
}
​

注意事项forbidUnknownValues默认为true，建议保持默认值。将其设置为false将导致未知对象通过验证!

3.Validation errors

validate方法返回一个ValidationError对象数组。每个ValidationError是:

// 表示验证失败时的错误信息对象
{
  // 未通过验证的目标对象
  target: Object;
​
  // 未通过验证的目标对象的属性名
  property: string;
​
  // 未通过验证的属性值
  value: any;
​
  // 包含验证失败的具体约束及错误消息
  constraints?: {
    [type: string]: string;
  };
​
  // 包含目标属性的所有嵌套验证错误信息
  children?: ValidationError[];
}
​

在本例中，当我们验证Post对象时，我们有这样一个ValidationError对象数组:

// 表示验证过程中发生的错误的数组
[{
    // 未通过验证的目标对象
    target: /* post object */,
​
    // 未通过验证的目标对象的属性名
    property: "title",
​
    // 未通过验证的属性值
    value: "Hello",
​
    // 包含验证失败的具体约束及错误消息
    constraints: {
        length: "$property must be longer than or equal to 10 characters"
    }
}, {
    // 未通过验证的目标对象
    target: /* post object */,
​
    // 未通过验证的目标对象的属性名
    property: "text",
​
    // 未通过验证的属性值
    value: "this is a great post about hell world",
​
    // 包含验证失败的具体约束及错误消息
    constraints: {
        contains: "text must contain a hello string"
    }
},
// and other errors
]
​

如果你不想在验证错误中暴露目标，在使用验证器时有一个特殊的选项:

validator.validate(post, { validationError: { target: false } });

当您通过http发送错误时，这尤其有用，并且您很可能不想公开整个目标对象。

Validation messages

您可以在装饰器选项中指定验证消息，该消息将在validate方法返回的ValidationError中返回(在此字段验证失败的情况下)。

import { MinLength, MaxLength } from 'class-validator';
​
export class Post {
  @MinLength(10, {
    message: 'Title is too short',
  })
  @MaxLength(50, {
    message: 'Title is too long',
  })
  title: string;
}

你可以在你的消息中使用一些特殊的令牌:

$value—正在验证的值

$property -要验证的对象属性的名称

$target -要验证的对象的类名

$constraint1， $constraint2，…$constraintN -由特定验证类型定义的约束

Example of usage:

// 引入 class-validator 库中的 MinLength 和 MaxLength 装饰器
import { MinLength, MaxLength } from 'class-validator';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 MinLength 装饰器来指定 title 属性的最小长度为 10
  @MinLength(10, {
    // 在验证失败时，可以使用 message 属性自定义错误消息
    // 这里的 $constraint1 将被替换为 "10"，$value 将被替换为实际提供的值
    message: 'Title is too short. Minimal length is $constraint1 characters, but actual is $value',
  })
  // 使用 MaxLength 装饰器来指定 title 属性的最大长度为 50
  @MaxLength(50, {
    // 在验证失败时，可以使用 message 属性自定义错误消息
    // 这里的 $constraint1 将被替换为 "50"，$value 将被替换为实际提供的值
    message: 'Title is too long. Maximal length is $constraint1 characters, but actual is $value',
  })
  // 定义了一个名为 title 的字符串属性
  title: string;
}
​

您还可以提供一个返回消息的函数。这允许你创建更细粒度的消息:

// 引入 class-validator 库中的 MinLength、MaxLength 和 ValidationArguments 类
import { MinLength, ValidationArguments } from 'class-validator';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 MinLength 装饰器来指定 title 属性的最小长度为 10
  @MinLength(10, {
    // 通过 message 属性传递一个函数，该函数在验证失败时会被调用
    message: (args: ValidationArguments) => {
      // 使用 ValidationArguments 对象中的 value 属性获取实际提供的值
      if (args.value.length === 1) {
        // 当实际值的长度为 1 时返回的错误消息
        return 'Too short, minimum length is 1 character';
      } else {
        // 当实际值的长度大于 1 时返回的错误消息，使用 args.constraints[0] 获取指定的最小长度
        return 'Too short, minimum length is ' + args.constraints[0] + ' characters';
      }
    },
  })
  // 定义了一个名为 title 的字符串属性
  title: string;
}
​

Message函数接受ValidationArguments，其中包含以下信息:

值—正在验证的值

约束——由特定验证类型定义的约束数组

targetName -要验证的对象的类名

对象-正在验证的对象

属性-要验证的对象属性的名称

Validating arrays

如果你的字段是一个数组，并且你想对数组中的每一项执行验证，你必须指定一个特殊的each: true装饰器选项。

// 引入 class-validator 库中的 MaxLength 装饰器
import { MaxLength } from 'class-validator';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 MaxLength 装饰器来限制 tags 属性中每个元素的最大长度为 20
  @MaxLength(20, {
    // 设置 each 选项为 true，表示要对数组中的每个元素分别进行长度验证
    each: true,
  })
  // 定义了一个名为 tags 的字符串数组属性
  tags: string[];
}
​

这将验证邮件中的每个项目。标记数组。

Validating sets

如果你的字段是一个集合，并且你想对集合中的每个项执行验证，你必须指定一个特殊的each: true装饰器选项:

import { MinLength, MaxLength } from 'class-validator';
​
export class Post {
  @MaxLength(20, {
    each: true,
  })
  tags: Set<string>;
}

这将验证邮件中的每个项目。标记集。

Validating maps

如果你的字段是一个映射，并且你想要对映射中的每个项执行验证，你必须指定一个特殊的each: true装饰器选项:

// 引入 class-validator 库中的 MaxLength 装饰器
import { MaxLength } from 'class-validator';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 MaxLength 装饰器来限制 tags 属性中每个键和值的字符串的最大长度为 20
  @MaxLength(20, {
    // 设置 each 选项为 true，表示要对 Map 中的每个键和值的字符串分别进行长度验证
    each: true,
  })
  // 定义了一个名为 tags 的 Map 属性，键和值都是字符串类型
  tags: Map<string, string>;
}

Validating nested objects

如果你的对象包含嵌套的对象，并且你想让验证器也执行它们的验证，那么你需要使用@ validatenest()装饰器:

// 引入 class-validator 库中的 ValidateNested 装饰器
import { ValidateNested } from 'class-validator';
​
// 引入 User 类，假设它是另一个定义好的类
import { User } from './User';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 ValidateNested 装饰器来指示对 user 属性进行嵌套验证
  @ValidateNested()
  // 定义了一个名为 user 的属性，类型为 User，假设 User 是另一个类的实例
  user: User;
}
​

请注意，嵌套对象必须是一个类的实例，否则@ validatenest将不知道哪个类是验证的目标。另请检查验证普通对象。它也适用于多维数组，如:

import { ValidateNested } from 'class-validator';
​
export class Plan2D {
  @ValidateNested()
  matrix: Point[][];
}

Validating promises

如果你的对象包含带有承诺返回值的属性，那么你需要使用@ValidatePromise()装饰器:

// 引入 class-validator 库中的 ValidatePromise 和 Min 装饰器
import { ValidatePromise, Min } from 'class-validator';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 Min 装饰器 来指示 userId 属性的最小值为 0
  @Min(0)
  // 使用 ValidatePromise 装饰器来指示 userId 属性是一个 Promise<number> 类型，并需要进行异步验证
  @ValidatePromise()
  // 定义了一个名为 userId 的属性，类型为 Promise<number>
  userId: Promise<number>;
}

它也可以很好地使用@ validatenest装饰器:

// 引入 class-validator 库中的 ValidateNested 和 ValidatePromise 装饰器
import { ValidateNested, ValidatePromise } from 'class-validator';
​
// 引入 User 类，假设它是另一个定义好的类
import { User } from './User';
​
// 定义了一个名为 Post 的类
export class Post {
  // 使用 ValidateNested 装饰器来指示对 user 属性进行嵌套验证
  @ValidateNested()
  // 使用 ValidatePromise 装饰器来指示 user 属性是一个 Promise<User> 类型，并需要进行异步验证
  @ValidatePromise()
  // 定义了一个名为 user 的属性，类型为 Promise<User>
  user: Promise<User>;
}

Inheriting Validation decorators(继承验证装饰器)

当你定义了一个继承自另一个子类的子类时，这个子类将自动继承父类的装饰器。如果一个属性在子类中被重新定义，类装饰器将从它自己的类和基类中应用于它。

Conditional validation

当提供的条件函数返回false时，可以使用条件验证装饰器(@ValidateIf)忽略属性上的验证器。条件函数接受被验证的对象，并且必须返回一个布尔值。

Whitelisting

即使您的对象是验证类的实例，它也可以包含未定义的附加属性。如果你不想在你的对象上有这样的属性，传递特殊的标志来验证方法:

将上下文传递给装饰器

可以将自定义对象传递给decorator，如果验证失败，可以在属性的ValidationError实例上访问该对象。

Validation decorators

1.Common validation decorators

Decorator	Description
Common validation decorators
@IsDefined(value: any)	检查value是否定义(!)==未定义，!== null)。这是唯一忽略skipMissingProperties选项的装饰器。
@IsOptional()	检查给定的值是否为空(=== null， === undefined)，如果是，则忽略该属性上的所有验证器。
@Equals(comparison: any)	检查value是否等于("===")比较。
@NotEquals(comparison: any)	检查value是否不等于("!==")比较。
@IsEmpty()	检查给定值是否为空(=== "，=== null， === undefined)。
@IsNotEmpty()	检查给定的值是否不为空(!== "， !== null， !== undefined)。
@IsIn(values: any[])	检查value是否在允许的值数组中。
@IsNotIn(values: any[])	检查value是否不在不允许的值数组中。

1

2.Type validation decorators

@IsBoolean()	Checks if a value is a boolean.
`@IsDate()	Checks if the value is a date.
@IsString()	Checks if the value is a string.
@IsNumber(options: IsNumberOptions)	Checks if the value is a number.
@IsInt()	Checks if the value is an integer number.
@IsArray()	Checks if the value is an array
@IsEnum(entity: object)	Checks if the value is a valid enum

3.Number validation decorators

Number validation decorators	deco
@IsDivisibleBy(num: number)	检查值是否能被另一个数整除
@IsPositive()	检查值是否为大于零的正数
@IsNegative()	检查值是否为小于零的负数
@Min(min: number)	检查给定的数字是否大于或等于给定的数字。
@Max(max: number)	检查给定的数字是否小于或等于给定的数字。

4.Date validation decorators

	deco
@MinDate(date: Date|(() => Date))	检查值是否为在指定日期之后的日期。
@MaxDate(date: Date|(() => Date))	检查值是否为在指定日期之前的日期。

5.String-type validation decorators

String-type validation decorators
@IsBooleanString()	检查字符串是否为布尔值(例如是“true”或“false”或“1”，“0”)。
@IsDateString()	@IsISO8601的别名
@IsNumberString(options?: IsNumericOptions)	检查字符串是否为数字。

6.String validation decorators

String validation decorators
@Contains(seed: string)	检查字符串是否包含种子
@NotContains(seed: string)	检查字符串是否不包含种子。
@IsAlpha()	检查字符串是否只包含字母(a-zA-Z)。
@IsAlphanumeric()	检查字符串是否只包含字母和数字。
@IsDecimal(options?: IsDecimalOptions)	检查字符串是否是有效的十进制值。默认的IsDecimalOptions是force_decimal=False, decimal_digits: '1，'， locale: 'en-US'
@IsAscii()	检查字符串是否只包含ASCII字符。
@IsBase32()	检查字符串是否为base32编码。
@IsBase58()	检查字符串是否为base58编码。
@IsBase64(options?: IsBase64Options)	检查字符串是否为base64编码。
@IsIBAN()	检查字符串是否为IBAN(国际银行帐号)。
@IsBIC()	检查字符串是否为BIC(银行识别码)或SWIFT代码。
@IsByteLength(min: number, max?: number)	检查字符串的长度(以字节为单位)是否在一个范围内。
@IsCreditCard()	检查字符串是否为信用卡。
@IsCurrency(options?: IsCurrencyOptions)	检查字符串是否是有效的货币金额。
@IsISO4217CurrencyCode()	检查字符串是否为ISO 4217货币代码。
@IsEthereumAddress()	使用基本正则表达式检查字符串是否为以太坊地址。不验证地址校验和。
@IsBtcAddress()	检查字符串是否是有效的BTC地址。
@IsDataURI()	检查字符串是否为数据uri格式。
@IsEmail(options?: IsEmailOptions)	检查字符串是否为电子邮件。
@IsFQDN(options?: IsFQDNOptions)	检查字符串是否是一个完全限定的域名(例如domain.com)。
@IsFullWidth()	检查字符串是否包含任何全宽字符。
@IsHalfWidth()	检查字符串是否包含任何半宽字符。
@IsVariableWidth()	检查字符串是否包含全宽和半宽字符的混合。
@IsHexColor()	检查字符串是否为十六进制颜色。
@IsHSL()	检查字符串是否是基于CSS颜色级别4规范的HSL颜色。
@IsRgbColor(options?: IsRgbOptions)	检查字符串的颜色是rgb还是rgba。
@IsIdentityCard(locale?: string)	检查字符串是否为有效的身份证代码。
@IsPassportNumber(countryCode?: string)	检查字符串是否为相对于特定国家代码的有效护照号码。
@IsPostalCode(locale?: string)	检查字符串是否为邮政编码。
@IsHexadecimal()	检查字符串是否为十六进制数。
@IsOctal()	检查字符串是否是八进制数。
@IsMACAddress(options?: IsMACAddressOptions)	检查字符串是否为MAC地址。
@IsIP(version?: "4"|"6")	检查字符串是否为IP(版本4或6)。
@IsPort()	检查字符串是否为有效端口号。
@IsISBN(version?: "10"|"13")	检查字符串是否为ISBN(版本10或13)。
@IsEAN()	检查字符串是否为EAN(欧洲商品编号)。
@IsISIN()	检查字符串是否为ISIN(股票/安全标识符)。
@IsISO8601(options?: IsISO8601Options)	检查字符串是否是有效的ISO 8601日期格式。使用strict = true选项对有效日期进行额外检查。
@IsJSON()	检查字符串是否是有效的JSON。
@IsJWT()	检查字符串是否是有效的JWT。
@IsObject()	检查对象是否有效对象(null，函数，数组将返回false)。
@IsNotEmptyObject()	检查对象是否为空。
@IsLowercase()	检查字符串是否为小写。
@IsLatLong()	检查字符串是否为lat, long格式的有效经纬度坐标。
@IsLatitude()	检查字符串或数字是否是有效的纬度坐标。
@IsLongitude()	检查字符串或数字是否是有效的经度坐标。
@IsMobilePhone(locale: string)	检查字符串是否为手机号码。
@IsISO31661Alpha2()	检查字符串是否是有效的ISO 3166-1 alpha-2官方指定的国家代码。
@IsISO31661Alpha3()	检查字符串是否是有效的ISO 3166-1 alpha-3官方指定的国家代码。
@IsLocale()	检查字符串是否为区域设置。
@IsPhoneNumber(region: string)	使用libphonenumber-js检查字符串是否是一个有效的电话号码。
@IsMongoId()	检查字符串是否是MongoDB ObjectId的有效十六进制编码表示。
@IsMultibyte()	检查字符串是否包含一个或多个多字节字符。
@IsNumberString(options?: IsNumericOptions)	检查字符串是否为数字。
@IsSurrogatePair()	检查字符串是否包含代理对字符。
@IsTaxId()	检查字符串是否是有效的税号。默认区域设置是en-US。
@IsUrl(options?: IsURLOptions)	检查字符串是否为URL。
@IsMagnetURI()	检查字符串是否为磁铁uri格式。
@IsUUID(version?: UUIDVersion)	检查字符串是否为UUID(版本3、4、5或全部)。
@IsFirebasePushId()	检查字符串是否是Firebase推送ID
@IsUppercase()	检查字符串是否为大写。
@Length(min: number, max?: number)	检查字符串的长度是否在某个范围内。
@MinLength(min: number)	检查字符串的长度是否不小于给定的数字。
@MaxLength(max: number)	检查字符串的长度是否不超过给定的数字。
@Matches(pattern: RegExp, modifiers?: string)	检查字符串是否与模式匹配。匹配(“foo”/ foo / i)或匹配(“foo”、“foo”,“我”)。
@IsMilitaryTime()	检查字符串是否是HH:MM格式的军事时间的有效表示形式。
@IsTimeZone()	检查字符串是否代表一个有效的IANA时区。
@IsHash(algorithm: string)	检查字符串是否为哈希。支持如下类型:md4、md5、sha1、sha256、sha384、sha512、ripemd128、ripemd160、tiger128、tiger160、tiger192、crc32、crc32b。
@IsMimeType()	检查字符串是否与有效的MIME类型格式匹配
@IsSemVer()	检查字符串是否是语义版本控制规范(SemVer)。
@IsISSN(options?: IsISSNOptions)	检查字符串是否为ISSN。
@IsISRC()	Checks if the string is a ISRC.
@IsRFC3339()	Checks if the string is a valid RFC 3339 date.
@IsStrongPassword(options?: IsStrongPasswordOptions)	Checks if the string is a strong password.

4.Array validation decorators

Array validation decorators
@ArrayContains(values: any[])	检查array是否包含给定值数组中的所有值。
@ArrayNotContains(values: any[])	检查数组是否不包含任何给定的值。
@ArrayNotEmpty()	检查给定的数组是否为空。
@ArrayMinSize(min: number)	检查数组的长度是否大于或等于指定的数字。
@ArrayMaxSize(max: number)	检查数组的长度是否小于或等于指定的数字。
@ArrayUnique(identifier?: (o) => any)	检查所有数组的值是否唯一。对象的比较是基于引用的。可选函数可以指定用于比较的返回值。

5.Object validation decorators

Object validation decorators
@IsInstance(value: any)	检查属性是否是传递值的实例。

6.Other decorators

Other decorators
@Allow()	当没有为该属性指定其他约束时，防止剥离该属性。