@hadss/turbo-trans-json-plugin 1.0.0-rc.0 → 1.0.0-rc.2

package/src/core/analyzers/ClassAnalyzer.ts

@@ -14,28 +14,12 @@
  */
 
 import {
-  ClassDeclaration,
-  ConstructorDeclaration,
-  Decorator,
-  InterfaceDeclaration,
-  NewExpression,
-  PropertyDeclaration,
-  PropertySignature,
-  SyntaxKind,
-  TypeNode
+  ClassDeclaration, ConstructorDeclaration, Decorator, InterfaceDeclaration, NewExpression, ObjectLiteralExpression,
+  PropertyDeclaration, PropertySignature, SyntaxKind, TypeNode
 } from 'ts-morph';
 import {
-  ClassAnalysis,
-  InterfaceAnalysis,
-  ClassDecorators,
-  ConstructorParam,
-  DeserializationMode,
-  GenericInfo,
-  InheritanceInfo,
-  PropertyAnalysis,
-  PropertyDecorators,
-  PropertyKind,
-  SerializableOptions,
+  ClassAnalysis, ClassDecorators, ConstructorParam, DeserializationMode, GenericInfo, InheritanceInfo,
+  InterfaceAnalysis, PropertyAnalysis, PropertyDecorators, PropertyKind, PropertyVisibility, SerializableOptions,
   TypeStructure
 } from '../Types';
 import { DecoratorConstants } from '../constants';
@@ -45,7 +29,6 @@ import { CustomTypeAnalyzer } from './CustomTypeAnalyzer';
 import { CustomError, ErrorCodes } from '../utils/CustomError';
 import { Logger } from '../logger/Logger';
 import { TsMorphUtil } from '../utils/TsMorphUtil';
