javascript

📜 JavaScript 开发规则

版本: v4.3.0 | 最后更新: 2026-01-22 | 作者: Cursor AI Rules

🎯 适用场景

• Node.js 后端开发
• 浏览器前端开发
• 服务端 JavaScript 应用
• 命令行工具和脚本
• 跨平台桌面应用
• 嵌入式 JavaScript 运行时

🏗️ 架构原则

模块化设计

• ES6 模块: 优先使用 import/export
• CommonJS: Node.js 环境下的模块系统
• 清晰的模块边界: 每个模块职责单一
• 依赖注入: 避免硬编码依赖关系

代码组织

• 关注点分离: 业务逻辑、数据访问、表示层分离
• 单一职责: 每个函数、类、模块只做一件事
• 开闭原则: 对扩展开放，对修改关闭

📝 编码规范

命名约定

// ✅ 推荐 - 变量和函数
const userName = 'john_doe'
const isUserActive = true
let currentUser = null

function getUserById(userId) {
  // 函数体
}

function calculateTotalPrice(items) {
  // 函数体
}

// ✅ 推荐 - 常量
const MAX_RETRY_COUNT = 3
const API_BASE_URL = 'https://api.example.com'
const DEFAULT_TIMEOUT = 5000

// ✅ 推荐 - 类和构造函数
class UserManager {
  constructor() {
    this.users = []
  }

  addUser(user) {
    this.users.push(user)
  }

  findUserById(id) {
    return this.users.find(user => user.id === id)
  }
}

// ❌ 避免 - 不一致的命名
const user_name = 'john'      // 使用 camelCase
const is_user_active = true   // 使用 camelCase
let CurrentUser = null        // 使用 camelCase

函数设计

• 单一职责: 每个函数只做一件事
• 参数限制: 最多3-4个参数，考虑使用对象参数
• 纯函数优先: 无副作用的函数更容易测试和推理

// ✅ 好的函数设计
function calculateUserScore(activities) {
  return activities
    .filter(activity => activity.completed)
    .reduce((score, activity) => score + activity.points, 0)
}

// ✅ 参数对象化
function createUser({ name, email, age, role = 'user' }) {
  return {
    id: generateId(),
    name,
    email,
    age,
    role,
    createdAt: new Date()
  }
}

// ❌ 避免的函数设计
function processUserData(user, options = {}) {
  // 参数太多且类型不明确
  if (options.validate) {
    // 验证逻辑
  }
  if (options.save) {
    // 保存逻辑
  }
  if (options.notify) {
    // 通知逻辑
  }
  // 做了太多事情
}

🔧 工具链配置

ESLint 配置

{
  "env": {
    "browser": true,
    "node": true,
    "es2021": true
  },
  "extends": [
    "eslint:recommended",
    "prettier"
  ],
  "rules": {
    "no-unused-vars": ["error", { "argsIgnorePattern": "^_" }],
    "no-console": "warn",
    "prefer-const": "error",
    "no-var": "error"
  },
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  }
}