序列化后端前端【免费下载链接】class-transformerDecorator-based transformation, serialization, and deserialization between objects and classes.项目地址https://gitcode.com/gh_mirrors/cl/class-transformer点击查看免费下载本篇指南围绕 class-transformer 最核心的两个转换入口展开plainToInstance将普通对象转换为类实例与instanceToPlain将已知类实例转换为普通对象。你将掌握Expose、Exclude、Transform、Type四个基础装饰器的语义与用法理解“一切转换都由装饰器注册的元数据驱动”这一核心设计并了解如何正确为类属性打上装饰器标记避免常见的“空构造函数调用”陷阱。文中所有细节均以当前仓库 src 目录下的源码实现为准。一、两个核心转换函数双向转换的入口class-transformer 的全部基础能力可以收敛为两个方向相反的导出函数详见 src/index.tsplainToInstance(cls, plain, options?)—— 将普通对象plain object转换为指定类构造函数的实例instanceToPlain(object, options?)—— 将已知的类实例转换为普通对象。import { plainToInstance, instanceToPlain } from class-transformer;第一个参数传入的是类的构造函数本身即ClassConstructorT而不是类的实例两个函数均支持传入单个对象或对象数组数组输入会得到对应的数组输出第三个可选参数options为ClassTransformOptions用于控制转换策略详见后文“转换选项”一节。两者的方向可这样直观理解函数输入输出典型场景plainToInstance普通对象 / 数组类实例 / 数组反序列化把 JSON.parse 得到的对象还原为类实例instanceToPlain类实例 / 数组普通对象 / 数组序列化把类实例输出为可 JSON 化的普通对象从源码看两者在 ClassTransformer.ts 中分别通过TransformationType.PLAIN_TO_CLASS与TransformationType.CLASS_TO_PLAIN两个枚举值创建TransformOperationExecutor执行器其余逻辑完全交由 TransformOperationExecutor.ts 统一处理。这正印证了文档中的关键论断两个函数都是通过应用类定义上由装饰器注册的元数据将源对象转换为目标对象。也就是说装饰器负责“声明”执行器负责“执行”转换行为完全由元数据驱动。二、四个基础装饰器声明转换规则的元数据文档给出的四个主要装饰器是编写 class-transformer 代码的基础语法装饰器作用可应用位置Expose指定属性在转换后的目标对象上如何暴露类定义与属性PropertyDecorator ClassDecoratorExclude将属性标记为跳过不参与转换类定义与属性Transform通过自定义处理函数为属性指定自定义转换逻辑仅属性PropertyDecoratorType显式指定属性的类型转换时 class-transformer 会尝试创建该类型的实例仅属性2.1Expose控制属性的暴露方式expose.decorator.ts 的实现显示Expose(options: ExposeOptions {})既可以作为属性装饰器也可以作为类装饰器使用——当作用于类时等价于把类内所有属性默认暴露。ExposeOptions的完整字段定义于 expose-options.interface.ts选项类型说明namestring在目标对象上暴露该属性值时使用的属性名重命名sincenumber该属性自某个版本起才被暴露配合options.version生效untilnumber该属性只暴露到某个版本为止groupsstring[]属性所属的转换分组仅当调用时传入匹配的groups才暴露toClassOnlyboolean仅在 plain → class 转换中暴露toPlainOnlyboolean仅在 class → plain 转换中暴露最常见的用法是通过name完成属性重命名例如把内部命名的_id在输出时暴露为idclass User { /** 转换为普通对象时_id 会被重映射为 id */ Expose({ name: id }) private _id: string; /** 原样暴露 name 属性 */ Expose() public name: string; }2.2Exclude将属性排除在转换之外exclude.decorator.ts 与Expose对称用于把属性标记为“跳过”。其选项类型ExcludeOptions见 exclude-options.interface.ts同样包含toClassOnly、toPlainOnly、groups、since、until也就是说排除行为同样可以被限定方向、分组或版本class User { /** 排除 passwordHash使其不会出现在转换后的普通对象中 */ Exclude() public passwordHash: string; }2.3Transform自定义转换逻辑当内置的暴露/排除规则无法满足需求时transform.decorator.ts 允许你传入一个自定义处理函数在转换发生时对该属性值做任意加工Transform((params) /* 自定义转换逻辑 */) public someProperty: string;处理函数收到的params是TransformFnParams对象定义于 transform-fn-params.interface.ts包含以下字段字段类型含义valueany当前属性的值keystring当前属性的键名objany当前正在转换的整个源对象typeTransformationType当前转换方向PLAIN_TO_CLASS/CLASS_TO_PLAIN/CLASS_TO_CLASS见 transformation-type.enum.tsoptionsClassTransformOptions本次转换传入的全部选项TransformOptions见 transform-options.interface.ts与ExposeOptions共享同一套版本、分组、方向控制字段since、until、groups、toClassOnly、toPlainOnly你可以据此让自定义转换也服从统一的版本/分组策略。2.4Type显式声明属性类型type.decorator.ts 用于在反序列化时告诉 class-transformer 属性应该被还原成什么类型的实例。它的核心签名是Type(typeFunction?: (type?: TypeHelpOptions) Function, options?: TypeOptions)typeFunction返回目标构造函数不传时class-transformer 会退而读取Reflect.getMetadata(design:type, ...)反射元数据options为TypeOptions见 type-options.interface.ts支持discriminator鉴别器描述符按属性值动态选择子类与keepDiscriminatorProperty是否保留鉴别器属性默认false。例如嵌套对象还原class Album { Type(() Photo) photos: Photo[]; }转换时 class-transformer 会对photos数组中的每一项尝试创建Photo实例。三、重要约束每个属性都必须声明装饰器文档强调了一条强制规则你必须始终为所有属性标记Expose或Exclude装饰器。这是由默认策略决定的。在 class-transformer-options.interface.ts 中可以看到默认策略为exposeAllstrategy字段默认值见 default-options.constant.ts理论上所有属性默认都会被转换但如果开启了excludeExtraneousValues从普通对象转换到类时剔除多余属性则该选项要求目标类上的每个属性都至少带有一个来自本库的Expose或Exclude装饰器否则该选项无法正确工作。同时 default-options.constant.ts 也列出了全部默认选项值可作为行为预期的参考export const defaultOptions: PartialClassTransformOptions { enableCircularCheck: false, enableImplicitConversion: false, excludeExtraneousValues: false, excludePrefixes: undefined, exposeDefaultValues: false, exposeUnsetFields: true, // 值为 undefined 的字段在 class → plain 时默认保留 groups: undefined, ignoreDecorators: false, strategy: undefined, // 默认 exposeAll targetMaps: undefined, version: undefined, };四、关键注意点空构造函数调用文档末尾的 NOTE 揭示了一个极易踩坑的实现细节请记住class-transformer会用空的构造函数来调用目标类型如果你使用的类型需要特殊初始化就必须使用Transform装饰器自行创建实例。这意味着通过Type(() SomeClass)指定的类型在转换时会被 class-transformer 以无参构造new SomeClass()的方式实例化如果该类型需要在构造时接收参数、进行异步初始化或执行副作用那么这种“空构造”方式无法满足需求此时应放弃Type的自动实例化改用Transform在回调里自行new出带参实例例如class Order { Transform(({ value }) new Money(value.amount, value.currency)) total: Money; }该约束同样适用于plainToInstance返回的顶层实例——目标类必须能够被无参构造否则需要借助Transform兜底。五、完整示例双向转换实战把上述概念串起来一个最小可运行的完整用例对应文档 Basic Usage 部分 的思路如下import reflect-metadata; // 必须在应用第一行导入 import { Expose, Exclude, plainToInstance, instanceToPlain } from class-transformer; class User { Expose({ name: id }) private _id: string; Expose() public name: string; Exclude() public passwordHash: string; } const plainUser { id: 42, name: John Snow, passwordHash: 2f55ce082... }; // 反序列化普通对象 → 类实例 const user plainToInstance(User, plainUser); // user 是一个 User 实例passwordHash 不会被还原 // 序列化类实例 → 普通对象 const plain instanceToPlain(user); // plain 只包含 { id: 42, name: John Snow }在这个例子中可以清楚看到三个装饰器的分工Expose({ name: id })完成重命名、Expose()原样透传、Exclude()完成敏感字段过滤。六、进阶转换选项可选补充plainToInstance与instanceToPlain的第三个参数options可覆盖 default-options.constant.ts 中的默认值常用选项完整定义见 class-transformer-options.interface.ts包括选项类型作用strategyexcludeAll \| exposeAll全局排除/暴露策略默认exposeAllgroupsstring[]只转换命中指定分组的属性versionnumber只转换since ≤ version ≤ until范围内的属性excludePrefixesstring[]排除指定前缀的属性仅对exposeAll生效excludeExtraneousValuesbooleanplain → class 时剔除未声明的多余属性exposeDefaultValuesboolean为未提供的字段填充默认值exposeUnsetFieldsbooleanclass → plain 时是否保留值为undefined的字段默认trueenableImplicitConversionboolean依据类型信息隐式转换属性值enableCircularCheckboolean开启循环引用检测ignoreDecoratorsboolean忽略全部Expose/Exclude装饰器效果targetMapsTargetMap[]在不使用Type的情况下为目标类型建立映射例如按版本控制字段暴露const plain instanceToPlain(user, { version: 1.0 });七、相关资源索引想继续深入理解底层实现可查阅仓库内以下文件转换函数声明与执行器调度src/index.ts、src/ClassTransformer.ts转换方向枚举src/enums/transformation-type.enum.ts四个装饰器实现src/decorators选项类型定义src/interfaces/decorator-options、src/interfaces/class-transformer-options.interface.ts转换处理函数参数src/interfaces/metadata/transform-fn-params.interface.ts功能测试用例test/functional/basic-functionality.spec.ts上手安装与环境配置docs/pages/01-getting-started.md安装与配置前提详见 Getting Startednpm install class-transformer reflect-metadata在应用第一行import reflect-metadata并在tsconfig.json中开启emitDecoratorMetadata与experimentalDecorators两个编译选项后即可开始使用。赞分享序列化后端前端【免费下载链接】class-transformerDecorator-based transformation, serialization, and deserialization between objects and classes.项目地址https://gitcode.com/gh_mirrors/cl/class-transformer点击查看免费下载相关推荐class-transformer装饰器详解Expose与Exclude的高级应用class transformer装饰器详解Expose与Exclude的高级应用 在TypeScript开发中处理对象序列化Serializatio序列化后端前端class-transformer高级装饰器创建自定义转换逻辑class transformer高级装饰器创建自定义转换逻辑 在日常开发中你是否经常遇到需要在对象与JSON之间进行复杂转换的场景比如日期格式化、数据脱序列化后端前端class-transformer项目基础使用指南对象与类的双向转换class transformer项目基础使用指南对象与类的双向转换 前言 在现代JavaScript/TypeScript开发中我们经常需要在普通对象P序列化后端前端上一篇BepInEx插件框架开发终极指南从原理到实战的游戏扩展技术下一篇Unity游戏插件框架终极指南从入门到精通BepInEx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考