---
description: 命名规范 - 自解释性和一致性。涉及变量、函数、文件、类命名时触发。
---

# 命名规范

该规则定义变量、函数、文件、类型的命名标准，确保代码自解释。

---

## 必须遵守

- ✅ 命名清晰表达意图，无需额外注释
- ✅ 避免缩写（除 URL、ID、API 等广泛认可的）
- ✅ 布尔值使用 `is`/`has`/`should`/`can` 前缀
- ✅ 组件文件：PascalCase（`UserCard.vue`）
- ✅ 页面文件：kebab-case（`user-list.vue`）
- ✅ 工具函数：camelCase（`formatDate.ts`）
- ✅ 类型定义：kebab-case（`user-types.ts`）
- ✅ 变量：camelCase，常量：UPPER_SNAKE_CASE
- ✅ 数组用复数（`users`），对象用单数（`user`）
- ✅ 函数用动词开头，事件处理器用 `handle` 前缀
- ✅ 组件名必须多词（避免与 HTML 元素冲突）
- ✅ Composable 使用 `use` 前缀（`useUserAuth`）
- ✅ Store 使用 `useXxxStore` 模式（`useUserStore`）
- ✅ 路由 name 使用 PascalCase（`UserProfile`）

---

## 严格禁止

- ❌ 单字母变量名（除循环索引 `i`、`j`、`k`）
- ❌ 拼音命名
- ❌ 无意义名称（`data`、`info`、`temp`、`foo`）
- ❌ 过度缩写（`usrNm`、`btnClk`）
- ❌ 误导性名称（名不副实）
- ❌ 混用命名风格
- ❌ 单词组件名（`Button.vue` → `BaseButton.vue`）
- ❌ 位置描述组件名（`TopBar` → `AppHeader`）
- ❌ 类型 I 前缀（`IUser` → `User`）

---

## 最佳实践

- 💡 使用领域语言（业务术语）
- 💡 避免冗余前缀（User 类中 `name` 而非 `userName`）
- 💡 异步函数名体现异步性（`fetchUserData`、`loadConfig`）

---

## 代码示例

### 变量与布尔值

```typescript
// ✅ 变量命名
const userList = await fetchUsers();
const activeUsers = userList.filter((u) => u.isActive);
const MAX_FILE_SIZE = 5 * 1024 * 1024;

// ✅ 布尔值命名
const isAuthenticated = !!token;
const hasPermission = user.role === "admin";
const shouldShowWelcome = isFirstLogin && isAuthenticated;

// ❌
const data = await fetchUsers();
const flag = !!token;
```

### 函数命名

```typescript
// ✅
function fetchUserById(userId: string): Promise<User> {}
function calculateTotalPrice(items: Item[]): number {}
function isUserAdmin(user: User): boolean {}

const handleClick = () => {};
const handleSubmit = async () => {};

// ❌
function user(userId: string): Promise<User> {}
function check(email: string): boolean {}
```

### 文件结构

```
components/
├── UserCard.vue         # PascalCase
├── BaseButton.vue
└── UserInfoCard.vue

pages/
├── user-list.vue        # kebab-case
├── user-detail.vue
└── order-history.vue

utils/
├── formatDate.ts        # camelCase
└── validateEmail.ts

types/
├── user-types.ts        # kebab-case
└── api-types.ts
```

### 类型命名

```typescript
// ✅
export interface User {
  id: string;
  name: string;
  role: UserRole;
}

export type UserRole = "admin" | "user" | "guest";

export interface UserListParams {
  page: number;
  pageSize: number;
  keyword?: string;
}

// ❌
export interface IUser {}
export type Role = string;
export interface Params {}
```