# 品牌类型 ## 什么和为什么 TypeScript 使用**结构类型**——具有相同形状的两种类型可以互换。这意味着“UserId”和“PostId”（都是“string”）可以默默地交换，从而导致错误：输入用户 ID = 字符串输入帖子 ID = 字符串函数 getUser(id: UserId) { /* ... */ } const postId: PostId = "post-123" getUser(postId) // 没有错误！两者都只是“字符串” **品牌类型**添加仅编译时标记，使结构相同的类型不兼容。零运行时开销——品牌在编译期间被擦除。 ## 核心模式（推荐）使用带有单个“唯一符号”的通用“品牌”实用程序： // 品牌.ts 声明 const __brand: 唯一符号类型 Brand = T & { 只读 [__brand]: B } 定义特定的品牌类型：从 './brand' 导入类型 { Brand } 类型 UserId = Brand<字符串, 'UserId'> 类型 PostId = Brand<字符串, 'PostId'> 类型电子邮件=品牌<字符串，'电子邮件'> 类型米=品牌<数字，'米'> 类型秒=品牌<数字，'秒'> 类型 PositiveInt = Brand<数字，'PositiveInt'> 现在 `UserId` 和 `PostId` 在编译时不兼容：函数 getUser(id: UserId) { /* ... */ } const postId = "post-123" 作为 PostId getUser(postId) // TS 错误：PostId 无法分配给 UserId ## 构造函数切勿在应用程序代码中使用裸露的“as”强制转换。创建构造函数/验证函数：函数createUserId(id: string): UserId { if (!id || id.length === 0) throw new Error('无效的用户Id') 返回 id 作为 UserId } 函数 validateEmail(输入：字符串): 电子邮件 { if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(输入)) { 抛出新错误（'无效电子邮件'） } 以电子邮件形式返回输入 } 函数 toPositiveInt(n: 数字): PositiveInt { if (!Number.isInteger(n) || n <= 0) throw new Error('必须是正整数') 返回 n 作为 PositiveInt } `as` 强制转换仅限于这些构造函数 - 这是它应该出现的唯一位置。 ## 实现变体图案|方法|实力|冗长 ---|---|---|--- **A** `__brand` 属性 | `T & { __brand: B }` |好 |低 **B** 每类型“唯一符号” | `T & { [MyBrand]: true }` |最强|高 **C** 通用“唯一符号”（推荐）| `T & { [__brand]: B }` |强|低 **默认为模式 C** — 它平衡了安全性与人体工程学。有关详细的权衡和完整示例，请参阅 [references/patterns.md]()。 ## 实际用例 ### 类型安全 ID 类型 UserId = Brand<字符串, 'UserId'> 类型 PostId = Brand<字符串, 'PostId'> 类型 CommentId = Brand 函数 getPost(postId: PostId) { /* ... */ } 函数deleteComment(commentId: CommentId) { /* ... */ } ### 已验证的字符串类型电子邮件=品牌<字符串，'电子邮件'> 类型 NonEmptyString = Brand 类型 SanitizedHTML = Brand 类型 TranslationKey = Brand ### 单位特定数字类型米=品牌<数字，'米'> 类型英尺=品牌<数字，'英尺'> 类型秒=品牌<数字，'秒'> 类型毫秒=品牌<数字，'毫秒'> type Percentage = Brand // 0-100 ### 令牌和敏感值类型 AccessToken = Brand 类型 RefreshToken = Brand 类型 ApiKey = Brand<字符串, 'ApiKey'> ## 反模式 ### 1\.在运行时检查品牌 // 错误 — __brand 在运行时不存在 if ((value as any).__brand === 'UserId') { /* ... */ } 品牌类型仅在编译时有效。对于运行时检查，请使用构造函数/验证函数。 ### 2\.应用程序代码中的裸“as”转换 // 不好——没有验证，达不到目的 const userId = someString 作为 UserId // GOOD——经过验证的构造函数 const userId = createUserId(someString) 仅将“as”强制转换为构造函数。 ### 3\.过度品牌化不要给每个“字符串”或“数字”打上烙印。在以下情况下使用品牌类型： * 混合值会导致错误（ID、单位、经过验证的数据） * 存在多种相似类型，不应互换 * 项目规模足够大，安全受益 ### 4\.跨模块重复的品牌名称 // file-a.ts — Brand // file-b.ts — Brand // 它们共享品牌名称“Id”，但含义不同！使用具体的、描述性的品牌名称：“UserId”、“PostId”，而不仅仅是“Id”。 ## 库集成 ### 佐德从 'zod' 导入 { z } const UserIdSchema = z.string().uuid().brand<'UserId'>() type UserId = z.infer // 字符串 & Brand<'UserId'> const parsed = UserIdSchema.parse(input) // 输入为 UserId ### 毛毛雨 ORM 从 'drizzle-orm/pg-core' 导入 { text } // 标记列输出类型 const 用户 = pgTable('用户', { id: text('id').primaryKey().$type(), }) // 查询返回 UserId，而不是纯字符串 const user = wait db.select().from(users).where(eq(users.id, userId)) 有关详细的集成示例（端到端流程、更多库），请参阅 [references/integrations.md]()。 ## 何时使用品牌类型场景 |使用品牌类型？ ---|--- 多种ID类型不应混用 |是的已验证数据与未验证数据 |是的单位特定数字（米与英尺）|是的令牌/秘密与纯字符串 |是的小脚本，类型少 |可能不会小项目中的单一ID类型|可能不会需要运行时类型区分 |使用受歧视的工会代替 ## 其他资源 * 详细模式比较：[references/patterns.md]() * 对于库集成示例：[references/integrations.md]()

品牌类型

包含技能