阅读class-validator文档

isyangli_blog

已于 2024-03-13 10:02:34 修改

阅读量968

点赞数 15

文章标签：前端 javascript 开发语言

于 2024-03-13 09:13:25 首次发布

本文链接：https://blog.csdn.net/qq_43457850/article/details/136669845

版权

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是否不在不允许的值数组中。

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)`	检查所有数组的值是否唯一。对象的比较是基于引用的。可选函数可以指定用于比较的返回值。