用途
这是一套适用于跨项目的基线编码约定,作为共享的“底线”,而不是某个框架的详细操作手册。它用于在多个项目之间统一命名、可读性、不可变性和代码质量审查标准。
当出现以下情况时激活本技能:
- 启动新项目或新模块
- 审查代码质量与可维护性
- 按约定重构既有代码
- 强制命名、格式或结构一致性
- 配置 lint、格式化或类型检查规则
- 帮助新贡献者了解编码约定
范围边界
本技能适用于:描述性命名、默认不可变性、可读性、KISS、DRY、YAGNI 的执行、错误处理预期与代码坏味道审查。
本技能不作为以下内容的主要来源:React 组合、Hook 或渲染模式;后端架构、API 设计或数据库分层;当已有更窄的 ECC 技能存在时,特定领域的框架指导。
相关技能指引:React、状态、表单、渲染与 UI 架构使用 frontend-patterns;仓储/服务层、端点设计、校验与服务端问题使用 backend-patterns 或 api-design;需要最短可复用规则层而非完整技能讲解时,使用 rules/common/coding-style.md。
代码质量原则
- 可读性优先:代码被阅读的次数多于被编写;变量与函数命名清晰;优先自文档化代码而非注释;格式一致。
- KISS(保持简单):采用能工作的最简单方案;避免过度工程;不做过早优化;易理解优于炫技。
- DRY(不要重复自己):把公共逻辑抽取为函数;创建可复用组件;跨模块共享工具;避免复制粘贴式编程。
- YAGNI(你不会需要它):不要提前构建尚未需要的功能;避免推测性通用化;只在需要时增加复杂度;从简单开始,需要时再重构。
TypeScript/JavaScript 标准
变量命名:使用描述性名称,例如 marketSearchQuery、isUserAuthenticated、totalRevenue;避免 q、flag、x 这类不清晰名称。
函数命名:采用动词-名词模式,例如 fetchMarketData、calculateSimilarity、isValidEmail;避免仅名词或不清晰的命名。
不可变模式(关键):始终使用展开运算符创建新对象或数组,例如 { ...user, name: 'New Name' }、[...items, newItem];绝不直接修改,例如 user.name = 'New Name'、items.push(newItem)。
错误处理:使用 try/catch,检查 response.ok,抛出带状态信息的错误,并在捕获后记录并重新抛出统一错误;避免无错误处理的直接返回。
Async/Await:在可能时使用 Promise.all 并行执行;避免不必要的顺序等待。
类型安全:定义明确接口,例如 Market 含 id、name、status、created_at;避免使用 any。
React 最佳实践
组件结构:使用带类型的函数组件,定义 ButtonProps(children、onClick、disabled?、variant?),并提供默认值;避免无类型、结构不清的组件。
自定义 Hook:可复用 Hook 示例 useDebounce<T>(value, delay),内部用 useState 与 useEffect 配合 setTimeout 和清理函数,返回防抖值。
状态管理:基于先前状态更新时使用函数式更新,例如 setCount(prev => prev + 1);避免直接引用可能过期的状态值。
条件渲染:使用清晰的 && 表达式分别渲染加载、错误与数据;避免多层三元嵌套。
API 设计标准
REST 约定:GET /api/markets 列表、GET /api/markets/:id 获取、POST /api/markets 创建、PUT /api/markets/:id 全量更新、PATCH /api/markets/:id 部分更新、DELETE /api/markets/:id 删除;过滤使用查询参数,如 ?status=active&limit=10&offset=0。
响应格式:统一结构 ApiResponse<T>,含 success、data?、error?、meta?(total、page、limit);成功与错误分别返回对应 JSON 与状态码。
输入校验:使用 Zod 定义 schema,例如 CreateMarketSchema 含 name、description、endDate、categories;在 POST 中解析并捕获 ZodError,返回校验失败详情与 400 状态码。
文件组织
项目结构示例:src/ 下含 app/(api/、markets/、(auth)/)、components/(ui/、forms/、layouts/)、hooks/、lib/(api/、utils/、constants/)、types/、styles/。
文件命名:组件用 PascalCase,如 components/Button.tsx;Hook 用 camelCase 加 use 前缀,如 hooks/useAuth.ts;工具用 camelCase,如 lib/formatDate.ts;类型用 camelCase 加 .types 后缀,如 types/market.types.ts。
注释与文档
注释应解释“为什么”而非“是什么”,例如说明指数退避的原因或刻意使用变更的性能考量;避免陈述显而易见的内容。公共 API 使用 JSDoc,包含参数、返回值、抛出异常与示例。
性能最佳实践
Memoization:使用 useMemo 记忆昂贵计算(排序前先复制数组,因为 sort 会原地修改),使用 useCallback 记忆回调。
懒加载:使用 lazy 与 Suspense 懒加载重型组件,并提供 fallback。
数据库查询:只选择需要的列,例如 select('id, name, status') 并加 limit;避免 select('*')。
测试标准
测试结构采用 AAA 模式:Arrange、Act、Assert。测试命名应描述行为,例如“当没有市场匹配查询时返回空数组”“当缺少 OpenAI API 密钥时抛出错误”“当 Redis 不可用时回退到子串搜索”;避免“works”“test search”这类模糊名称。
代码坏味道识别
关注以下反模式:长函数(超过 50 行应拆分为更小函数);深层嵌套(5 层以上应改用提前返回);魔法数字(应改为命名常量,如 MAX_RETRIES、DEBOUNCE_DELAY_MS)。
代码质量不可妥协:清晰、可维护的代码能支撑快速开发与有信心的重构。