用途
这是一套适用于所有项目的通用编码规范与最佳实践，主要面向 TypeScript、JavaScript、React 和 Node.js 开发。它通过正反示例对比，帮助团队统一代码风格、提升可读性、可维护性与可重构信心。
主要能力
代码质量原则
- 可读性优先：代码被阅读的次数多于被编写，强调清晰的变量与函数命名、自文档化代码优于注释、格式一致。
- KISS：采用能工作的最简单方案，避免过度工程与过早优化，易懂优于炫技。
- DRY：将公共逻辑抽取为函数、创建可复用组件、跨模块共享工具，避免复制粘贴式编程。
- YAGNI：不在需要之前构建功能，避免推测性通用化，从简单开始，需要时再重构。
TypeScript / JavaScript 规范
- 变量命名：使用描述性名称（如 marketSearchQuery、isUserAuthenticated、totalRevenue），避免 q、flag、x 等含义不明的名称。
- 函数命名：采用动词-名词模式（如 fetchMarketData、calculateSimilarity、isValidEmail），避免仅用名词或含义不清的命名。
- 不可变模式（关键）：始终使用展开运算符创建新对象或数组，绝不直接修改原对象或数组。
- 错误处理：使用 try/catch 全面处理错误，检查 response.ok 并抛出带状态码的错误，避免无错误处理的裸调用。
- 异步最佳实践：在可能时使用 Promise.all 并行执行，避免不必要的顺序 await。
- 类型安全：使用明确的 interface 与联合类型，避免使用 any。
React 最佳实践
- 组件结构：使用带类型的函数式组件，为 props 定义 interface，提供默认值。
- 自定义 Hooks：抽取可复用逻辑，如 useDebounce 示例。
- 状态管理：基于前值更新状态时使用函数式更新（setCount(prev => prev + 1)），避免直接引用可能过期的状态。
- 条件渲染：使用清晰的 && 表达式，避免三元表达式嵌套地狱。
API 设计规范
- REST 约定：列出 GET、POST、PUT、PATCH、DELETE 的标准用法，以及查询参数过滤方式。
- 响应格式：统一的 ApiResponse<T> 结构，包含 success、data、error、meta 字段。
- 输入校验：使用 zod 定义 Schema 并解析请求体，返回带 details 的校验失败响应。
文件组织
- 项目结构：给出 src/ 下 app、components、hooks、lib、types、styles 的目录划分示例。
- 文件命名：组件用 PascalCase，Hooks 用 camelCase 且以 use 前缀，工具用 camelCase，类型文件加 .types 后缀。
注释与文档
- 注释时机：解释“为什么”而非“是什么”，避免陈述显而易见的内容。
- 公共 API 的 JSDoc：包含参数、返回值、抛出异常与示例。
性能最佳实践
- 记忆化：使用 useMemo 缓存昂贵计算，useCallback 缓存回调。
- 懒加载：使用 lazy 与 Suspense 懒加载重型组件。
- 数据库查询：只选择需要的列，避免 select('*')。
测试规范
- 测试结构：采用 AAA（Arrange-Act-Assert）模式。
- 测试命名：使用描述性名称，说明具体行为与边界条件。
代码坏味道识别
- 长函数：超过 50 行应拆分为更小的函数。
- 深层嵌套：5 层以上嵌套应改用提前返回。
- 魔法数字：应替换为具名常量。
使用方式
资料未提供具体的安装命令、配置方式或集成步骤，暂未提供。内容以规范条文与代码示例形式呈现，可直接作为团队编码约定参考。
适用场景
适用于使用 TypeScript、JavaScript、React 和 Node.js 的项目，尤其是需要统一多人协作代码风格、进行代码审查或重构的团队。
限制
资料未说明该规范的强制程度、工具链集成方式、版本适用范围或与特定框架的兼容性细节，暂未提供。