用途 这是一套适用于 TypeScript、JavaScript、React 和 Node.js 开发的通用编码标准、最佳实践与模式集合，可用于在多个项目中统一代码风格与工程质量。
何时启用
- 启动新项目或模块时
- 为了质量和可维护性进行代码审查时
- 重构现有代码以遵循规范时
- 强制执行命名、格式或结构的一致性时
- 设置 linting、格式化或类型检查规则时
- 引导新贡献者了解编码规范时
代码质量原则
- 可读性优先：代码被阅读的次数远多于编写的次数，变量与函数命名应清晰明确，优先选择自描述代码而非依赖注释，保持一致格式化风格。
- KISS：采用最简单的可行方案，避免过度设计，不进行过早优化，易于理解胜过奇技淫巧。
- DRY：将公共逻辑提取为函数，创建可复用组件，在模块间共享工具函数，避免复制粘贴式编程。
- YAGNI：不要在功能被需要之前就构建它，避免投机性的通用设计，仅在必要时增加复杂性，从简单开始按需重构。
TypeScript/JavaScript 规范
- 变量命名：使用描述性命名（如 marketSearchQuery、isUserAuthenticated、totalRevenue），避免含义不明的 q、flag、x。
- 函数命名：采用动词-名词模式（fetchMarketData、calculateSimilarity、isValidEmail），避免仅有名词或不清晰的命名。
- 不可变性：始终使用展开运算符创建新对象/数组；严禁直接修改（mutate）现有对象或数组。
- 错误处理：使用 try/catch，检查 response.ok，抛出带状态信息的错误，并避免无错误处理的异步请求。
- Async/Await：尽可能使用 Promise.all 并行执行；避免非必要的串行等待。
- 类型安全：定义正确的 interface 与返回类型；避免滥用 any。
React 最佳实践
- 组件结构：使用带类型的函数式组件与显式 Props 接口，为可选属性提供默认值。
- 自定义 Hook：以 use 开头，返回可复用逻辑（如 useDebounce）。
- 状态管理：使用函数式更新（setCount(prev => prev + 1)），避免直接引用状态导致闭包过期。
- 条件渲染：使用清晰的条件表达式，避免嵌套三元运算符。
API 设计规范
- REST 约定：GET/POST/PUT/PATCH/DELETE 按资源路径组织，使用查询参数进行过滤（status、limit、offset）。
- 响应格式：使用统一的 ApiResponse<T> 结构，包含 success、data、error、meta 等字段。
- 输入验证：使用 zod 定义 Schema，对请求体进行验证并返回结构化错误信息。
文件组织
- 项目结构：以 src 为根，划分 app、components、hooks、lib、types、styles 等目录，组件按 ui、forms、layouts 分类。
- 文件命名：组件使用 PascalCase，Hook 以 use 开头使用 camelCase，工具函数使用 camelCase，类型文件带 .types 后缀。
注释与文档
- 解释“为什么”而非“是什么”，避免陈述显而易见的事实。
- 对公共 API 使用 JSDoc，包含参数、返回值、异常与示例。
性能最佳实践
- 记忆化：使用 useMemo 缓存昂贵计算，useCallback 缓存回调。
- 延迟加载：使用 lazy 与 Suspense 延迟加载大型组件。
- 数据库查询：仅选择需要的列，避免全量查询。
测试规范
- 使用 AAA（Arrange-Act-Assert）模式组织测试。
- 使用描述性的测试名称，说明具体行为与预期结果，避免模糊命名。
代码异味检测 注意过长函数（超过 50 行应拆分）、过深嵌套（使用及早返回）与魔数（改为命名常量）。
限制 资料中未提供该技能的安装命令、运行环境要求、授权方式、收费信息或与其他工具的集成方式，这些事实暂未提供。