TypeScript 开发规则（前端）

TypeScript 开发规则（前端）

前端专属的 React/TypeScript 实现规则：阈值、边界类型安全、组件/状态设计、错误处理与项目约定。

前置条件检测

在应用某项项目约定之前，先检查 TypeScript、打包器/框架、lint/format、路径别名以及具有代表性的组件配置。当配置或既有仓库模式支持某项约定时，将其视为已观察到；仅凭少量示例得出的结论应标注为推断。当存在相互冲突的模式，且会影响公共行为、兼容性或组件边界时，应停下来指出所需的权威来源或决策点。

反模式与阈值

触发设计调整的信号：

• Prop 透传超过 3 层 → 提升到 Context 或状态管理
• 组件超过 300 行 → 拆分
• Props 数量超过 10 个 → 拆分组件（3-7 个为合理区间）
• 可选 props 超过 50% → 引入默认值或 Context
• Props 嵌套超过 2 层 → 拉平

边界处的类型安全

将不可信或类型未知的数据接收为 unknown，并通过类型守卫进行收窄。仅当运行时/框架不变量能够证明所断言的类型时才使用 as，并在附近注释中记录该不变量。既有的生成代码或第三方声明中包含 any 属于需要包装的边界输入，而不是在应用契约中扩散 any 的理由。

在应用内部，React Props/State 已由类型保证——无需 unknown。在每一个外部边界处，先接收为 unknown，再通过类型守卫收窄后使用：API 响应、localStorage/sessionStorage、URL 参数、解析后的 JSON。受控组件的表单输入通过 React 合成事件保持类型安全。

const raw: unknown = await (await fetch(url)).json()
if (!isUser(raw)) throw new ValidationError('invalid user')
const user = raw // 已收窄为 User

组件与状态设计

• 仅使用函数组件。 类组件仅允许用于 Error Boundary（不存在对应的 Hook 方案）
• 显式为 Props 定义类型，使用具名类型并解构：function UserCard({ user, onSelect }: UserCardProps)。直接在函数上标注 props 类型，使 props 契约保持显式
• Props 驱动： 当有一个明确的父组件拥有依赖项时，通过 props 传递。当多个非相邻的后代组件共享该值、且逐层传递 props 会引入无所有权作用的中间组件时，使用 Context 或既有的全局状态方案
• 自定义 Hook 是逻辑复用与依赖注入的基本单元（通过 Hook 注入协作对象以提升可测试性）
• 函数参数： 0-2 个使用位置参数；3 个及以上使用单一 options 对象
• State 结构： 显式定义 state 类型；对于具有离散转换的多字段 state，使用带判别联合 action 类型的 useReducer，而不是大量 useState 调用
• 服务端/客户端边界（仅限 RSC 框架，例如 Next.js App Router）：数据获取/渲染默认使用服务端组件，将交互逻辑隔离在所需最小范围的 "use client" 边界之后；仅浏览器可用的 API（window、localStorage、事件处理函数）应保留在客户端组件内，因为在服务端组件中调用它们会破坏渲染。纯客户端 SPA（例如 Vite）没有服务端组件运行时，因此可跳过此项

错误处理

• 为每个错误设定一个明确的处理结果：将其转换为带类型的预期失败、在所属的 UI 边界处处理，或连同其诊断上下文一并向上传播。在拥有可观测性职责的层级记录日志，避免同一个失败被重复记录
• 快速失败： 遇到无效状态时应抛出异常，而不是静默返回兜底值
• 使用 Result 类型将预期内的失败表示为值；将 throw 保留给非预期/不可恢复的情况