-import { logger } from 'handlebars';
 
 export class ClassAnalyzer {
   /**
@@ -97,14 +80,15 @@ export class ClassAnalyzer {
   }
 
   /**
-     * 分析接口的完整结构，包括属性、继承关系等信息
-     * @param interfaceDecl 接口声明节点
-     * @returns 接口分析结果
-     */
+   * 分析接口的完整结构，包括属性、继承关系等信息
+   * @param interfaceDecl 接口声明节点
+   * @returns 接口分析结果
+   */
   public static analyzeInterface(interfaceDecl: InterfaceDeclaration): InterfaceAnalysis {
     const interfaceName = interfaceDecl.getName();
     if (!interfaceName) {
-      throw new CustomError(`Interface name is undefined in ${interfaceDecl.getSourceFile().getFilePath()}`, ErrorCodes.CLASS_DECLARATION_NOT_FOUND);
+      throw new CustomError(`Interface name is undefined in ${interfaceDecl.getSourceFile().getFilePath()}`,
+        ErrorCodes.CLASS_DECLARATION_NOT_FOUND);
     }
     const sourceFilePath = interfaceDecl.getSourceFile().getFilePath();
     const generics: GenericInfo = {
@@ -141,7 +125,8 @@ export class ClassAnalyzer {
    */
   private static analyzeInheritanceInfo(cls: ClassDeclaration | InterfaceDeclaration): InheritanceInfo {
     const heritageClaus = cls.getHeritageClauses();
-    Logger.debug(`分析类的继承信息: ${cls.getName()} ${heritageClaus.length} ${heritageClaus.map(c => c.getText()).join(',')}`);
+    Logger.debug(
+      `分析类的继承信息: ${cls.getName()} ${heritageClaus.length} ${heritageClaus.map(c => c.getText()).join(',')}`);
     for (const clause of heritageClaus) {
       const token = clause.getToken();
       // 接口实现
@@ -155,7 +140,8 @@ export class ClassAnalyzer {
       Logger.debug(`继承信息: text: ${className} getTypeArguments: ${args.map(type => type.getText()).join(', ')}`);
       const classDecl = CustomTypeAnalyzer.getInstance().findClassDeclFromClassName(className, cls.getSourceFile());
       if (!classDecl) {
-        throw new CustomError(`class ${className} decl does not exist ${cls.getName} implement ${className}`, ErrorCodes.CLASS_DECLARATION_NOT_FOUND);
+        throw new CustomError(`class ${className} decl does not exist ${cls.getName} implement ${className}`,
+          ErrorCodes.CLASS_DECLARATION_NOT_FOUND);
       }
       if (classDecl instanceof InterfaceDeclaration) {
         const baseClassAnalysis = this.analyzeInterface(classDecl);
@@ -219,45 +205,69 @@ export class ClassAnalyzer {
       return undefined;
     }
     const args = decorator.getArguments();
-    let generateSendable: boolean | undefined;
-    let _with: string | undefined;
-    let deserializationMode: DeserializationMode | undefined;
-
     const firstArg = args[0];
 
-    if (!firstArg) {
+    if (!firstArg || firstArg.getKind() !== SyntaxKind.ObjectLiteralExpression) {
       return {};
     }
 
-    // 处理对象形式：@Serializable({ generateSendable: true })
-    if (firstArg.getKind() === SyntaxKind.ObjectLiteralExpression) {
-      const properties = firstArg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperties();
-
-      for (const prop of properties) {
-        if (prop.getKind() === SyntaxKind.PropertyAssignment) {
-          const propAssignment = prop.asKindOrThrow(SyntaxKind.PropertyAssignment);
-          const propertyName = propAssignment.getName();
-          const initializer = propAssignment.getInitializer();
-          if (propertyName === 'generateSendable' && initializer) {
-            if (initializer.getKind() === SyntaxKind.TrueKeyword) {
-              generateSendable = true;
-            } else if (initializer.getKind() === SyntaxKind.FalseKeyword) {
-              generateSendable = false;
-            }
-          } else if (propertyName === 'with' && initializer) {
-            // 处理 with 参数，存储完整的表达式文本
-            _with = initializer.getText();
-          } else if (propertyName === 'deserializationMode' && initializer) {
-            // 处理 deserializationMode 参数：'performance' | 'strict'
-            const modeText = initializer.getText().replace(/['"]/g, ''); // 去掉引号
-            if (modeText === DeserializationMode.PERFORMANCE || modeText === DeserializationMode.STRICT) {
-              deserializationMode = modeText as DeserializationMode;
-            }
-          }
-        }
+    return this.extractOptionsFromObjectLiteral(firstArg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression));
+  }
+
+  private static extractOptionsFromObjectLiteral(objectLiteral: ObjectLiteralExpression): SerializableOptions {
+    const options: SerializableOptions = {};
+    const properties = objectLiteral.getProperties();
+
+    for (const prop of properties) {
+      // early return: 非属性赋值节点
+      if (prop.getKind() !== SyntaxKind.PropertyAssignment) {
+        continue;
       }
+      const propAssignment = prop.asKindOrThrow(SyntaxKind.PropertyAssignment);
+      const initializer = propAssignment.getInitializer();
+      // early return: 无初始化器
+      if (!initializer) {
+        continue;
+      }
+
+      this.extractSingleOption(options, propAssignment.getName(), initializer);
+    }
+    return options;
+  }
+
+  private static extractSingleOption(
+    options: SerializableOptions,
+    propertyName: string,
+    initializer: ReturnType<typeof Object.prototype.valueOf>
+  ): void {
+    if (propertyName === 'generateSendable') {
+      options.generateSendable = this.parseBooleanInitializer(initializer);
+    } else if (propertyName === 'with') {
+      options.with = (initializer as { getText(): string }).getText();
+    } else if (propertyName === 'deserializationMode') {
+      this.parseDeserializationMode(options, initializer);
+    }
+  }
+
+  private static parseBooleanInitializer(initializer: ReturnType<typeof Object.prototype.valueOf>): boolean | undefined {
+    const kind = (initializer as { getKind(): SyntaxKind }).getKind();
+    if (kind === SyntaxKind.TrueKeyword) {
+      return true;
+    }
+    if (kind === SyntaxKind.FalseKeyword) {
+      return false;
+    }
+    return undefined;
+  }
+
+  private static parseDeserializationMode(
+    options: SerializableOptions,
+    initializer: ReturnType<typeof Object.prototype.valueOf>
+  ): void {
+    const modeText = (initializer as { getText(): string }).getText().replace(/['"]/g, '');
+    if (modeText === DeserializationMode.PERFORMANCE || modeText === DeserializationMode.STRICT) {
+      options.deserializationMode = modeText as DeserializationMode;
     }
-    return { with: _with, generateSendable, deserializationMode };
   }
 
   /**
@@ -266,36 +276,53 @@ export class ClassAnalyzer {
    * @returns 序列化名称
    */
   private static parseSerialNameOptions(decorator?: Decorator): string | undefined {
+    // early return: 无装饰器
     if (!decorator) {
       return undefined;
     }
     const args = decorator.getArguments();
+    // early return: 无参数
     if (args.length === 0) {
       return undefined;
     }
 
     const firstArg = args[0];
 
+    // early return: 非对象字面量
+    if (firstArg.getKind() !== SyntaxKind.ObjectLiteralExpression) {
+      return undefined;
+    }
+
     // 处理对象形式：@SerialName({ name: 'xxx' })
-    if (firstArg.getKind() === SyntaxKind.ObjectLiteralExpression) {
-      const properties = firstArg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperties();
-
-      for (const prop of properties) {
-        if (prop.getKind() === SyntaxKind.PropertyAssignment) {
-          const propAssignment = prop.asKindOrThrow(SyntaxKind.PropertyAssignment);
-          const name = propAssignment.getName();
-
-          if (name === 'name') {
-            const initializer = propAssignment.getInitializer();
-            if (initializer && initializer.getKind() === SyntaxKind.StringLiteral) {
-              const stringLiteral = initializer.asKindOrThrow(SyntaxKind.StringLiteral);
-              return stringLiteral.getLiteralValue();
-            }
-          }
-        }
+    const properties = firstArg.asKindOrThrow(SyntaxKind.ObjectLiteralExpression).getProperties();
+    return this.extractNameFromProperties(properties);
+  }
+
+  /**
+   * 从属性列表中提取name属性的值
+   * @param properties 属性列表
+   * @returns name属性的字符串值
+   */
+  private static extractNameFromProperties(properties: ReturnType<ObjectLiteralExpression['getProperties']>): string | undefined {
+    for (const prop of properties) {
+      // early return: 非属性赋值节点
+      if (prop.getKind() !== SyntaxKind.PropertyAssignment) {
+        continue;
+      }
+      const propAssignment = prop.asKindOrThrow(SyntaxKind.PropertyAssignment);
+      // early return: 非name属性
+      if (propAssignment.getName() !== 'name') {
+        continue;
+      }
+
+      const initializer = propAssignment.getInitializer();
+      // early return: 非字符串字面量
+      if (!initializer || initializer.getKind() !== SyntaxKind.StringLiteral) {
+        continue;
       }
-    }
 
+      return initializer.asKindOrThrow(SyntaxKind.StringLiteral).getLiteralValue();
+    }
     return undefined;
   }
 
@@ -320,40 +347,49 @@ export class ClassAnalyzer {
         genericParameters
       );
 
-      // 检测 UNKNOWN 类型
-      if (propertyAnalysis.type.kind === PropertyKind.UNKNOWN) {
-        const hasTransient = propertyAnalysis.decorators?.isTransient;
-        const hasCustomSerializer = !!propertyAnalysis.decorators?.with;
-
-        if (!hasTransient && !hasCustomSerializer) {
-          if (prop instanceof PropertyDeclaration) {
-            // 未知类型且没有 @Transient 或自定义序列化器，抛出清晰错误
-            throw new CustomError(
-              `不支持的类型 '${propertyAnalysis.type.sourceText}' 用于属性 '${propertyAnalysis.name
-              }' (类: ${cls.getName()})。\n` +
-              `请选择以下任一解决方案：\n` +
-              `  1. 添加 @Transient() 跳过序列化（属性仍会参与 Sendable 转换和对象拷贝）：\n` +
-              `     @Transient()\n` +
-              `     ${propertyAnalysis.name}: ${propertyAnalysis.type.sourceText};\n\n` +
-              `  2. 添加 @Serializable({with: CustomSerializer}) 指定自定义序列化器：\n` +
-              `     @Serializable({with: DateSerializer.INSTANCE})\n` +
-              `     ${propertyAnalysis.name}: ${propertyAnalysis.type.sourceText};`,
-              ErrorCodes.TYPE_NOT_SUPPORT
-            );
-          } else {
-            // 未知类型且没有 @Transient 或自定义序列化器，抛出清晰错误
-            throw new CustomError(`不支持的类型 '${propertyAnalysis.type.sourceText}' 用于属性 '${propertyAnalysis.name
-              }' (接口: ${cls.getName()})`, ErrorCodes.TYPE_NOT_SUPPORT);
-          }
-        }
-      }
-
-      // 保留所有属性（包括 UNKNOWN 类型），生成阶段再筛选
+      this.checkUnknownType(cls, prop, propertyAnalysis);
       ownProperties.push(propertyAnalysis);
     }
     return ownProperties;
   }
 
+  private static checkUnknownType(
+    cls: ClassDeclaration | InterfaceDeclaration,
+    prop: PropertyDeclaration | PropertySignature,
+    propertyAnalysis: PropertyAnalysis
+  ): void {
+    if (propertyAnalysis.type.kind !== PropertyKind.UNKNOWN) {
+      return;
+    }
+
+    const hasTransient = propertyAnalysis.decorators?.isTransient;
+    const hasCustomSerializer = !!propertyAnalysis.decorators?.with;
+
+    if (hasTransient || hasCustomSerializer) {
+      return;
+    }
+
+    if (prop instanceof PropertyDeclaration) {
+      // 未知类型且没有 @Transient 或自定义序列化器，抛出清晰错误
+      throw new CustomError(
+        `不支持的类型 '${propertyAnalysis.type.sourceText}' 用于属性 '${propertyAnalysis.name
+        }' (类: ${cls.getName()})。\n` +
+        `请选择以下任一解决方案：\n` +
+        `  1. 添加 @Transient() 跳过序列化（属性仍会参与 Sendable 转换和对象拷贝）：\n` +
+        `     @Transient()\n` +
+        `     ${propertyAnalysis.name}: ${propertyAnalysis.type.sourceText};\n\n` +
+        `  2. 添加 @Serializable({with: CustomSerializer}) 指定自定义序列化器：\n` +
+        `     @Serializable({with: DateSerializer.INSTANCE})\n` +
+        `     ${propertyAnalysis.name}: ${propertyAnalysis.type.sourceText};`,
+        ErrorCodes.TYPE_NOT_SUPPORT
+      );
+    } else {
+      // 未知类型且没有 @Transient 或自定义序列化器，抛出清晰错误
+      throw new CustomError(`不支持的类型 '${propertyAnalysis.type.sourceText}' 用于属性 '${propertyAnalysis.name
+      }' (接口: ${cls.getName()})`, ErrorCodes.TYPE_NOT_SUPPORT);
+    }
+  }
+
   /**
    * 对属性进行分类，区分继承属性、重写属性和自有属性
    * @param ownProperties 自有属性数组
@@ -370,8 +406,8 @@ export class ClassAnalyzer {
     overriddenProperties: PropertyAnalysis[];
     properties: PropertyAnalysis[];
   } {
+    // early return: 没有继承，所有属性都是自有属性
     if (!inheritance.isInherited || !inheritance.baseClassAnalysis) {
-      // 没有继承，所有属性都是自有属性
       return {
         inheritedProperties: [],
         overriddenProperties: [],
@@ -382,22 +418,34 @@ export class ClassAnalyzer {
     // 递归收集所有祖先属性 - 传递泛型参数进行替换
     const allAncestorProperties = this.collectAllAncestorProperties(
       inheritance.baseClassAnalysis,
-      inheritance.genericTypeArguments || [], // 传递子类指定的泛型参数
-      currentClassGenericParams // 传递当前类的泛型参数列表
+      inheritance.genericTypeArguments || [],
+      currentClassGenericParams
     );
 
+    return this.buildPropertyClassification(ownProperties, allAncestorProperties);
+  }
+
+  /**
+   * 根据自有属性和祖先属性构建属性分类结果
+   * @param ownProperties 自有属性数组
+   * @param allAncestorProperties 所有祖先属性数组
+   * @returns 分类后的属性对象
+   */
+  private static buildPropertyClassification(
+    ownProperties: PropertyAnalysis[],
+    allAncestorProperties: PropertyAnalysis[]
+  ): {
+    inheritedProperties: PropertyAnalysis[];
+    overriddenProperties: PropertyAnalysis[];
+    properties: PropertyAnalysis[];
+  } {
     // 构建自有属性名称集合，用于快速查找重写
     const ownPropertyNames = new Set(ownProperties.map((prop) => prop.name));
 
-    // 分类祖先属性：被重写的 vs 继承的
-    const inheritedProperties: PropertyAnalysis[] = [];
-
-    for (const ancestorProp of allAncestorProperties) {
-      if (!ownPropertyNames.has(ancestorProp.name)) {
-        // 被当前类继承了
-        inheritedProperties.push(ancestorProp);
-      }
-    }
+    // 分类祖先属性：过滤出被继承的（未被重写的）
+    const inheritedProperties = allAncestorProperties.filter(
+      (ancestorProp) => !ownPropertyNames.has(ancestorProp.name)
+    );
 
     // 确定当前类中的重写属性
     const overriddenProperties = ownProperties.filter((prop) =>
@@ -407,11 +455,7 @@ export class ClassAnalyzer {
     // 合并最终属性：继承的 + 当前类的（重写优先）
     const properties = [...inheritedProperties, ...ownProperties];
 
-    return {
-      inheritedProperties,
-      overriddenProperties,
-      properties
-    };
+    return { inheritedProperties, overriddenProperties, properties };
   }
 
   /**
@@ -436,22 +480,82 @@ export class ClassAnalyzer {
     const substitutedProperties = classAnalysis.ownProperties.map((property) =>
       GenericTypeSubstitutionUtil.substitutePropertyType(property, genericMapping, currentClassGenericParams)
     );
-
     allProperties.push(...substitutedProperties);
 
-    // 3. 递归处理更上层祖先，传递泛型参数
-    if (classAnalysis.inheritance.isInherited && classAnalysis.inheritance.baseClassAnalysis) {
-      const ancestorProperties = this.collectAllAncestorProperties(
-        classAnalysis.inheritance.baseClassAnalysis,
-        classAnalysis.inheritance.genericTypeArguments || [], // 传递当前层的泛型参数
-        currentClassGenericParams // 保持传递当前类的泛型参数
-      );
-      allProperties.push(...ancestorProperties);
-    }
+    // 3. 递归处理更上层祖先
+    this.collectAncestorPropertiesRecursively(
+      classAnalysis, parentGenericParams, genericMapping, currentClassGenericParams, allProperties
+    );
 
     return allProperties;
   }
 
+  /**
+   * 递归收集更上层祖先的属性
+   * @param classAnalysis 当前类分析结果
+   * @param parentGenericParams 父类泛型参数
+   * @param genericMapping 泛型映射
+   * @param currentClassGenericParams 当前类泛型参数列表
+   * @param allProperties 属性收集数组
+   */
+  private static collectAncestorPropertiesRecursively(
+    classAnalysis: ClassAnalysis | InterfaceAnalysis,
+    parentGenericParams: string[],
+    genericMapping: Map<string, TypeNode>,
+    currentClassGenericParams: string[],
+    allProperties: PropertyAnalysis[]
+  ): void {
+    // early return: 没有继承关系
+    if (!classAnalysis.inheritance.isInherited || !classAnalysis.inheritance.baseClassAnalysis) {
+      return;
+    }
+
+    // 解析父类的泛型参数，将泛型引用替换为具体类型
+    const parentGenericTypeArgs = classAnalysis.inheritance.genericTypeArguments || [];
+    const resolvedParentGenericArgs = this.resolveGenericTypeArgs(
+      parentGenericTypeArgs, parentGenericParams, genericMapping
+    );
+
+    Logger.debug(
+      `[CollectAncestors] Resolved parent generic args: ${resolvedParentGenericArgs.map(a => a.getText()).join(', ')}`);
+
+    const ancestorProperties = this.collectAllAncestorProperties(
+      classAnalysis.inheritance.baseClassAnalysis,
+      resolvedParentGenericArgs,
+      currentClassGenericParams
+    );
+    allProperties.push(...ancestorProperties);
+  }
+
+  /**
+   * 解析泛型类型参数，将泛型引用替换为具体类型
+   * @param typeArgs 类型参数数组
+   * @param parentGenericParams 父类泛型参数
+   * @param genericMapping 泛型映射
+   * @returns 解析后的类型参数数组
+   */
+  private static resolveGenericTypeArgs(
+    typeArgs: TypeNode[],
+    parentGenericParams: string[],
+    genericMapping: Map<string, TypeNode>
+  ): TypeNode[] {
+    return typeArgs.map(typeArg => {
+      // 解析类型参数为 TypeStructure
+      const typeStructure = TypeHandlerRegistry.getInstance().parseType(typeArg, {
+        depth: 0,
+        genericParams: parentGenericParams
+      });
+
+      // 如果是泛型引用，进行替换
+      if (typeStructure.kind === PropertyKind.GENERIC && genericMapping.has(typeStructure.sourceText)) {
+        return genericMapping.get(typeStructure.sourceText)!;
+      }
+
+      // 否则保持原样
+      return typeArg;
+    });
+  }
+
   /**
    * 提取构造函数参数信息
    * @param constructor 构造函数声明
@@ -485,45 +589,75 @@ export class ClassAnalyzer {
     genericParameters: string[]
   ): PropertyAnalysis {
     const name = prop.getName();
+    const typeNode = this.getTypeNode(prop);
+    const type = TypeHandlerRegistry.getInstance().parseType(typeNode, { genericParams: genericParameters, depth: 0 });
+    type.isOptional = prop.hasQuestionToken();
+
+    const defaultValue = prop instanceof PropertyDeclaration ?
+      this.analyzeDefaultValue(prop, constructorParams) : undefined;
+    const decorators = prop instanceof PropertyDeclaration ? this.analyzePropertyDecorators(prop) : undefined;
+    const visibility = this.getPropertyVisibility(prop);
+
+    const constructorParam = constructorParams.find((param) => param.name === name);
+    const isMust = this.calculateIsMust(prop, type, constructorParam, decorators, defaultValue);
+
+    if (decorators?.isTransient && constructorParam) {
+      this.validateTransientConstructorParam(name, constructorParam);
+    }
+
+    return {
+      name,
+      defaultValue,
+      decorators,
+      type,
+      isMust,
+      visibility
+    };
+  }
+
+  private static getTypeNode(prop: PropertyDeclaration | PropertySignature): TypeNode {
     let typeNode = prop.getTypeNode();
     if (!typeNode) {
       typeNode = this.analyzePropertyType(prop);
     }
-
     if (!typeNode) {
-      throw new CustomError(`无法分析属性 '${name}' 的类型。请检查属性声明。`, ErrorCodes.TYPE_NOT_SUPPORT);
+      throw new CustomError(`无法分析属性 '${prop.getName()}' 的类型。请检查属性声明。`, ErrorCodes.TYPE_NOT_SUPPORT);
     }
+    return typeNode;
+  }
 
-    const defaultValue: string | undefined = prop instanceof PropertyDeclaration ? this.analyzeDefaultValue(prop, constructorParams) : undefined;
-    const decorators = prop instanceof PropertyDeclaration ? this.analyzePropertyDecorators(prop) : undefined;
-    const type = TypeHandlerRegistry.getInstance().parseType(typeNode, { genericParams: genericParameters, depth: 0 });
-    type.isOptional = prop.hasQuestionToken();
-
-    const constructorParam = constructorParams.find((param) => param.name === name);
-
-    // 计算构造函数参数的可选性（用于后续验证）
-    const isParamOptional = constructorParam
-      ? constructorParam.isOptional ||
-        constructorParam.defaultValue !== undefined ||
-        this.hasUndefinedInUnion(constructorParam.type)
-      : true;
+  private static getPropertyVisibility(prop: PropertyDeclaration | PropertySignature): PropertyVisibility {
+    if (prop.hasModifier(SyntaxKind.PrivateKeyword)) {
+      return PropertyVisibility.PRIVATE;
+    }
+    if (prop.hasModifier(SyntaxKind.ProtectedKeyword)) {
+      return PropertyVisibility.PROTECTED;
+    }
+    return PropertyVisibility.PUBLIC;
+  }
 
-    let isMust: boolean;
+  private static calculateIsMust(
+    prop: PropertyDeclaration | PropertySignature,
+    type: TypeStructure,
+    constructorParam: ConstructorParam | undefined,
+    decorators: PropertyDecorators | undefined,
+    defaultValue: string | undefined
+  ): boolean {
     if (constructorParam) {
-      // 属性在构造函数参数中，以构造函数参数的必要性为准
-      // 构造函数参数可选的条件：
-      // 1. 有显式的?标记（isOptional为true）
-      // 2. 有默认值
-      // 3. 类型字符串中包含undefined作为联合类型成员
-      isMust = !isParamOptional;
-    } else {
-      // 属性不在构造函数中，判断属性本身的必要性
-      isMust = decorators?.isRequired || !this.isOptional(prop, defaultValue, type);
+      const isParamOptional = constructorParam.isOptional ||
+        constructorParam.defaultValue !== undefined ||
+        this.hasUndefinedInUnion(constructorParam.type);
+      return !isParamOptional;
     }
+    return decorators?.isRequired || !this.isOptional(prop, defaultValue, type);
+  }
+
+  private static validateTransientConstructorParam(name: string, constructorParam: ConstructorParam): void {
+    const isParamOptional = constructorParam.isOptional ||
+      constructorParam.defaultValue !== undefined ||
+      this.hasUndefinedInUnion(constructorParam.type);
 
-    // @Transient 属性的构造函数参数验证
-    // 检查构造函数参数是否可选或有默认值
-    if (decorators?.isTransient && constructorParam && !isParamOptional) {
+    if (!isParamOptional) {
       throw new CustomError(
         `@Transient 属性 '${name}' 的构造函数参数必须是可选的或有默认值。\n` +
         `因为 @Transient 属性不参与序列化，反序列化时无法从外部数据获取值。\n` +
@@ -533,14 +667,6 @@ export class ClassAnalyzer {
         ErrorCodes.TRANSIENT_ATTR_OPTIONAL
       );
     }
-
-    return {
-      name,
-      defaultValue,
-      decorators,
-      type,
-      isMust
-    };
   }
 
   private static analyzePropertyType(prop: PropertyDeclaration | PropertySignature): TypeNode | undefined {
@@ -598,7 +724,8 @@ export class ClassAnalyzer {
     return typeText;
   }
 
-  private static getTypeFromInitializer(prop: PropertyDeclaration | PropertySignature, propName: string): TypeNode | undefined {
+  private static getTypeFromInitializer(prop: PropertyDeclaration | PropertySignature,
+    propName: string): TypeNode | undefined {
     const initializer = prop.getInitializer();
     if (!initializer) {
       return undefined;
@@ -626,7 +753,8 @@ export class ClassAnalyzer {
     }
 
     const exprText = expression.getText();
-    const supportedTypes = ['Map', 'Set', 'WeakMap', 'WeakSet', 'Array', 'Object', 'ArrayList', 'HashMap', 'HashSet', 'LinkedList', 'Decimal', 'List'];
+    const supportedTypes = ['Map', 'Set', 'WeakMap', 'WeakSet', 'Array', 'Object', 'ArrayList', 'HashMap', 'HashSet',
+      'LinkedList', 'Decimal', 'List'];
 
     if (!supportedTypes.includes(exprText)) {
       return undefined;
@@ -651,7 +779,8 @@ export class ClassAnalyzer {
    * @param type 类型结构
    * @returns 是否为可选属性
    */
-  private static isOptional(node: PropertyDeclaration | PropertySignature, defaultValue: string | undefined, type: TypeStructure): boolean {
+  private static isOptional(node: PropertyDeclaration | PropertySignature, defaultValue: string | undefined,
+    type: TypeStructure): boolean {
     // 1. 语法上带 ?（prop?: T, param?: T）
     if (node.hasQuestionToken()) {
       return true;
@@ -768,14 +897,14 @@ export class ClassAnalyzer {
    */
   private static analyzePropertyDecorators(prop: PropertyDeclaration): PropertyDecorators {
     const decorators = prop.getDecorators();
-    let isRequired: boolean = false;
-    let isTransient: boolean = false;
+    let isRequired = false;
+    let isTransient = false;
+    let isPlainValue = false;
     let serialName: string | undefined;
     let _with: string | undefined;
 
     decorators.forEach((decorator) => {
       const name = decorator.getName();
-
       switch (name) {
         case DecoratorConstants.SERIAL_NAME:
           serialName = this.parseSerialNameOptions(decorator);
@@ -786,39 +915,71 @@ export class ClassAnalyzer {
         case DecoratorConstants.TRANSIENT:
           isTransient = true;
           break;
+        case DecoratorConstants.PLAIN_VALUE:
+          isPlainValue = true;
+          break;
         case DecoratorConstants.SERIALIZABLE:
           _with = this.parseSerializableOptions(decorator)!.with;
+          break;
       }
     });
 
-    // 注解互斥检查：@Transient 与其他序列化注解互斥
-    if (isTransient) {
-      const conflictingDecorators: string[] = [];
-      if (isRequired) {
-        conflictingDecorators.push('@Required');
-      }
-      if (serialName) {
-        conflictingDecorators.push('@SerialName');
-      }
-      if (_with) {
-        conflictingDecorators.push('@Serializable');
-      }
-
-      if (conflictingDecorators.length > 0) {
-        throw new CustomError(
-          `属性 '${prop.getName()}' 的注解冲突：@Transient 与 ${conflictingDecorators.join(', ')} 不能同时使用。\n` +
-          `@Transient 表示跳过序列化，与其他序列化配置注解互斥。\n` +
-          `请移除 @Transient 或移除其他序列化注解。`,
-          ErrorCodes.ANNOTATION_CONFLICT
-        );
-      }
-    }
+    this.checkTransientConflicts(prop.getName(), isTransient, isRequired, !!serialName, !!_with, isPlainValue);
+    this.checkPlainValueConflicts(prop.getName(), isPlainValue, !!_with);
 
     return {
       isRequired,
       isTransient,
+      isPlainValue,
       serialName,
       with: _with
     };
   }
+
+  private static checkTransientConflicts(
+    propName: string,
+    isTransient: boolean,
+    isRequired: boolean,
+    hasSerialName: boolean,
+    hasWith: boolean,
+    isPlainValue: boolean
+  ): void {
+    if (!isTransient) {
+      return;
+    }
+
+    const conflictingDecorators: string[] = [];
+    if (isRequired) {
+      conflictingDecorators.push('@Required');
+    }
+    if (hasSerialName) {
+      conflictingDecorators.push('@SerialName');
+    }
+    if (hasWith) {
+      conflictingDecorators.push('@Serializable');
+    }
+    if (isPlainValue) {
+      conflictingDecorators.push('@PlainValue');
+    }
+
+    if (conflictingDecorators.length > 0) {
+      throw new CustomError(
+        `属性 '${propName}' 的注解冲突：@Transient 与 ${conflictingDecorators.join(', ')} 不能同时使用。\n` +
+        `@Transient 表示跳过序列化，与其他序列化配置注解互斥。\n` +
+        `请移除 @Transient 或移除其他序列化注解。`,
+        ErrorCodes.ANNOTATION_CONFLICT
+      );
+    }
+  }
+
+  private static checkPlainValueConflicts(propName: string, isPlainValue: boolean, hasWith: boolean): void {
+    if (isPlainValue && hasWith) {
+      throw new CustomError(
+        `属性 '${propName}' 的注解冲突：@PlainValue 与 @Serializable(with:) 不能同时使用。\n` +
+        `@PlainValue 跳过类型转换直接使用原始值，与自定义序列化器冲突。\n` +
+        `请移除 @PlainValue 或移除自定义序列化器。`,
+        ErrorCodes.ANNOTATION_CONFLICT
+      );
+    }
+  }
 }