Frontend Typescript Rules

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 合成事件保持类型安全。

typescriptCopy code
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 保留给非预期/不可恢复的情况
• 使用继承自基类 AppError 的专用错误类，携带 code（例如 ValidationError、ApiError、NotFoundError）
• 各层职责： API 层将传输层错误转换为领域错误；Hook 向上传播 AppError；Error Boundary 捕获渲染期错误并展示兜底 UI
• Effect 竞态/清理： 对 useEffect 中的数据获取要防范乱序响应与卸载后的状态更新——中止或忽略过期结果（使用 AbortController 或挂载标志），或使用能自动取消与去重的服务端状态库（React Query/SWR）。仅靠 try-catch 无法覆盖这类情况
• 仅记录当前信任边界所允许的诊断字段；记录日志前应对凭证、令牌、支付数据等敏感值进行脱敏

typescriptCopy code
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }

class AppError extends Error {
  constructor(message: string, readonly code: string, readonly statusCode = 500) {
    super(message); this.name = this.constructor.name
  }
}

Error Boundary ——唯一必须使用类组件的场景：

typescriptCopy code
class ErrorBoundary extends React.Component<{ children: React.ReactNode; fallback: React.ReactNode }, { hasError: boolean }> {
  state = { hasError: false }
  static getDerivedStateFromError() { return { hasError: true } }
  render() { return this.state.hasError ? this.props.fallback : this.props.children }
}

项目约定

• 环境变量： 通过所配置打包器暴露的访问方式读取客户端环境变量。匹配已观察到的打包器：Vite 使用 import.meta.env.VITE_*，Next.js 公共变量使用 process.env.NEXT_PUBLIC_*，CRA 使用 process.env.REACT_APP_*。前端构建产物包含公开配置；敏感值应保留在服务端边界之后
• 构建体积与性能： 使用 build 脚本对照项目预算监控构建体积；使用 React.lazy + Suspense 进行代码分割；组织状态结构以尽量减少重新渲染。记忆化（Memoization）：启用 React Compiler 时应依赖它；仅在有性能分析依据或身份稳定性依据时（经测量确认的瓶颈，或第三方 API/effect 依赖需要稳定的引用身份）才手动使用 React.memo/useMemo/useCallback 作为例外手段
• 命名： 组件/类型使用 PascalCase；变量/函数使用 camelCase；Hook 以 use 为前缀；常量使用 SCREAMING_SNAKE_CASE
• 导入： 遵循在 tsconfig、lint 配置及代表性文件中观察到的别名与导入顺序规则。仅在配置的别名支持时使用 src/ 绝对路径
• 格式化： 遵循仓库配置的格式化工具；若使用 Biome，分号与代码风格以其项目配置为准