coding-standards

Coding Standards - TypeScript/JavaScript/React 通用编码规范

技能概述

Coding Standards 提供了一套适用于 TypeScript、JavaScript、React 和 Node.js 开发的通用编码规范和最佳实践，涵盖代码质量原则、命名规范、错误处理、性能优化和测试标准。

适用场景

1. 团队协作与代码审查

当团队需要统一的编码标准时，这套规范可以作为代码审查的检查清单。它包含了变量命名、函数命名、组件结构等明确的最佳实践，帮助团队成员保持代码风格一致。

2. 新项目初始化与架构设计

在开始新项目时，可以参考其中的项目结构、文件命名规范和 API 设计标准，确保项目从一开始就具备良好的可维护性和扩展性。

3. 代码重构与质量提升

当需要重构现有代码或提升代码质量时，可以参考其中的代码异味检测、性能最佳实践和测试标准，识别并修复代码中的问题。

核心功能

1. 代码质量原则指南

提供四大核心原则：可读性优先、KISS（保持简单）、DRY（避免重复）和YAGNI（不过度设计）。这些原则帮助开发者做出更好的架构决策，避免过度工程化。

2. TypeScript/JavaScript 编码规范

涵盖变量命名、函数命名、类型安全、错误处理和异步编程模式。特别强调不可变性模式，推荐使用 spread 操作符而非直接修改数据，这是 React 开发中的关键实践。

3. React 最佳实践

包括组件类型定义、自定义 Hook 编写、状态管理和条件渲染模式。提供了 functional component 类型定义的完整示例，以及 useDebounce 等实用 Hook 的实现。

4. API 设计标准

规范 REST API 的路由命名、HTTP 方法使用、响应格式和输入验证。使用 Zod 进行 Schema 验证的示例确保了 API 的健壮性。

5. 性能与测试优化

包含 memoization、lazy loading、数据库查询优化等性能实践，以及 AAA（Arrange-Act-Assert）测试模式，帮助开发者编写高质量的测试代码。

6. 代码异味检测

识别常见的反模式，如过长函数、深度嵌套和魔法数字，并提供相应的重构建议。

常见问题

什么是不可变性模式，为什么 TypeScript/React 推荐使用？

不可变性模式是指不直接修改现有对象或数组，而是创建新的副本。在 TypeScript 中使用 spread 操作符（...）实现：

const updatedUser = { ...user, name: 'New Name' }
const updatedArray = [...items, newItem]

React 推荐不可变性是因为：1）便于状态变化追踪；2）简化组件渲染逻辑；3）配合 React.memo 提升性能。

React 组件的 Props 应该如何正确定义类型？

推荐使用 interface 定义明确的类型，包括可选参数和联合类型：

interface ButtonProps {
  children: React.ReactNode
  onClick: () => void
  disabled?: boolean
  variant?: 'primary' | 'secondary'
}

这样可以获得完整的类型检查和 IDE 智能提示，避免运行时错误。

如何避免代码中的深度嵌套？

使用早期返回（Early Returns）模式，将多层嵌套的 if 语句转换为顺序的条件检查：

// ❌ 深度嵌套
if (user) {
  if (user.isAdmin) {
    if (hasPermission) { /* do something */ }
  }
}

// ✅ 早期返回
if (!user) return
if (!user.isAdmin) return
if (!hasPermission) return
// do something

这样可以显著提高代码的可读性和维护性。

什么时候应该使用 useMemo 和 useCallback？

useMemo 用于缓存昂贵的计算结果，useCallback 用于缓存函数引用避免子组件不必要的重渲染。但不要过度使用，只在确实存在性能问题时才引入。常见的使用场景包括：大数据排序、复杂计算传递给子组件的回调函数。

这套规范适用于所有项目吗？

这套规范提供了通用的最佳实践，但具体实施时需要根据项目规模、团队偏好和业务需求进行调整。例如，小型项目可能不需要严格的文件分层，而大型企业应用则需要更细致的目录结构。建议将这些规范作为起点，根据实际情况制定团队内部的编码约定。