typescript-rules

TypeScript 开发规则（前端）

注释编写规则

优先编写代码：名称和类型本身承载含义；注释应补充代码无法表达的内容，每项决策一条注释即可。

• 说明组件为何进行记忆化、设置保护条件或重新渲染，而不是描述 JSX 渲染了什么。
• 记录决策及其理由；按时间顺序记录历史交由版本控制处理。

类型安全

默认规则：优先使用 unknown、泛型或联合类型，而非 any。只有在现有外部、生成或旧版公共签名要求使用 any，或者替换它会导致项目类型检查无法表达安全的泛型关系时，才保留 any。记录能证明这一限制的声明路径或类型检查结果。如果在用户请求或当前任务／设计产物范围内，可以通过本地适配器保持兼容性并提供更安全的类型，就实现该适配器；否则，将 any 限制在最小的适配器或公共签名边界内，记录原因，并在不可信数据进入有类型的应用代码前进行验证。

前端边界

• React Props／State：使用已声明的应用类型。
• 外部 API 响应：将未经验证的载荷视为 unknown，并在边界处验证。如果生成的客户端也会在运行时强制执行契约，则可保留其声明类型。
• localStorage／sessionStorage：处理 string | null；在验证之前，将解析后的数据视为 unknown。
• URL 参数：处理路由器或平台的可空字符串形式，然后在转换为领域类型之前进行解析和验证。
• 导出的 API 和重要边界：声明返回类型；如果契约仍然清晰，本地实现可使用类型推断。

类型复杂度审查信号

将这些信号作为审查提示，而非通过／不通过的门槛。现有项目约定和组件职责优先。

• Props 数量：超过 10 个时，审查其归属或拆分方式。
• 可选 Props：超过一半为可选时，审查默认值或归属。
• 嵌套 Props 结构：超过 2 层时，审查是否应扁平化。
• 类型断言：需要 3 个或更多断言时，审查边界。
• 外部 API 类型：应体现实际的外部结构，并在应用边界处转换。

编码约定

组件与文件决策

• 新代码优先使用函数组件和 Hooks。除非已接受的工作要求迁移，否则保留现有可正常工作的类组件；类仍适用于实现 Error Boundary。
• 使用仓库中既定的组件、Hook 或模块模式复用逻辑。
• 遵循项目采用的组件架构和文件布局。只有在已有约定或获准采用新结构时，才将文件放在一起。

服务端／客户端边界——仅适用于 RSC 框架

• 默认在服务端获取数据并渲染；将交互功能隔离在满足需求的最小 "use client" 边界内。
• 将仅限浏览器使用的 API 和事件处理程序保留在客户端组件中。
• 如果项目没有服务端组件运行时，则跳过这些规则。

状态归属

• 保留仓库现有的本地、共享和服务端状态归属边界。
• 只有在已接受的设计要求现有边界无法表示的归属关系或生命周期时，才引入 Context、共享状态层或服务端状态依赖。
• 每个状态值只保留一个权威所有者，并使用 React 变更检测所需的不可变更新。

函数与 Props 边界

• 参数优先控制在 0 至 2 个。对于 3 个或更多相关值，如果使用对象能明确名称或表示一个领域输入，则使用对象；如果仓库约定或外部 API 有要求，则保留位置参数。
• 根据仓库既定的状态和依赖边界，通过类型化 props、Hooks、Context 或注入模块声明组件依赖。

环境变量

• 通过项目的打包工具访问器和公开前缀读取客户端环境变量。
• 通过仓库的类型化配置层验证必需值；只有对可选值或明确规定的本地开发模式，才添加默认值。

客户端安全

• 将凭据和机密保留在服务端；客户端可观察到浏览器接收的代码和公开环境变量。
• 将本地环境文件排除在版本控制之外，并确保错误输出不包含敏感值。

异步处理

• 遵循仓库的 Promise 风格；在能明确执行顺序和错误传播时使用 async/await。
• 在事件处理程序所属边界处理事件处理程序和异步操作中的失败。Error Boundary 用于处理后代渲染失败，不处理普通回调或异步工作。
• 通过仓库的取消机制或服务端状态机制，防止由 effect 触发的请求产生过期更新或卸载后的更新。

格式

• 遵循仓库的格式化工具、命名、模块解析和包边界配置。
• 仅在项目配置能够解析导入别名时使用该别名。

错误处理

每个捕获的错误都应有明确的处理结果：向上传播、转换为仓库的类型化边界结果，或表示为面向用户的错误状态。在负责诊断或恢复的边界保留上下文并仅记录一次日志，同时对敏感数据进行脱敏。

• Error Boundary：将其放置在能够为后代渲染失败提供明确 UI 恢复结果的位置。
• 自定义 Hook：保留应用程序现有的错误约定。
• API 层：将传输失败转换为仓库既定的领域表示或边界表示。
• 事件处理程序和异步工作流：使用所属层的异常、结果或 UI 状态约定。

性能优化

• 启用 React Compiler 时，应依赖它。只有在测得存在性能瓶颈，或外部 API／副作用边界要求保持稳定标识时，才添加手动的 React.memo、useMemo 或 useCallback。
• 当配置的打包体积预算出现退化，或已接受的任务将打包体积列为预期结果且仓库打包报告指出相关增量由更改的导入导致时，才进行代码拆分或调整导入。遵循仓库现有的加载模式，并在更改后验证同一指标。

非功能性需求

• 浏览器兼容性：按照 PRD、设计文档、Browserslist 或构建配置中的支持策略进行实现。如果这些内容均未定义，则保留仓库当前的转译／polyfill 基线，并将任何新的浏览器依赖 API 作为待解决的兼容性决策提出。
• 性能：根据项目定义的预算和代表受影响体验的指标进行验证。如果没有预算，则测量更改后的路径并报告观察到的结果，而不是自行设定阈值。