shinpr TypeScript 开发规则（前端）
前端专属的 React/TypeScript 实现规则：阈值、边界类型安全、组件/状态设计、错误处理与项目约定。
前置条件检测
在应用某项项目约定之前，先检查 TypeScript、打包器/框架、lint/format、路径别名以及具有代表性的组件配置。当配置或既有仓库模式支持某项约定时，将其视为已观察到；仅凭少量示例得出的结论应标注为推断。当存在相互冲突的模式，且会影响公共行为、兼容性或组件边界时，应停下来指出所需的权威来源或决策点。
反模式与阈值
触发设计调整的信号：
- Prop 透传超过 3 层 → 提升到 Context 或状态管理
- 组件超过 300 行 → 拆分
- Props 数量超过 10 个 → 拆分组件（3-7 个为合理区间）
- 可选 props 超过 50% → 引入默认值或 Context
- Props 嵌套超过 2 层 → 拉平
- 相同的
as断言出现 3 次以上 → 重新审视类型设计
边界处的类型安全
将不可信或类型未知的数据接收为 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保留给非预期/不可恢复的情况 - 使用继承自基类
AppError的专用错误类，携带code（例如 ValidationError、ApiError、NotFoundError） - 各层职责： API 层将传输层错误转换为领域错误；Hook 向上传播
AppError；Error Boundary 捕获渲染期错误并展示兜底 UI - Effect 竞态/清理： 对
useEffect中的数据获取要防范乱序响应与卸载后的状态更新——中止或忽略过期结果（使用AbortController或挂载标志），或使用能自动取消与去重的服务端状态库（React Query/SWR）。仅靠try-catch无法覆盖这类情况 - 仅记录当前信任边界所允许的诊断字段；记录日志前应对凭证、令牌、支付数据等敏感值进行脱敏
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 ——唯一必须使用类组件的场景：
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，分号与代码风格以其项目配置为准