用途
本技能提供一套可跨项目复用的通用编码规范与最佳实践,主要面向 TypeScript、JavaScript、React 和 Node.js 开发场景。其目标是通过统一的命名、结构、错误处理、类型、API 设计与测试约定,让代码更易读、易维护、易重构。
主要能力
代码质量原则
- 可读性优先:代码被阅读的次数多于被编写,强调清晰的变量与函数命名、自文档化代码优于注释、格式一致。
- KISS:采用能工作的最简方案,避免过度工程与过早优化,易懂优于炫技。
- DRY:将公共逻辑抽取为函数、创建可复用组件、跨模块共享工具,避免复制粘贴。
- YAGNI:不提前构建尚未需要的功能,避免推测性通用化,从简单开始,需要时再重构。
TypeScript/JavaScript 规范
- 变量命名:使用描述性名称(如 marketSearchQuery、isUserAuthenticated),避免 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,提供默认值(如 disabled = false、variant = 'primary')。
- 自定义 Hook:抽取可复用逻辑,例如 useDebounce 泛型 Hook,配合 useEffect 清理定时器。
- 状态管理:基于前值更新时使用函数式更新(setCount(prev => prev + 1)),避免直接引用可能过期的状态。
- 条件渲染:使用清晰的 && 表达式分别渲染加载、错误与数据状态,避免多层三元嵌套。
API 设计规范
- REST 约定:GET 列表/详情、POST 创建、PUT 全量更新、PATCH 部分更新、DELETE 删除;使用查询参数过滤(如 ?status=active&limit=10&offset=0)。
- 响应格式:统一结构,包含 success、data、error 与 meta(total、page、limit);错误响应返回对应 HTTP 状态码。
- 输入校验:使用 zod 定义 Schema(如 CreateMarketSchema),在 POST 中解析请求体,捕获 ZodError 并返回校验失败详情。
文件组织与命名
- 项目结构示例:src/app(Next.js App Router,含 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),类型用 camelCase 加 .types 后缀(market.types.ts)。
注释与文档
- 注释解释“为什么”而非“是什么”,例如说明使用指数退避的原因或刻意使用可变操作以提升大数组性能。
- 公共 API 使用 JSDoc,包含参数、返回值、抛出异常与示例。
性能最佳实践
- 使用 useMemo 缓存昂贵计算、useCallback 缓存回调。
- 使用 lazy 与 Suspense 懒加载重型组件。
- 数据库查询只选择需要的列,避免 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 项目的日常开发,尤其适合需要统一团队代码风格、进行代码评审、重构遗留代码或建立项目规范的场景。
限制
资料未说明该技能的运行环境、依赖、版本要求、收费情况或平台支持范围,暂未提供。