Drizzle ORM 中 Branded Zod 类型的使用技巧

在 TypeScript 开发中，类型安全是保证代码质量的重要手段。Drizzle ORM 与 Zod 的结合为开发者提供了强大的类型校验能力，但在使用 Branded Zod 类型时，开发者可能会遇到一些类型不匹配的问题。

Branded 类型的基本概念

Branded 类型是 TypeScript 中一种创建名义类型（nominal typing）的方式。它允许我们为基本类型添加额外的类型信息，使类型系统能够区分看似相同但实际上用途不同的类型。例如，一个表示文件ID的字符串和一个普通字符串虽然都是字符串类型，但在业务逻辑中应该被视为不同的类型。

常见问题场景

在使用 Drizzle ORM 时，开发者可能会尝试直接在表定义中使用 Branded 类型：

const fileIdSchema = z.string().uuid().brand<'FileId'>();
type FileId = z.infer<typeof fileIdSchema>;

export const files = pgTable('files', {
    id: uuid()
        .primaryKey()
        .$defaultFn(() => uuidv7())
        .$type<FileId>(), // 这里直接指定类型
    name: varchar({ length: 255 }).notNull(),
});

这种方式会导致运行时类型信息丢失，因为 TypeScript 的类型信息在编译后会消失，而 Zod 的校验能力需要在运行时保留。

正确使用方法

正确的做法是在创建插入模式时指定 Branded 类型的校验规则：

export const zodFilesInsertSchema = createInsertSchema(files, {
  id: fileIdSchema // 在这里指定校验规则
});

这种方法既保留了运行时的校验能力，又确保了类型系统的正确性。当使用这种方式时：

1. 数据库操作返回的结果会自动带有正确的 Branded 类型
2. 类型系统能够正确识别不同类型的字符串
3. 运行时校验确保数据的有效性

实际应用建议

在实际项目中，建议遵循以下最佳实践：

1. 为每个需要区分的基本类型创建对应的 Branded 类型
2. 在表定义中只定义基本类型
3. 在创建校验模式时指定具体的 Branded 校验规则
4. 在业务逻辑中使用 Branded 类型来确保类型安全

这种方法不仅能解决类型不匹配的问题，还能提高代码的可读性和可维护性，使类型系统真正成为开发者的有力工具。