TTMusic/.cursor/rules/cursorrules.mdc

---
description: 
globs: 
alwaysApply: true
---
# 鸿蒙ArkTS编程规则与最佳实践

## 语法差异规则：ArkTS vs TypeScript

### 1. 空值检查规则
```typescript
// ❌ 错误: 未对可能为null的对象执行检查
this.dbObject.executeSql(sql);

// ✅ 正确: 执行null检查
if (this.dbObject) {
  this.dbObject.executeSql(sql);
}
```

### 2. 解构赋值规则
```typescript
// ❌ 错误: ArkTS不支持解构赋值语法
for (const [key, value] of Object.entries(obj)) {
  // 处理逻辑
}

// ✅ 正确: 使用传统循环方式
const keys = Object.keys(obj);
for (let i = 0; i < keys.length; i++) {
  const key = keys[i];
  const value = obj[key];
  // 处理逻辑
}
```

### 3. 异步API调用规则
```typescript
// ❌ 错误: 回调参数类型不匹配
dbStore.executeSql(sql, (err, result: ResultSet) => {
  // 处理逻辑
});

// ✅ 正确: 使用Promise模式
dbStore.executeSql(sql)
  .then(() => {
    // 成功处理
  })
  .catch((err: Error) => {
    // 错误处理
    console.log(err.message);
  });
```

### 4. 计算属性名规则
```typescript
// ❌ 错误: 不支持计算属性名语法
const obj = { [CONSTANT.KEY]: value };

// ✅ 正确: 使用对象属性赋值语法
const obj = {};
obj[CONSTANT.KEY] = value;
```

### 5. 数据类型规则
```typescript
// ❌ 错误: 使用any或未指定泛型类型
const items = new Set();
const map = new Map();

// ✅ 正确: 明确指定泛型类型
const items = new Set<string>();
const map = new Map<string, number>();
```

### 6. 错误对象类型规则
```typescript
// ❌ 错误: 使用隐式any类型的错误对象
try {
  // 代码
} catch (e) {
  console.log(`错误: ${e}`);
}

// ✅ 正确: 明确指定错误对象的类型
try {
  // 代码
} catch (e: Error) {
  console.log(`错误: ${e.message}`);
}
```

## 数据库操作最佳实践

### 1. 表结构升级
```typescript
// ❌ 错误: 依赖回调处理的表结构升级
this.rdbStore.executeSql(tableInfoQuery, (err, result) => {
  // 处理逻辑
});

// ✅ 正确: 使用Promise模式并独立处理每个列的添加操作
this.rdbStore.executeSql(tableInfoQuery)
  .then(() => {
    // 为每个需要添加的列单独执行ALTER TABLE
    Object.keys(columnsToAdd).forEach(column => {
      const type = columnsToAdd[column];
      this.rdbStore.executeSql(`ALTER TABLE ${tableName} ADD COLUMN ${column} ${type}`)
        .then(() => { /* 成功处理 */ })
        .catch((err: Error) => { /* 错误处理 */ });
    });
  });
```

### 2. 资源释放
```typescript
// ❌ 错误: 未关闭ResultSet
this.rdbStore.query(predicates, (resultSet) => {
  // 处理逻辑
});

// ✅ 正确: 确保关闭ResultSet
this.rdbStore.query(predicates, (resultSet) => {
  try {
    // 处理逻辑
  } finally {
    resultSet.close();
  }
});
```

## 对象字面量规则

### 1. 复杂对象初始化
```typescript
// ❌ 错误: 不支持复杂对象字面量初始化
const config = {
  complex: {
    nested: {
      value: someValue
    }
  }
};

// ✅ 正确: 分步创建复杂对象
const config = {};
config.complex = {};
config.complex.nested = {};
config.complex.nested.value = someValue;
```

## 命名规范

- 类名: PascalCase (例如 MediaTable)
- 方法名: camelCase (例如 queryByParentPath)
- 常量: UPPER_SNAKE_CASE (例如 DB_COLUMNS.FILE_PATH)
- 私有属性: _camelCase (例如 _dbStore)