1373 lines
34 KiB
Markdown
1373 lines
34 KiB
Markdown
> 随着时间的推移，可能部分内容无法与官方最新版本同步，请自行对比查看，我有空会更新
|
||
|
||
用于Typescript或ES6+的类验证，基于[validator.js](https://github.com/chriso/validator.js)
|
||
|
||
[手动验证方法列表](https://github.com/typestack/class-validator#manual-validation)和[验证装饰器列表](https://github.com/typestack/class-validator#validation-decorators)
|
||
|
||
```python
|
||
print("Hello, World!")
|
||
```
|
||
|
||
## class-validator中文文档
|
||
|
||
### 安装
|
||
|
||
```shell
|
||
npm install class-validator --save
|
||
```
|
||
|
||
#### 基本使用
|
||
|
||
创建一个`Post`作为演示,在每个属性上添加不同的验证[装饰器](https://test.3rcd.com/notes/decorator.html)尝试
|
||
|
||
```javascript
|
||
import {validate, validateOrReject, Contains, IsInt, Length, IsEmail, IsFQDN, IsDate, Min, Max} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@Length(10, 20)
|
||
title: string;
|
||
|
||
@Contains("hello")
|
||
text: string;
|
||
|
||
@IsInt()
|
||
@Min(0)
|
||
@Max(10)
|
||
rating: number;
|
||
|
||
@IsEmail()
|
||
email: string;
|
||
|
||
@IsFQDN()
|
||
site: string;
|
||
|
||
@IsDate()
|
||
createDate: Date;
|
||
|
||
}
|
||
|
||
let post = new Post();
|
||
post.title = "Hello"; // should not pass
|
||
post.text = "this is a great post about hell world"; // should not pass
|
||
post.rating = 11; // should not pass
|
||
post.email = "google.com"; // should not pass
|
||
post.site = "googlecom"; // should not pass
|
||
|
||
// 如果验证失败不会停止运行程序
|
||
validate(post).then(errors => {
|
||
if (errors.length > 0) {
|
||
console.log("validation failed. errors: ", errors);
|
||
} else {
|
||
console.log("validation succeed");
|
||
}
|
||
});
|
||
|
||
// 验证失败就停止运行程序
|
||
validateOrReject(post).catch(errors => {
|
||
console.log("Promise rejected (validation failed). Errors: ", errors);
|
||
});
|
||
// 或者
|
||
async function validateOrRejectExample(input) {
|
||
try {
|
||
await validateOrReject(input);
|
||
} catch (errors) {
|
||
console.log("Caught promise rejection (validation failed). Errors: ", errors)
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 选项
|
||
|
||
``validate``函数的第二个参数是一个选项对象，尽量设置`forbidNonWhitelisted`为`true`以避免unkown对象的输入验证
|
||
|
||
```javascript
|
||
export interface ValidatorOptions {
|
||
|
||
skipMissingProperties?: boolean;
|
||
whitelist?: boolean;
|
||
forbidNonWhitelisted?: boolean;
|
||
groups?: string[];
|
||
dismissDefaultMessages?: boolean;
|
||
validationError?: {
|
||
target?: boolean;
|
||
value?: boolean;
|
||
};
|
||
|
||
forbidUnknownValues?: boolean;
|
||
}
|
||
```
|
||
|
||
#### 验证错误
|
||
|
||
验证失败返回的错误数组是`ValidationError`类的对象的数组，格式如下
|
||
|
||
```javascript
|
||
{
|
||
target: Object; // Object that was validated.
|
||
property: string; // Object's property that haven't pass validation.
|
||
value: any; // Value that haven't pass a validation.
|
||
constraints?: { // Constraints that failed validation with error messages.
|
||
[type: string]: string;
|
||
};
|
||
children?: ValidationError[]; // Contains all nested validation errors of the property
|
||
}
|
||
```
|
||
|
||
返回的格式如下
|
||
|
||
```javascript
|
||
[{
|
||
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
|
||
]
|
||
```
|
||
|
||
在http响应中我们一般不想在错误中暴露`target`，那么就可以如下方式禁用它
|
||
|
||
```javascript
|
||
validator.validate(post, { validationError: { target: false } });
|
||
```
|
||
|
||
#### 验证消息
|
||
|
||
我们可以自定义在`ValidationError`对象中返回的错误消息
|
||
|
||
```javascript
|
||
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;
|
||
}
|
||
```
|
||
|
||
消息可以接受几个参数作为变量，用字符串混合的方式放入，比如`"$constraint1 characters"`
|
||
|
||
```javascript
|
||
import {MinLength, MaxLength} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@MinLength(10, { // here, $constraint1 will be replaced with "10", and $value with actual supplied value
|
||
message: "Title is too short. Minimal length is $constraint1 characters, but actual is $value"
|
||
})
|
||
@MaxLength(50, { // here, $constraint1 will be replaced with "50", and $value with actual supplied value
|
||
message: "Title is too long. Maximal length is $constraint1 characters, but actual is $value"
|
||
})
|
||
title: string;
|
||
}
|
||
```
|
||
|
||
能接受的变量如下
|
||
|
||
- `value` - 被验证的值
|
||
- `constraints` - 由指定验证类型定义的约束数组
|
||
- `targetName` - 验证对象的类的名称
|
||
- `object` - 被验证的对象
|
||
- `property` - 被验证的属性名
|
||
|
||
当然`message`还可以接受一个函数的返回值，这个函数的参数为`ValidationArguments`类的对象，而`ValidationArguments`类的属性就是上面的变量列表
|
||
|
||
```javascript
|
||
import {MinLength, MaxLength, ValidationArguments} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@MinLength(10, {
|
||
message: (args: ValidationArguments) => {
|
||
if (args.value.length === 1) {
|
||
return "Too short, minimum length is 1 character";
|
||
} else {
|
||
return "Too short, minimum length is " + args.constraints[0] + " characters";
|
||
}
|
||
}
|
||
})
|
||
title: string;
|
||
}
|
||
```
|
||
|
||
### 特殊类型
|
||
|
||
`class-validator`对一些经常使用的特殊类型有专门的处理方法
|
||
|
||
#### 集合类型
|
||
|
||
验证数组,`Sets`,`Map`等集合类型需要开启`each`选项
|
||
|
||
#### 验证数组
|
||
|
||
```javascript
|
||
import {MinLength, MaxLength} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@MaxLength(20, {
|
||
each: true
|
||
})
|
||
tags: string[];
|
||
}
|
||
```
|
||
|
||
#### 验证Sets
|
||
|
||
```javascript
|
||
import {MinLength, MaxLength} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@MaxLength(20, {
|
||
each: true
|
||
})
|
||
tags: Set<string>;
|
||
}
|
||
```
|
||
|
||
#### 验证Map
|
||
|
||
```javascript
|
||
import {MinLength, MaxLength} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@MaxLength(20, {
|
||
each: true
|
||
})
|
||
tags: Map<string, string>;
|
||
}
|
||
```
|
||
|
||
#### 嵌套对象
|
||
|
||
一个验证的类中的某些属性可能是类一个的对象，比如`Post`类的`user`属性为`User`类，则可以使用`@ValidateNested()`方式来同时验证`Post`和嵌入的`User`类
|
||
|
||
```javascript
|
||
import {ValidateNested} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@ValidateNested()
|
||
user: User;
|
||
|
||
}
|
||
```
|
||
|
||
#### Promise对象
|
||
|
||
如果待验证的属性是一个`Promise`对象，比如通过`await`关键字返回的值，则可以使用`@ValidatePromise()`
|
||
|
||
```javascript
|
||
import {ValidatePromise, Min} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@Min(0)
|
||
@ValidatePromise()
|
||
userId: Promise<number>;
|
||
|
||
}
|
||
```
|
||
|
||
`@ValidatePromise()`也可以和`@ValidateNested()`一起使用
|
||
|
||
```javascript
|
||
import {ValidateNested, ValidatePromise} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@ValidateNested()
|
||
@ValidatePromise()
|
||
user: Promise<User>;
|
||
|
||
}
|
||
```
|
||
|
||
### 高级主题
|
||
|
||
#### 子类验证
|
||
|
||
如果定义一个从另一个继承的子类时，子类将自动继承父级的装饰器。如果在后代类中重新定义了属性，则装饰器将从该类和基类中继承
|
||
|
||
```javascript
|
||
import {validate} from "class-validator";
|
||
|
||
class BaseContent {
|
||
|
||
@IsEmail()
|
||
email: string;
|
||
|
||
@IsString()
|
||
password: string;
|
||
}
|
||
|
||
class User extends BaseContent {
|
||
|
||
@MinLength(10)
|
||
@MaxLength(20)
|
||
name: string;
|
||
|
||
@Contains("hello")
|
||
welcome: string;
|
||
|
||
@MinLength(20)
|
||
password: string; /
|
||
}
|
||
|
||
let user = new User();
|
||
|
||
user.email = "invalid email"; // inherited property
|
||
user.password = "too short" // password wil be validated not only against IsString, but against MinLength as well
|
||
user.name = "not valid";
|
||
user.welcome = "helo";
|
||
|
||
validate(user).then(errors => {
|
||
// ...
|
||
}); // it will return errors for email, title and text properties
|
||
```
|
||
|
||
#### 条件验证
|
||
|
||
当某个属性需要满足一定条件验证时可以使用(`@ValidateIf`)装饰器
|
||
|
||
```javascript
|
||
import {ValidateIf, IsNotEmpty} from "class-validator";
|
||
|
||
export class Post {
|
||
otherProperty:string;
|
||
|
||
@ValidateIf(o => o.otherProperty === "value")
|
||
@IsNotEmpty()
|
||
example:string;
|
||
}
|
||
```
|
||
|
||
#### 白名单
|
||
|
||
一个被验证的类的对象可以定义在类中不存在的属性，在验证时不会产生错误。为了使只有添加了**验证装饰器**的属性才能被定义，你需要把`whitelist`设置为`true`，那么如果对象中定义一个类中不存在的属性就无法通过验证了。
|
||
|
||
```javascript
|
||
import {validate} from "class-validator";
|
||
// ...
|
||
validate(post, { whitelist: true });
|
||
```
|
||
|
||
开启白名单之后所有没有加上**验证装饰器**的属性被定义后都将无法通过验证，如果你想一些属性可以被定义但是又不想被验证，如果[条件验证](#条件验证)中的`otherProperty`属性，那么你需要在该属性上面添加一个`@Allow`装饰器
|
||
|
||
```javascript
|
||
/**
|
||
* title可以被定义
|
||
* nonWhitelistedProperty不能被定义，否则验证失败
|
||
*/
|
||
import {validate, Allow, Min} from "class-validator";
|
||
|
||
export class Post {
|
||
|
||
@Allow()
|
||
title: string;
|
||
|
||
@Min(0)
|
||
views: number;
|
||
|
||
nonWhitelistedProperty: number;
|
||
}
|
||
|
||
let post = new Post();
|
||
post.title = 'Hello world!';
|
||
post.views = 420;
|
||
|
||
post.nonWhitelistedProperty = 69;
|
||
// 额外属性不能被添加，否则验证失败
|
||
(post as any).anotherNonWhitelistedProperty = "something";
|
||
|
||
validate(post).then(errors => {
|
||
// post.nonWhitelistedProperty is not defined
|
||
// (post as any).anotherNonWhitelistedProperty is not defined
|
||
...
|
||
});
|
||
```
|
||
|
||
如果你想要所有没有添加**验证装饰器**的属性都无法定义，则可以设置`forbidNonWhitelisted`为`true`
|
||
|
||
> 这个一般不要设置，否则属性添加@Allow会都没用了
|
||
|
||
```javascript
|
||
import {validate} from "class-validator";
|
||
// ...
|
||
validate(post, { whitelist: true, forbidNonWhitelisted: true });
|
||
```
|
||
|
||
#### 添加上下文
|
||
|
||
你可以在验证装饰其中添加一个自定义的上下文对象，此对象在验证失败时被`ValidationError`的实例获取
|
||
|
||
```javascript
|
||
import { validate } from 'class-validator';
|
||
|
||
class MyClass {
|
||
@MinLength(32, {
|
||
message: "EIC code must be at least 32 characters",
|
||
context: {
|
||
errorCode: 1003,
|
||
developerNote: "The validated string must contain 32 or more characters."
|
||
}
|
||
})
|
||
eicCode: string;
|
||
}
|
||
|
||
const model = new MyClass();
|
||
|
||
validate(model).then(errors => {
|
||
//errors[0].contexts['minLength'].errorCode === 1003
|
||
});
|
||
```
|
||
|
||
#### 跳过缺失属性
|
||
|
||
有时候你需要跳过一些对象中没有设置的属性，比如更新数据模型时，与创建模型不同的是你只会更新部分值，那么这时候你就需要设置`skipMissingProperties`为`true`，当然可能一部分属性是你不想被跳过验证的，那么需要在这些属性上加上`@IsDefined()`装饰器，加了`@IsDefined()`装饰器的属性会忽略`skipMissingProperties`而必定被验证
|
||
|
||
```javascript
|
||
import {validate} from "class-validator";
|
||
// ...
|
||
validate(post, { skipMissingProperties: true });
|
||
```
|
||
|
||
#### 验证组
|
||
|
||
```javascript
|
||
import {validate, Min, Length} from "class-validator";
|
||
|
||
export class User {
|
||
|
||
@Min(12, {
|
||
groups: ["registration"]
|
||
})
|
||
age: number;
|
||
|
||
@Length(2, 20, {
|
||
groups: ["registration", "admin"]
|
||
})
|
||
name: string;
|
||
}
|
||
|
||
let user = new User();
|
||
user.age = 10;
|
||
user.name = "Alex";
|
||
|
||
validate(user, {
|
||
groups: ["registration"]
|
||
}); // 无法通过验证
|
||
|
||
validate(user, {
|
||
groups: ["admin"]
|
||
}); // 可以通过验证
|
||
|
||
validate(user, {
|
||
groups: ["registration", "admin"]
|
||
}); // 无法通过验证
|
||
|
||
validate(user, {
|
||
groups: undefined // 默认模式
|
||
}); // 无法通过验证，因为没有指定group则所有属性都将被验证
|
||
|
||
validate(user, {
|
||
groups: []
|
||
}); // 无法通过验证 (与'groups: undefined'相同)
|
||
```
|
||
|
||
在验证中还有一个`always: true`选项，如果添加了此选项，无论验证时设定的是哪种模式的`groups`，都将被验证
|
||
|
||
#### 使用服务容器
|
||
|
||
你可以使用服务容器来加载验证器通过依赖注入的方式使用。以下如何将其与[typedi](https://github.com/pleerock/typedi)集成的示例：
|
||
|
||
```javascript
|
||
import {Container} from "typedi";
|
||
import {useContainer, Validator} from "class-validator";
|
||
|
||
// do this somewhere in the global application level:
|
||
useContainer(Container);
|
||
let validator = Container.get(Validator);
|
||
|
||
// now everywhere you can inject Validator class which will go from the container
|
||
// also you can inject classes using constructor injection into your custom ValidatorConstraint-s
|
||
```
|
||
|
||
#### 非装饰器验证
|
||
|
||
如果你的运行环境不支持装饰器请看[这里](https://github.com/typestack/class-validator#defining-validation-schema-without-decorators)
|
||
|
||
#### 验证普通对象
|
||
|
||
> Nest.js中使用的验证管道就是class-validator+class-transformer结合的方式
|
||
|
||
由于装饰器的性质，必须使用`new class()`语法实例化待验证的对象。如果你使用了class-validator装饰器定义了类，并且想要验证普通的JS对象（文本对象或JSON.parse返回），则需要将其转换为类实例
|
||
（例如，使用[class-transformer](https://github.com/pleerock/class-transformer)或仅使用[class-transformer-validator](https://github.com/19majkel94/class-transformer-validator)扩展可以为您完成此任务。
|
||
|
||
### 自定义验证
|
||
|
||
#### 自定义规则类
|
||
|
||
你可以创建一个自定义的验证规则的类，并在规则类上添加`@ValidatorConstraint`装饰器。 还可以设置验证约束名称(`name`选项)-该名称将在`ValidationError`中用作“error type”。 如果您不提供约束名称，它将自动生成。
|
||
|
||
规则类必须实现`ValidatorConstraintInterface`接口及`validate`方法，该接口定义了验证逻辑。 如果验证成功，则方法返回`true`，否则返回`false`。 自定义验证器可以是异步的，如果您想在执行一些异步操作后执行验证，只需在`validate`方法中返回带有布尔值的`promise`。
|
||
|
||
我们还可以定义了可选方法`defaultMessage`，它在属性上的装饰器未设置错误消息的情况下定义了默认错误消息。
|
||
|
||
首选我们创建一个`CustomTextLength`演示用的验证规则类
|
||
|
||
```javascript
|
||
import {ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments} from "class-validator";
|
||
|
||
@ValidatorConstraint({ name: "customText", async: false })
|
||
export class CustomTextLength implements ValidatorConstraintInterface {
|
||
|
||
validate(text: string, args: ValidationArguments) {
|
||
return text.length > 1 && text.length < 10; // 对于异步验证，您必须在此处返回Promise<boolean>
|
||
}
|
||
|
||
defaultMessage(args: ValidationArguments) { // 如果验证失败，您可以在此处提供默认错误消息
|
||
return "Text ($value) is too short or too long!";
|
||
}
|
||
|
||
}
|
||
```
|
||
|
||
定义好规则后我们就可以在类中使用了
|
||
|
||
```javascript
|
||
import {Validate} from "class-validator";
|
||
import {CustomTextLength} from "./CustomTextLength";
|
||
|
||
class Post {
|
||
|
||
@Validate(CustomTextLength, {
|
||
message: "Title is too short or long!"
|
||
})
|
||
title: string;
|
||
|
||
}
|
||
|
||
|
||
validate(post).then(errors => {
|
||
// ...
|
||
});
|
||
```
|
||
|
||
你也可以将自定义的约束传入规则类，并通过约束来设定验证的条件
|
||
|
||
```javascript
|
||
import {Validate} from "class-validator";
|
||
import {CustomTextLength} from "./CustomTextLength";
|
||
|
||
import {ValidationArguments, ValidatorConstraint, ValidatorConstraintInterface} from "class-validator";
|
||
|
||
@ValidatorConstraint()
|
||
class CustomTextLength implements ValidatorConstraintInterface {
|
||
|
||
validate(text: string, validationArguments: ValidationArguments) {
|
||
return text.length > validationArguments.constraints[0] && text.length < validationArguments.constraints[1];
|
||
}
|
||
|
||
}
|
||
|
||
class Post {
|
||
|
||
@Validate(CustomTextLength, [3, 20], {
|
||
message: "Wrong post title"
|
||
})
|
||
title: string;
|
||
|
||
}
|
||
```
|
||
|
||
#### 自定义装饰器
|
||
|
||
创建自定义装饰器的方法类似创建自定义规则类，只是使用装饰器而已
|
||
|
||
> 装饰器的详细使用请看我[这篇文章](https://test.3rcd.com/notes/decorator.html)
|
||
|
||
```javascript
|
||
import {registerDecorator, ValidationOptions, ValidationArguments} from "class-validator";
|
||
|
||
function IsLongerThan(property: string, validationOptions?: ValidationOptions) {
|
||
return function (object: Object, propertyName: string) {
|
||
registerDecorator({
|
||
name: "isLongerThan",
|
||
target: object.constructor,
|
||
propertyName: propertyName,
|
||
constraints: [property],
|
||
options: validationOptions,
|
||
validator: {
|
||
validate(value: any, args: ValidationArguments) {
|
||
const [relatedPropertyName] = args.constraints;
|
||
const relatedValue = (args.object as any)[relatedPropertyName];
|
||
return typeof value === "string" &&
|
||
typeof relatedValue === "string" &&
|
||
value.length > relatedValue.length; // you can return a Promise<boolean> here as well, if you want to make async validation
|
||
}
|
||
}
|
||
});
|
||
};
|
||
}
|
||
|
||
export class Post {
|
||
|
||
title: string;
|
||
|
||
@IsLongerThan("title", {
|
||
/* you can also use additional validation options, like "groups" in your custom validation decorators. "each" is not supported */
|
||
message: "Text must be longer than the title"
|
||
})
|
||
text: string;
|
||
|
||
}
|
||
```
|
||
|
||
在自定义装饰器上仍然可以使用`ValidationConstraint`装饰器。我们在创建一个`IsUserAlreadyExist`验证装饰器演示
|
||
|
||
```javascript
|
||
import {registerDecorator, ValidationOptions, ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments} from "class-validator";
|
||
|
||
@ValidatorConstraint({ async: true })
|
||
class IsUserAlreadyExistConstraint implements ValidatorConstraintInterface {
|
||
|
||
validate(userName: any, args: ValidationArguments) {
|
||
return UserRepository.findOneByName(userName).then(user => {
|
||
if (user) return false;
|
||
return true;
|
||
});
|
||
}
|
||
|
||
}
|
||
|
||
function IsUserAlreadyExist(validationOptions?: ValidationOptions) {
|
||
return function (object: Object, propertyName: string) {
|
||
registerDecorator({
|
||
target: object.constructor,
|
||
propertyName: propertyName,
|
||
options: validationOptions,
|
||
constraints: [],
|
||
validator: IsUserAlreadyExistConstraint
|
||
});
|
||
};
|
||
}
|
||
|
||
class User {
|
||
|
||
@IsUserAlreadyExist({
|
||
message: "User $value already exists. Choose another name."
|
||
})
|
||
name: string;
|
||
|
||
}
|
||
```
|
||
|
||
#### 同步验证
|
||
|
||
如果只是想简单的进行同步验证，可以使用`validateSync`代替`validate`。不过需要注意的是`validateSync`会忽略所有的异步验证。
|
||
|
||
## class-transfomer中文文档
|
||
|
||
类转换器的作用是将普通的javascript对象转换成类对象。我们通过api端点或者json文件访问所得的是普通的json文本，一般我们通过`JSON.parse`把其转换成普通的javascript对象，但是有时候我们想让它变成一个类的对象而不是普通的javascript对象。比如用`class-validator`来验证从后端api获取的json字符串时，我们就需要自动把json转为待验证类的对象而不是一个js对象。
|
||
|
||
例如我们现在可以读取远程api的一个`users.json`的内容如下
|
||
|
||
```json
|
||
[{
|
||
"id": 1,
|
||
"firstName": "Johny",
|
||
"lastName": "Cage",
|
||
"age": 27
|
||
},
|
||
{
|
||
"id": 2,
|
||
"firstName": "Ismoil",
|
||
"lastName": "Somoni",
|
||
"age": 50
|
||
},
|
||
{
|
||
"id": 3,
|
||
"firstName": "Luke",
|
||
"lastName": "Dacascos",
|
||
"age": 12
|
||
}]
|
||
```
|
||
|
||
我们有一个`User`类
|
||
|
||
```javascript
|
||
export class User {
|
||
id: number;
|
||
firstName: string;
|
||
lastName: string;
|
||
age: number;
|
||
|
||
getName() {
|
||
return this.firstName + " " + this.lastName;
|
||
}
|
||
|
||
isAdult() {
|
||
return this.age > 36 && this.age < 60;
|
||
}
|
||
}
|
||
```
|
||
|
||
然后你想通过`user.json`来获取`User`的对象数组
|
||
|
||
```javascript
|
||
fetch("users.json").then((users: User[]) => {
|
||
// you can use users here, and type hinting also will be available to you,
|
||
// but users are not actually instances of User class
|
||
// this means that you can't use methods of User class
|
||
});
|
||
```
|
||
|
||
现在你可以获取`users[0].firstname`但是由于你获取的是普通的js对象而非`User`类的对象，所以你无法调用`users[0].getName()`方法，而**class-transformer**就是为了把普通的js对象按你的需求转换成类对象而生的。
|
||
|
||
你只要像下面这样就可以创建真正的`User[]`对象数组了
|
||
|
||
```javascript
|
||
fetch("users.json").then((users: Object[]) => {
|
||
const realUsers = plainToClass(User, users);
|
||
// now each user in realUsers is instance of User class
|
||
});
|
||
```
|
||
|
||
### 安装
|
||
|
||
1. 安装class-transformer:
|
||
`npm install class-transformer --save`
|
||
|
||
2. 安装`reflect-metadata`
|
||
|
||
> reflect-metadata是必须的，具体使用请看[这篇博文](./2022-06-23-ts-decorator.md)
|
||
|
||
安装后在`app.ts`这种顶层文件你需要`import "reflect-metadata";`
|
||
|
||
### 基础方法
|
||
|
||
#### plainToClass
|
||
|
||
普通对象转换为类对象
|
||
|
||
```javascript
|
||
import {plainToClass} from "class-transformer";
|
||
|
||
let users = plainToClass(User, userJson); // to convert user plain object a single user. also supports arrays
|
||
```
|
||
|
||
#### plainToClassFromExist
|
||
|
||
普通对象合并已经创建的类实例
|
||
|
||
```javascript
|
||
const defaultUser = new User();
|
||
defaultUser.role = 'user';
|
||
|
||
let mixedUser = plainToClassFromExist(defaultUser, user); // mixed user should have the value role = user when no value is set otherwise.
|
||
```
|
||
|
||
#### classToPlain
|
||
|
||
类实例转换为普通对象
|
||
|
||
> 转换后可以使用`JSON.stringify`再转成普通的json文本
|
||
|
||
```javascript
|
||
import {classToPlain} from "class-transformer";
|
||
let photo = classToPlain(photo);
|
||
```
|
||
|
||
#### classToClass
|
||
|
||
克隆类实例
|
||
|
||
```javascript
|
||
import {classToClass} from "class-transformer";
|
||
let photo = classToClass(photo);
|
||
```
|
||
|
||
可以使用`ignoreDecorators`选项去除所有原实例中的装饰器
|
||
|
||
#### serialize
|
||
|
||
直接把类实例转换为json文本,是不是数组都可以转换
|
||
|
||
```javascript
|
||
import {serialize} from "class-transformer";
|
||
let photo = serialize(photo);
|
||
```
|
||
|
||
#### deserialize 和 deserializeArray
|
||
|
||
直接把json文本转换为类对象
|
||
|
||
```javascript
|
||
import {deserialize} from "class-transformer";
|
||
let photo = deserialize(Photo, photo);
|
||
```
|
||
|
||
如果json文本是个对象数组请使用`deserializeArray`方法
|
||
|
||
```javascript
|
||
import {deserializeArray} from "class-transformer";
|
||
let photos = deserializeArray(Photo, photos);
|
||
```
|
||
|
||
#### 强制类型安全
|
||
|
||
`plainToClass`会把所有的被转换对象的属性全部类实例的属性，即时类中并不存在某些属性
|
||
|
||
```javascript
|
||
import {plainToClass} from "class-transformer";
|
||
|
||
class User {
|
||
id: number
|
||
firstName: string
|
||
lastName: string
|
||
}
|
||
|
||
const fromPlainUser = {
|
||
unkownProp: 'hello there',
|
||
firstName: 'Umed',
|
||
lastName: 'Khudoiberdiev',
|
||
}
|
||
|
||
console.log(plainToClass(User, fromPlainUser))
|
||
|
||
// User {
|
||
// unkownProp: 'hello there',
|
||
// firstName: 'Umed',
|
||
// lastName: 'Khudoiberdiev',
|
||
// }
|
||
```
|
||
|
||
你可以使用`excludeExtraneousValues`选项结合`Expose`装饰器来指定需要公开的属性
|
||
|
||
```javascript
|
||
import {Expose, plainToClass} from "class-transformer";
|
||
|
||
class User {
|
||
@Expose() id: number;
|
||
@Expose() firstName: string;
|
||
@Expose() lastName: string;
|
||
}
|
||
|
||
const fromPlainUser = {
|
||
unkownProp: 'hello there',
|
||
firstName: 'Umed',
|
||
lastName: 'Khudoiberdiev',
|
||
}
|
||
|
||
console.log(plainToClass(User, fromPlainUser, { excludeExtraneousValues: true }))
|
||
|
||
// User {
|
||
// id: undefined,
|
||
// firstName: 'Umed',
|
||
// lastName: 'Khudoiberdiev'
|
||
// }
|
||
```
|
||
|
||
### 子类型转换
|
||
|
||
#### 嵌套对象
|
||
|
||
由于现在Typescript对反射还没有非常好的支持，所以你需要使用`@Type`装饰器来隐式地指定属性所属的类
|
||
|
||
```javascript
|
||
import {Type, plainToClass} from "class-transformer";
|
||
|
||
export class Album {
|
||
|
||
id: number;
|
||
|
||
name: string;
|
||
|
||
@Type(() => Photo)
|
||
photos: Photo[];
|
||
}
|
||
|
||
export class Photo {
|
||
id: number;
|
||
filename: string;
|
||
}
|
||
|
||
let album = plainToClass(Album, albumJson);
|
||
// now album is Album object with Photo objects inside
|
||
```
|
||
|
||
#### 多类型选项
|
||
|
||
一个嵌套的子类型也可以匹配多个类型，这可以通过判断器实现。判断器需要指定一个` property`，而被转换js对象中的嵌套对象的也必须拥有与`property`相同的一个字段，并把值设置为需要转换的子类型的名称。判断器还需要指定所有的子类型值以及其名称，具体示例如下
|
||
|
||
```javascript
|
||
import {Type, plainToClass} from "class-transformer";
|
||
|
||
const albumJson = {
|
||
"id": 1,
|
||
"name": "foo",
|
||
"topPhoto": {
|
||
"id": 9,
|
||
"filename": "cool_wale.jpg",
|
||
"depth": 1245,
|
||
"__type": "underwater"
|
||
}
|
||
}
|
||
|
||
export abstract class Photo {
|
||
id: number;
|
||
filename: string;
|
||
}
|
||
|
||
export class Landscape extends Photo {
|
||
panorama: boolean;
|
||
}
|
||
|
||
export class Portrait extends Photo {
|
||
person: Person;
|
||
}
|
||
|
||
export class UnderWater extends Photo {
|
||
depth: number;
|
||
}
|
||
|
||
export class Album {
|
||
|
||
id: number;
|
||
name: string;
|
||
|
||
@Type(() => Photo, {
|
||
discriminator: {
|
||
property: "__type",
|
||
subTypes: [
|
||
{ value: Landscape, name: "landscape" },
|
||
{ value: Portrait, name: "portrait" },
|
||
{ value: UnderWater, name: "underwater" }
|
||
]
|
||
}
|
||
})
|
||
topPhoto: Landscape | Portrait | UnderWater;
|
||
|
||
}
|
||
|
||
let album = plainToClass(Album, albumJson);
|
||
// now album is Album object with a UnderWater object without `__type` property.
|
||
```
|
||
|
||
此外可以设置`keepDiscriminatorProperty: true`，这样可以把判断器的属性也包含在转换后的对象中
|
||
|
||
### 排除与公开
|
||
|
||
#### 公开方法的返回值
|
||
|
||
添加`@Expose`装饰器即可公开getter和方法的返回值
|
||
|
||
```javascript
|
||
import {Expose} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
id: number;
|
||
firstName: string;
|
||
lastName: string;
|
||
password: string;
|
||
|
||
@Expose()
|
||
get name() {
|
||
return this.firstName + " " + this.lastName;
|
||
}
|
||
|
||
@Expose()
|
||
getFullName() {
|
||
return this.firstName + " " + this.lastName;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 公开属性为不同名称
|
||
|
||
如果要使用其他名称公开某些属性，可以通过为`@Expose`装饰器指定`name`选项来实现：
|
||
|
||
```javascript
|
||
import {Expose} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
@Expose({ name: "uid" })
|
||
id: number;
|
||
|
||
firstName: string;
|
||
|
||
lastName: string;
|
||
|
||
@Expose({ name: "secretKey" })
|
||
password: string;
|
||
|
||
@Expose({ name: "fullName" })
|
||
getFullName() {
|
||
return this.firstName + " " + this.lastName;
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 跳过指定属性
|
||
|
||
有时您想在转换过程中跳过一些属性。这可以使用`@Exclude`装饰器完成：
|
||
|
||
```javascript
|
||
import {Exclude} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
id: number;
|
||
|
||
email: string;
|
||
|
||
@Exclude()
|
||
password: string;
|
||
}
|
||
```
|
||
|
||
现在，当您转换用户时，`password`属性将被跳过，并且不包含在转换结果中。
|
||
|
||
#### 根据操作决定跳过
|
||
|
||
我们可以通过`toClassOnly`或者`toPlainOnly`来控制一个属性在哪些操作中需要排除
|
||
|
||
```javascript
|
||
import {Exclude} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
id: number;
|
||
|
||
email: string;
|
||
|
||
@Exclude({ toPlainOnly: true })
|
||
password: string;
|
||
}
|
||
```
|
||
|
||
现在`password`属性将会在`classToPlain`操作中排除，相反的可以使用`toClassOnly`
|
||
|
||
#### 跳过类的所有属性
|
||
|
||
你可以通过在类上添加`@Exclude`装饰器并且在需要公开的属性上添加`@Expose`装饰器来只公开指定的属性
|
||
|
||
```javascript
|
||
import {Exclude, Expose} from "class-transformer";
|
||
|
||
@Exclude()
|
||
export class User {
|
||
|
||
@Expose()
|
||
id: number;
|
||
|
||
@Expose()
|
||
email: string;
|
||
|
||
password: string;
|
||
}
|
||
```
|
||
|
||
另外，您可以在转换期间设置排除策略：
|
||
|
||
```javascript
|
||
import {classToPlain} from "class-transformer";
|
||
let photo = classToPlain(photo, { strategy: "excludeAll" });
|
||
```
|
||
|
||
这时你不需要在添加`@Exclude`装饰器了
|
||
|
||
#### 跳过私有属性或某些前缀属性
|
||
|
||
我们可以排除公开具有指定前缀的属性以及私有属性
|
||
|
||
```javascript
|
||
import {Expose} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
id: number;
|
||
private _firstName: string;
|
||
private _lastName: string;
|
||
_password: string;
|
||
|
||
setName(firstName: string, lastName: string) {
|
||
this._firstName = firstName;
|
||
this._lastName = lastName;
|
||
}
|
||
|
||
@Expose()
|
||
get name() {
|
||
return this.firstName + " " + this.lastName;
|
||
}
|
||
|
||
}
|
||
|
||
const user = new User();
|
||
user.id = 1;
|
||
user.setName("Johny", "Cage");
|
||
user._password = 123;
|
||
|
||
const plainUser = classToPlain(user, { excludePrefixes: ["_"] });
|
||
// here plainUser will be equal to
|
||
// { id: 1, name: "Johny Cage" }
|
||
```
|
||
|
||
#### 使用组来控制排除的属性
|
||
|
||
```javascript
|
||
import {Exclude, Expose} from "class-transformer";
|
||
|
||
@Exclude()
|
||
export class User {
|
||
|
||
id: number;
|
||
|
||
name: string;
|
||
|
||
@Expose({ groups: ["user", "admin"] }) // this means that this data will be exposed only to users and admins
|
||
email: string;
|
||
|
||
@Expose({ groups: ["user"] }) // this means that this data will be exposed only to users
|
||
password: string;
|
||
}
|
||
|
||
let user1 = classToPlain(user, { groups: ["user"] }); // will contain id, name, email and password
|
||
let user2 = classToPlain(user, { groups: ["admin"] }); // will contain id, name and email
|
||
```
|
||
|
||
#### 使用版本范围来控制公开和排除的属性
|
||
|
||
如果要构建具有不同版本的API，则class-transformer具有非常有用的工具。您可以控制应在哪个版本中公开或排除模型的哪些属性。示例
|
||
|
||
```javascript
|
||
import {Exclude, Expose} from "class-transformer";
|
||
|
||
@Exclude()
|
||
export class User {
|
||
|
||
id: number;
|
||
|
||
name: string;
|
||
|
||
@Expose({ since: 0.7, until: 1 }) // this means that this property will be exposed for version starting from 0.7 until 1
|
||
email: string;
|
||
|
||
@Expose({ since: 2.1 }) // this means that this property will be exposed for version starting from 2.1
|
||
password: string;
|
||
}
|
||
|
||
let user1 = classToPlain(user, { version: 0.5 }); // will contain id and name
|
||
let user2 = classToPlain(user, { version: 0.7 }); // will contain id, name and email
|
||
let user3 = classToPlain(user, { version: 1 }); // will contain id and name
|
||
let user4 = classToPlain(user, { version: 2 }); // will contain id and name
|
||
let user5 = classToPlain(user, { version: 2.1 }); // will contain id, name nad password
|
||
```
|
||
|
||
### 特殊处理
|
||
|
||
#### 将日期字符串转换为Date对象
|
||
|
||
有时，您的JavaScript对象中有一个以字符串格式接收的Date。您想从中创建一个真正的javascript Date对象。您只需将Date对象传递给`@Type`装饰器即可完成此操作：
|
||
|
||
> 当从类对象反向转换为普通对象时registrationDate将会被转回为字符串
|
||
|
||
```javascript
|
||
import {Type} from "class-transformer";
|
||
|
||
export class User {
|
||
|
||
id: number;
|
||
|
||
email: string;
|
||
|
||
password: string;
|
||
|
||
@Type(() => Date)
|
||
registrationDate: Date;
|
||
}
|
||
```
|
||
|
||
当您想将值转换为`Number`, `String`, `Boolean` 类型时也是这样做
|
||
|
||
#### 数组处理
|
||
|
||
当你想转换数组时，你必须使用`@Type`装饰器指定数组项的类型也可以使用自定义的数组类型
|
||
|
||
`Set`和`Map`也是一样
|
||
|
||
```javascript
|
||
import {Type} from "class-transformer";
|
||
|
||
export class AlbumCollection extends Array<Album> {
|
||
// custom array functions ...
|
||
}
|
||
|
||
export class Photo {
|
||
|
||
id: number;
|
||
|
||
name: string;
|
||
|
||
@Type(() => Album)
|
||
albums: Album[];
|
||
// albums: AlbumCollection; 使用自定义类型
|
||
}
|
||
|
||
export class Skill {
|
||
name: string;
|
||
}
|
||
|
||
export class Weapon {
|
||
name: string;
|
||
range: number;
|
||
}
|
||
|
||
export class Player {
|
||
name: string;
|
||
|
||
@Type(() => Skill)
|
||
skills: Set<Skill>;
|
||
|
||
@Type(() => Weapon)
|
||
weapons: Map<string, Weapon>;
|
||
}
|
||
```
|
||
|
||
### 自定义转换
|
||
|
||
#### 基本使用
|
||
|
||
你可以使用`@Transform`添加额外的数据转换,例如当你想把通过普通对象中的字符串日期转换后的`date`对象继续转换变成`moment`库的对象：
|
||
|
||
```javascript
|
||
import {Transform} from "class-transformer";
|
||
import * as moment from "moment";
|
||
import {Moment} from "moment";
|
||
|
||
export class Photo {
|
||
|
||
id: number;
|
||
|
||
@Type(() => Date)
|
||
@Transform(value => moment(value), { toClassOnly: true })
|
||
date: Moment;
|
||
}
|
||
```
|
||
|
||
现在当执行`plainToClass`转换后的对象中的`date`属性将是一个`Moment`对象。`@Transform`同样支持组和版本。
|
||
|
||
#### 高级用法
|
||
|
||
`@Transform`有更多的参数给你创建自定义的转换逻辑
|
||
|
||
```javascript
|
||
@Transform((value, obj, type) => value)
|
||
```
|
||
|
||
| 参数 | 描述 |
|
||
| :------ | ------------------------ |
|
||
| `value` | 自定义转换执行前的属性值 |
|
||
| `obj` | 转换源对象 |
|
||
| `type` | 转换的类型 |
|
||
|
||
#### 其他装饰器
|
||
|
||
| 签名 | 示例 |
|
||
| ------------------------ | ---------------------------------------------------- |
|
||
| `@TransformClassToPlain` | `@TransformClassToPlain({ groups: ["user"] })` |
|
||
| `@TransformClassToClass` | `@TransformClassToClass({ groups: ["user"] })` |
|
||
| `@TransformPlainToClas` | `@TransformPlainToClass(User, { groups: ["user"] })` |
|
||
|
||
上述装饰器接受一个可选参数：`ClassTransformOptions`-转换选项，例如groups, version, name，示例：
|
||
|
||
```javascript
|
||
@Exclude()
|
||
class User {
|
||
|
||
id: number;
|
||
|
||
@Expose()
|
||
firstName: string;
|
||
|
||
@Expose()
|
||
lastName: string;
|
||
|
||
@Expose({ groups: ['user.email'] })
|
||
email: string;
|
||
|
||
password: string;
|
||
}
|
||
|
||
class UserController {
|
||
|
||
@TransformClassToPlain({ groups: ['user.email'] })
|
||
getUser() {
|
||
const user = new User();
|
||
user.firstName = "Snir";
|
||
user.lastName = "Segal";
|
||
user.password = "imnosuperman";
|
||
|
||
return user;
|
||
}
|
||
}
|
||
|
||
const controller = new UserController();
|
||
const user = controller.getUser();
|
||
```
|
||
|
||
`user`对象将包含firstname,latstname和email
|
||
|
||
#### 使用泛型
|
||
|
||
由于目前Typescript对反射的支持还没有完善，所以只能使用其它替代方案，具体可以查看[这个例子](https://github.com/pleerock/class-transformer/tree/master/sample/sample4-generics)
|
||
|
||
#### 隐式类型转换
|
||
|
||
> 你如果将class-validator与class-transformer一起使用，则可能不想启用此功能。
|
||
|
||
根据Typescript提供的类型信息，启用内置类型之间的自动转换。默认禁用。
|
||
|
||
```javascript
|
||
import { IsString } from 'class-validator'
|
||
|
||
class MyPayload {
|
||
|
||
@IsString()
|
||
prop: string
|
||
}
|
||
|
||
|
||
const result1 = plainToClass(MyPayload, { prop: 1234 }, { enableImplicitConversion: true });
|
||
const result2 = plainToClass(MyPayload, { prop: 1234 }, { enableImplicitConversion: false });
|
||
|
||
/**
|
||
* result1 will be `{ prop: "1234" }` - notice how the prop value has been converted to string.
|
||
* result2 will be `{ prop: 1234 }` - default behaviour
|
||
*/
|
||
```
|
||
|
||
#### 循环引用
|
||
|
||
如果`User`包含一个`Photo`类型的`photos`数组属性，而`Photo`又包含一个属性链接到`User`，则转换过程中此属性会被忽略，除了`classToClass`操作。 |