# TypeScript 最佳实践 ## 与 React 最佳实践搭配使用 React 组件（“.tsx”、“.jsx”文件或“@react”导入）时，请始终加载“react-best-practices”以及此技能。这项技能涵盖了 TypeScript 基础知识； React 特定的模式（效果、钩子、引用、组件设计）位于专用的 React 技能中。 ## 类型优先开发类型在实施之前定义合同。请遵循以下工作流程： 1. **定义数据模型** \- 首先类型、接口和模式 2. **定义函数签名** \- 逻辑之前的输入/输出类型 3. **实现满足类型** \-让编译器引导完整性 4. **在边界处验证** \- 运行时检查数据进入系统的位置 ### 让非法国家无法代表使用类型系统来防止编译时的无效状态。 **相互排斥国家的受歧视工会：** // 好：仅可能有效的组合类型请求状态 = | { 状态： '空闲' } | { 状态： '正在加载' } | { 状态：'成功'；数据：T} | { 状态：'错误'；错误：错误}； // 不好：允许无效组合，例如 {loading: true, error: Error } 类型请求状态 = { 加载：布尔值；数据？：T；错误？：错误； }; **域原语的品牌类型：** 类型 UserId = string & { readonly __brand: 'UserId' }; 类型 OrderId = string & { readonly __brand: 'OrderId' }; // 编译器阻止将 OrderId 传递到预期 UserId 的位置 function getUser(id: UserId): Promise { /* ... */ } 函数createUserId(id: string): UserId { 返回 id 作为 UserId； } **文字联合的 const 断言：** const ROLES = ['管理员', '用户', '访客'] as const; 类型角色 = typeof ROLES[编号]; // '管理员' | '用户' | ‘客人’ // 数组和类型自动保持同步函数 isValidRole(角色: string): 角色是角色 { return ROLES.includes(角色作为角色); } **必填字段与可选字段 - 明确：** // 创建：需要一些字段类型创建用户 = { 电子邮件：字符串；名称：字符串； }; // 更新：所有字段都是可选的类型 UpdateUser = Partial; // 数据库行：存在的所有字段类型用户=创建用户&{ id：用户ID；创建于：日期； }; ## 模块结构更喜欢较小的、集中的文件：每个文件一个组件、挂钩或实用程序。当文件处理多个问题或超过约 200 行时进行拆分。将测试与实现并置（“foo.test.ts”与“foo.ts”一起）。按功能而不是按类型对相关文件进行分组。 ## 函数式模式 * 优先选择 `const` 而不是 `let`；对不可变数据使用“readonly”和“Readonly”。 * 在“for”循环上使用“array.map/filter/reduce”；管道中的链式改造。 * 编写业务逻辑的纯函数；隔离专用模块中的副作用。 * 避免改变函数参数；返回新的对象/数组。 ## 说明 * 启用“严格”模式；具有接口和类型的模型数据。强类型可以在编译时捕获错误。 * 每个代码路径都会返回一个值或抛出异常；默认使用详尽的“switch”和“never”检查。未处理的情况会成为编译错误。 * 通过上下文传播错误；捕获需要重新抛出或返回有意义的结果。隐藏的故障会延迟调试。 * 显式处理边缘情况：空数组、空/未定义输入、边界值。防御性检查可防止运行时出现意外。 * 使用`await`进行异步调用；使用上下文错误消息包装外部调用。未处理的拒绝会导致节点进程崩溃。 * 更改逻辑时添加或更新重点测试；测试行为，而不是实现细节。 ## 示例未实现逻辑的显式失败：导出函数 buildWidget(widgetType: string): never { 抛出新错误（`buildWidget 未实现类型：${widgetType}`）； } 详尽的开关，从不检查：类型状态=“活动”| “不活跃”；导出函数 processStatus(status: Status): string { 开关（状态）{ 案例“活跃”：返回“处理中”；案例“不活动”：返回“跳过”；默认值：{ const _exhaustive：从不=状态； throw new Error(`未处理状态：${_exhaustive}`); } } } 用上下文包装外部调用：导出异步函数 fetchWidget(id: string): Promise { const 响应 =等待 fetch(`/api/widgets/${id}`); 如果（！response.ok）{ 抛出新错误（`获取小部件 ${id} 失败：${response.status}`）； } 返回response.json(); } 使用命名空间记录器调试日志记录：从“调试”导入调试； const log = debug("myapp:widgets"); 导出函数 createWidget(name: string): Widget { log("正在创建小部件：%s"，名称); const widget = { id: crypto.randomUUID(), 名称 }; log("已创建小部件：%s", widget.id); 返回小部件； } ## 使用 Zod 进行运行时验证 (v4) * 将模式定义为单一事实来源；使用 z.infer<> 推断 TypeScript 类型。避免重复的类型和模式。 * 在预计会失败的情况下使用“safeParse”进行用户输入；在信任边界使用“parse”，其中无效数据是一个错误。 * 使用 `.extend()`、`.pick()`、`.omit()`、`.merge()` 来构建 DRY 定义的模式。 * 添加 `.transform()` 以在解析时进行数据标准化（修剪字符串、解析日期）。 * 包含描述性错误消息；使用 .refine() 进行自定义验证逻辑。 ### Zod 4 顶级验证器（新代码必需）与链式字符串方法相比，更喜欢 Zod 4 顶级验证器： // ✅ Zod 4：顶级验证器 z.email() z.url() z.uuid() // ❌ Zod 3 旧版（仍然有效，但更喜欢上面的） z.string().email() z.string().url() z.string().uuid() 错误消息使用“error”而不是“message”： // ✅ 佐德 4 z.email({ error: "电子邮件格式无效" }) z.string().min(1, { 错误: "必需" }) // ❌ Zod 3 遗产 z.string().email({ message: "电子邮件格式无效" }) ### 示例模式作为类型推断的事实来源：从“zod”导入{z}； const UserSchema = z.object({ id: z.uuid(), 电子邮件：z.email(), 名称：z.string().min(1), 创建时间：z.string().transform((s) => new Date(s)), }); type User = z.infer; 将解析结果返回给调用者（永远不要吞下错误）：从“zod”导入{z，SafeParseReturnType}；导出函数 parseUserInput(raw:unknown): SafeParseReturnType { 返回 UserSchema.safeParse(raw); } // 调用者处理成功和错误： const 结果 = parseUserInput(formData); 如果（！结果。成功）{ setErrors(result.error.flatten().fieldErrors); 返回; } 等待提交用户（结果.数据）；在信任边界进行严格解析：导出异步函数 fetchUser(id: string): Promise { const 响应 =等待 fetch(`/api/users/${id}`); 如果（！response.ok）{ throw new Error(`获取用户 ${id} 失败：${response.status}`); } const data =等待response.json(); 返回 UserSchema.parse(data); // 如果违反 API 契约则抛出异常 } 架构组成： const CreateUserSchema = UserSchema.omit({ id: true,createdAt: true }); const UpdateUserSchema = CreateUserSchema.partial(); const UserWithPostsSchema = UserSchema.extend({ 帖子：z.array(PostSchema), }); ＃＃配置 * 启动时从环境变量加载配置；使用前请通过 Zod 进行验证。无效的配置应该立即崩溃。 * 将类型化配置对象定义为单一事实来源；避免在整个代码库中访问“process.env”。 * 使用合理的默认值进行开发；需要生产秘密的明确值。 ### 示例使用 Zod 验证输入配置：从“zod”导入{z}； const ConfigSchema = z.object({ 端口: z.coerce.number().default(3000), DATABASE_URL: z.url(), API_KEY: z.string().min(1), NODE_ENV: z.enum(["开发", "生产", "测试"]).default("开发"), }); 导出 const config = ConfigSchema.parse(process.env); 访问配置值（不是直接访问 process.env）：从“./config”导入{config}； const server = app.listen(config.PORT); const db = connect(config.DATABASE_URL); ## 可选：类型盛宴对于 TypeScript 内置函数之外的高级类型实用程序，请考虑 [type-fest]()： * `Opaque` \- 比手动 `& { __brand }` 模式更清晰的品牌类型 * `PartialDeep` \- 嵌套对象的递归部分 * `ReadonlyDeep` \- 不可变数据的递归只读 * `LiteralUnion` \- 带有自动完成+字符串回退的文字 * `SetRequired` / `SetOptional` \- 目标字段修改 * `Simplify` \- 展平 IDE 工具提示中的复杂交集类型从 'type-fest' 导入类型 { Opaque, PartialDeep, SetRequired }; // 品牌类型（比手动方法更干净）类型 UserId = Opaque; // 补丁操作的深度部分类型 UserPatch = PartialDeep<用户>; // 指定特定字段为必填项类型 UserWithEmail = SetRequired, '电子邮件'>;

打字稿最佳实践

包含技能