coding-standards

name	coding-standards
description	编码规范和最佳实践。适用于所有语言和框架的通用编码标准。

编码标准技能

提供通用编码规范和最佳实践指导。

代码组织

文件大小

• 每文件 200-400 行（典型）
• 最大 800 行
• 更多小文件优于少数大文件

组织方式

• 按功能/领域组织
• 高内聚，低耦合
• 清晰的模块边界

src/
├── features/           # 按功能组织
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── services/
│   └── users/
├── shared/             # 共享组件
└── lib/                # 工具库

命名约定

变量和函数

// camelCase
const userName = "john"
function getUserById(id: string) {}

类和接口

// PascalCase
class UserService {}
interface UserData {}
type CreateUserInput = {}

常量

// UPPER_SNAKE_CASE
const MAX_RETRY_COUNT = 3
const API_BASE_URL = "https://api.example.com"

文件名

// kebab-case.ts
user-service.ts
create-user-form.tsx

函数设计

单一职责

每个函数只做一件事

大小限制

• 最大 50 行
• 如果更长，拆分成子函数

参数数量

• 最多 3-4 个参数
• 更多参数使用对象

// ❌ 太多参数
function createUser(name, email, age, role, team, manager) {}

// ✅ 使用对象
function createUser(options: CreateUserOptions) {}

错误处理

始终使用 try/catch

async function fetchUser(id: string) {
  try {
    const response = await api.get(`/users/${id}`)
    return { success: true, data: response.data }
  } catch (error) {
    console.error('获取用户失败:', error)
    return { success: false, error: '无法获取用户信息' }
  }
}

用户友好的错误消息

• 不暴露技术细节
• 提供有用的建议

不可变性

禁止直接修改

// ❌ 修改原始对象
user.name = "new name"
users.push(newUser)

// ✅ 创建新对象
const updatedUser = { ...user, name: "new name" }
const updatedUsers = [...users, newUser]

禁止事项

• ❌ 硬编码值（使用常量或配置）
• ❌ 魔法数字（给数字命名）
• ❌ 深度嵌套（>4 层）
• ❌ 重复代码（提取函数）
• ❌ any 类型（使用具体类型）
• ❌ console.log 在生产代码中