TypeBox 中自定义类型元数据丢失问题的解决方案

背景介绍

TypeBox 是一个强大的 TypeScript 类型验证库，它允许开发者通过编程方式定义 JSON Schema。在从 TypeBox 0.24 版本升级到 0.32 版本的过程中，一些开发者遇到了自定义类型元数据丢失的问题。

问题现象

在旧版本中，开发者通过继承 TypeBuilder 类创建了自定义类型 StringEnumArray，并为这些类型附加了元数据信息。这些元数据用于实现特定的验证逻辑。然而，在升级到 0.32 版本后，发现这些元数据不再包含在生成的 Schema 中，同时类型标识符也从 Unsafe 变成了 Intersect。

根本原因分析

TypeBox 在 0.25.0 到 0.32.0 版本之间对类型构建器进行了多项更新，特别是对 Intersect 类型的内部表示方式进行了修改。新版本中，Intersect 类型使用了 allOf 的表示方式，这与旧版本的实现有所不同。

解决方案

要解决这个问题，开发者需要做以下调整：

1. 使用正确的基类：应该继承 JsonTypeBuilder 或 JavaScriptTypeBuilder 而不是旧的 TypeBuilder。对于 Fastify 应用，推荐使用 JsonTypeBuilder。

2. 保持元数据符号：自定义类型构建器中定义的 Meta 符号仍然有效，可以继续用于存储类型元数据。

3. 处理复合类型：如果遇到类型标识符变为 Intersect 的情况，可以考虑使用 Composite 类型替代，它保留了旧版本的表示方式。

实现示例

以下是修正后的自定义类型构建器实现：

import { JsonTypeBuilder } from '@sinclair/typebox'

type CustomTypeBuilderMeta = { 
  type: 'decimal128' 
} | { 
  type: 'stringEnumArray'; 
  values: Set<string> 
};

const Meta = Symbol('Meta');

export class CustomTypeBuilder extends JsonTypeBuilder {
  public readonly Meta = Meta;
  
  constructor() {
    super();
  }
  
  public getMeta(item: any): CustomTypeBuilderMeta {
    return item[this.Meta];
  }
  
  public StringEnumArray<T extends string[]>(
    values: [...T], 
    opts: { examples?: any; description?: string } = {}
  ) {
    return super.Unsafe<Array<T[number]>>({
      type: 'string',
      examples: [...opts.examples ?? [], ...values],
      description: opts.description,
      [this.Meta]: { 
        type: 'stringEnumArray', 
        values: new Set(values) 
      } as CustomTypeBuilderMeta,
    });
  }
}

export const Type = new CustomTypeBuilder();

验证结果

使用上述实现后，生成的 Schema 将包含正确的元数据和类型标识符：

{
  "type": "string",
  "examples": ["A", "B"],
  "description": undefined,
  "[Symbol(Meta)]": { 
    "type": "stringEnumArray", 
    "values": Set(2) { "A", "B" } 
  },
  "[Symbol(TypeBox.Kind)]": "Unsafe"
}

总结

在 TypeBox 升级过程中，理解类型构建器的变化对于保持自定义类型的兼容性至关重要。通过正确继承基类并了解复合类型的新表示方式，开发者可以顺利迁移自定义类型逻辑。对于需要保持旧版本行为的场景，Composite 类型提供了向后兼容的解决方案。