用途
本技能提供一套可跨项目复用的通用编码规范与最佳实践，主要面向 TypeScript、JavaScript、React 和 Node.js 开发。其目标是通过统一的命名、结构、错误处理、类型与测试约定，提升代码的可读性、可维护性与可重构信心。
主要能力
代码质量原则
- 可读性优先：代码被阅读的次数多于被编写，强调清晰的变量与函数命名、自解释代码优于注释、格式一致。
- KISS：采用能工作的最简方案，避免过度工程与过早优化，易懂优于炫技。
- DRY：将公共逻辑抽取为函数、可复用组件与共享工具，避免复制粘贴式编程。
- YAGNI：不提前构建尚未需要的功能，避免推测性通用化，从简单开始、需要时再重构。
TypeScript/JavaScript 规范
- 变量命名：使用描述性名称（如 marketSearchQuery、isUserAuthenticated、totalRevenue），避免 q、flag、x 等含义不明的名称。
- 函数命名：采用动词-名词模式（如 fetchMarketData、calculateSimilarity、isValidEmail），避免仅用名词或含义不清的命名。
- 不可变性（关键）：始终使用展开运算符创建新对象/数组（如 { ...user, name: 'New Name' }、[...items, newItem]），绝不直接修改原对象或数组。
- 错误处理：使用 try/catch，检查 response.ok 并抛出带状态码与状态文本的错误，捕获后记录并抛出统一错误信息；避免无错误处理的裸调用。
- async/await：在可并行时使用 Promise.all 并行执行，避免不必要的顺序等待。
- 类型安全：使用明确的 interface 与联合类型（如 status: 'active' | 'resolved' | 'closed'），避免使用 any。
React 最佳实践
- 组件结构：使用带类型的函数组件，为 props 定义 interface（如 children、onClick、disabled?、variant?），并提供默认值。
- 自定义 Hook：抽取可复用逻辑，示例为 useDebounce<T>(value, delay)，内部用 useState 与 useEffect 配合 setTimeout 与清理函数。
- 状态管理：基于前值更新时使用函数式更新（setCount(prev => prev + 1)），避免直接引用可能过期的状态。
- 条件渲染：使用清晰的 && 表达式分别渲染加载、错误与数据状态，避免多层嵌套三元表达式。
API 设计规范
- REST 约定：GET 列表、GET 单条、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除；使用查询参数过滤（如 ?status=active&limit=10&offset=0）。
- 响应格式：统一结构 ApiResponse<T>，包含 success、data?、error?、meta?（total、page、limit）；成功与错误响应分别返回对应状态码。
- 输入校验：使用 zod 定义 Schema（如 CreateMarketSchema，含 name、description、endDate、categories 及长度/格式约束），解析失败时返回 400 与校验详情。
文件组织
- 项目结构示例：src/ 下划分 app/（含 api/、markets/、路由组 (auth)/）、components/（ui/、forms/、layouts/）、hooks/、lib/（api/、utils/、constants/）、types/、styles/。
- 文件命名：组件用 PascalCase（Button.tsx），Hook 用 camelCase 且以 use 前缀（useAuth.ts），工具用 camelCase（formatDate.ts），类型文件用 .types 后缀（market.types.ts）。
注释与文档
- 注释原则：解释“为什么”而非“是什么”，例如说明使用指数退避以避免压垮 API、或为性能刻意使用可变操作；避免陈述显而易见的内容。
- JSDoc：为公开 API 编写 JSDoc，包含描述、@param、@returns、@throws 与 @example。
性能实践
- Memoization：使用 useMemo 缓存昂贵计算，使用 useCallback 缓存回调。
- 懒加载：使用 lazy 与 Suspense 懒加载重型组件。
- 数据库查询：只选择需要的列（如 select('id, name, status')），避免 select('*')。
测试标准
- 结构：采用 AAA 模式（Arrange、Act、Assert）。
- 命名：使用描述性测试名（如“returns empty array when no markets match query”），避免“works”“test search”等模糊命名。
代码坏味道识别
- 长函数：超过约 50 行应拆分为更小函数。
- 深层嵌套：5 层以上嵌套应改用提前返回（early return）。
- 魔法数字：使用具名常量（如 MAX_RETRIES、DEBOUNCE_DELAY_MS）替代无解释的数字。
使用方式
资料未提供具体的安装命令、调用方式或集成步骤，暂未提供。该内容以规范文档形式呈现，可作为编码参考或团队约定使用。
适用场景
适用于 TypeScript、JavaScript、React 与 Node.js 项目的日常开发，包括组件编写、API 设计、状态管理、性能优化与测试编写；也可作为代码评审与重构时的检查清单。
限制
资料未说明该技能的运行环境、依赖、版本要求、收费情况或平台支持，暂未提供。