Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# SoybeanAdmin React 命名规范
7 
8## 概述
9 
10本文档定义了 SoybeanAdmin React 项目的命名规范，旨在确保代码的一致性、可读性和可维护性。所有团队成员都应严格遵循这些规范。
11 
12## 文件和目录命名
13 
14### 📁 目录命名规范
15 
16**规则：统一使用小写字母 + 连字符（kebab-case）**
17 
18```bash
19# ✅ 正确示例
20src/
21├── components/
22├── pages/
23├── user-center/
24├── role-manage/
25├── global-header/
26├── theme-drawer/
27├── multi-menu/
28└── system-config/
29 
30# ❌ 错误示例
31src/
32├── userCenter/        # 不使用 camelCase
33├── RoleManage/        # 不使用 PascalCase
34├── global_header/     # 不使用 snake_case
35└── SYSTEM_CONFIG/     # 不使用 UPPER_CASE
36```
37 
38### 📄 文件命名规范
39 
40#### React 组件文件
41- **页面组件**：`index.tsx`
42- **动态路由**：`[id].tsx`、`[...slug].tsx`
43- **布局组件**：`layout.tsx`
44- **异步状态组件**：`loading.tsx`、`error.tsx`
45- **普通组件**：使用 PascalCase，如 `UserProfile.tsx`
46 
47```bash
48# ✅ 正确示例
49components/
50├── UserProfile.tsx
51├── GlobalHeader.tsx
52├── ThemeDrawer.tsx
53└── DataTable.tsx
54 
55pages/
56├── index.tsx
57├── [id].tsx
58├── [...slug].tsx
59├── layout.tsx
60├── loading.tsx
61└── error.tsx
62 
63# ❌ 错误示例
64components/
65├── userProfile.tsx    # 不使用 camelCase
66├── global-header.tsx  # 不使用 kebab-case
67└── THEME_DRAWER.tsx   # 不使用 UPPER_CASE
68```
69 
70#### 其他文件类型
71```bash
72# ✅ 样式文件
73styles/
74├── global.scss
75├── user-card.module.scss
76└── theme-config.css
77 
78# ✅ 工具文件
79utils/
80├── common.ts
81├── date-format.ts
82└── api-helper.ts
83 
84# ✅ 类型文件
85types/
86├── api.d.ts
87├── user-info.d.ts
88└── common.d.ts
89 
90# ✅ 配置文件
91config/
92├── app-config.ts
93├── theme-config.ts
94└── router-config.ts
95```
96 
97## JavaScript/TypeScript 命名
98 
99### 🔤 变量命名
100 
101**规则：使用 camelCase**
102 
103```typescript
104// ✅ 正确示例
105const userName = 'admin';
106const userAge = 25;
107const isLoading = false;
108const hasPermission = true;
109const userList = [];
110const currentUser = null;
111const pageConfig = {};
112 
113// ❌ 错误示例
114const user_name = 'admin';        // 不使用 snake_case
115const UserAge = 25;               // 不使用 PascalCase
116const is_loading = false;         // 不使用 snake_case
117const HAS_PERMISSION = true;      // 不使用 UPPER_CASE
118```
119 
120### 🔧 函数命名
121 
122**规则：使用 camelCase，动词开头**
123 
124```typescript
125// ✅ 正确示例
126function getUserInfo() {}
127function handleClick() {}
128function validateForm() {}
129function formatDate() {}
130function checkPermission() {}
131function toggleTheme() {}
132function calculateTotal() {}
133function renderComponent() {}
134 
135// ❌ 错误示例
136function GetUserInfo() {}         // 不使用 PascalCase
137function handle_click() {}        // 不使用 snake_case
138function user_info() {}           // 缺少动词
139function VALIDATE_FORM() {}       // 不使用 UPPER_CASE
140```
141 
142### 📦 常量命名
143 
144**规则：使用 UPPER_SNAKE_CASE**
145 
146```typescript
147// ✅ 正确示例
148const MAX_RETRY_COUNT = 3;
149const API_BASE_URL = 'https://api.example.com';
150const DEFAULT_PAGE_SIZE = 20;
151const STORAGE_KEYS = {
152  USER_TOKEN: 'user_token',
153  THEME_CONFIG: 'theme_config',
154  LANGUAGE: 'language'
155};
156 
157const HTTP_STATUS = {
158  SUCCESS: 200,
159  NOT_FOUND: 404,
160  SERVER_ERROR: 500
161} as const;
162 
163// ❌ 错误示例
164const maxRetryCount = 3;          // 不使用 camelCase 表示常量
165const apiBaseUrl = 'https://...'; // 不使用 camelCase 表示常量
166const Max_Retry_Count = 3;        // 混合命名风格
167```
168 
169### 🏗️ 类型和接口命名
170 
171**规则：使用 PascalCase**
172 
173```typescript
174// ✅ 正确示例 - 接口
175interface UserInfo {
176  id: string;
177  name: string;
178  email: string;
179}
180 
181interface ApiResponse<T> {
182  code: number;
183  message: string;
184  data: T;
185}
186 
187interface ComponentProps {
188  title: string;
189  visible?: boolean;
190  onClose?: () => void;
191}
192 
193// ✅ 正确示例 - 类型别名
194type Theme = 'light' | 'dark';
195type UserRole = 'admin' | 'user' | 'guest';
196type RequestMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
197 
198// ✅ 正确示例 - 泛型
199type Partial<T> = {
200  [P in keyof T]?: T[P];
201};
202 
203type ApiResult<T = any> = {
204  success: boolean;
205  data: T;
206  error?: string;
207};
208 
209// ❌ 错误示例
210interface userInfo {}            // 不使用 camelCase
211interface api_response {}        // 不使用 snake_case
212interface COMPONENT_PROPS {}     // 不使用 UPPER_CASE
213type theme = 'light' | 'dark';   // 不使用 camelCase
214```
215 
216### 🏛️ 类命名
217 
218**规则：使用 PascalCase**
219 
220```typescript
221// ✅ 正确示例
222class UserService {
223  private apiClient: ApiClient;
224 
225  constructor(apiClient: ApiClient) {
226    this.apiClient = apiClient;
227  }
228}
229 
230class HttpClient {
231  private baseURL: string;
232 
233  get(url: string) {}
234  post(url: string, data: any) {}
235}
236 
237class ValidationError extends Error {
238  constructor(message: string) {
239    super(message);
240    this.name = 'ValidationError';
241  }
242}
243 
244// ❌ 错误示例
245class userService {}             // 不使用 camelCase
246class http_client {}             // 不使用 snake_case
247class VALIDATION_ERROR {}        // 不使用 UPPER_CASE
248```
249 
250### 🔗 枚举命名
251 
252**规则：枚举名使用 PascalCase，成员使用 PascalCase**
253 
254```typescript
255// ✅ 正确示例
256enum UserRole {
257  Admin = 'admin',
258  User = 'user',
259  Guest = 'guest'
260}
261 
262enum RequestStatus {
263  Pending = 'pending',
264  Success = 'success',
265  Failed = 'failed'
266}
267 
268enum ThemeMode {
269  Light = 'light',
270  Dark = 'dark',
271  Auto = 'auto'
272}
273 
274// ❌ 错误示例
275enum userRole {                  // 不使用 camelCase
276  ADMIN = 'admin',              // 不使用 UPPER_CASE 成员
277  USER = 'user'
278}
279 
280enum REQUEST_STATUS {            // 不使用 UPPER_CASE 枚举名
281  pending = 'pending',          // 不使用 camelCase 成员
282  success = 'success'
283}
284```
285 
286## React 组件命名
287 
288### 🧩 组件命名规范
289 
290**规则：使用 PascalCase**
291 
292```typescript
293// ✅ 正确示例
294const UserProfile: React.FC = () => {
295  return <div>User Profile</div>;
296};
297 
298const GlobalHeader: React.FC = () => {
299  return <header>Global Header</header>;
300};
301 
302const DataTable: React.FC<DataTableProps> = ({ data }) => {
303  return <table>{/* table content */}</table>;
304};
305 
306const ThemeDrawer: React.FC = () => {
307  return <div>Theme Drawer</div>;
308};
309 
310// ❌ 错误示例
311const userProfile = () => {};     // 不使用 camelCase
312const global_header = () => {};   // 不使用 snake_case
313const DATA_TABLE = () => {};      // 不使用 UPPER_CASE
314```
315 
316### 🏷️ Props 接口命名
317 
318**规则：组件名 + Props 后缀**
319 
320```typescript
321// ✅ 正确示例
322interface UserProfileProps {
323  user: UserInfo;
324  onEdit?: (user: UserInfo) => void;
325  onDelete?: (id: string) => void;
326}
327 
328interface DataTableProps<T = any> {
329  data: T[];
330  columns: ColumnConfig[];
331  loading?: boolean;
332  onRowClick?: (record: T) => void;
333}
334 
335interface ModalProps {
336  visible: boolean;
337  title: string;
338  children: React.ReactNode;
339  onCancel: () => void;
340  onConfirm: () => void;
341}
342 
343// ❌ 错误示例
344interface UserProfileProperties {}  // 不使用完整的 Props
345interface userProfileProps {}       // 不使用 PascalCase
346interface UserProfile_Props {}      // 不使用下划线
347```
348 
349### 🎯 事件处理函数命名
350 
351**规则：handle + 动作名称**
352 
353```typescript
354// ✅ 正确示例
355const UserCard: React.FC<UserCardProps> = ({ user, onEdit, onDelete }) => {
356  const handleEdit = () => {
357    onEdit?.(user);
358  };
359 
360  const handleDelete = () => {
361    if (window.confirm('确认删除？')) {
362      onDelete?.(user.id);
363    }
364  };
365 
366  const handleSubmit = (event: React.FormEvent) => {
367    event.preventDefault();
368    // 处理提交逻辑
369  };
370 
371  const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
372    setValue(event.target.value);
373  };
374 
375  return (
376    <div>
377      <button onClick={handleEdit}>编辑</button>
378      <button onClick={handleDelete}>删除</button>
379    </div>
380  );
381};
382 
383// ❌ 错误示例
384const onEditClick = () => {};      // 不使用 handle 前缀
385const deleteHandler = () => {};    // 不使用 handle 前缀
386const HandleEdit = () => {};       // 不使用 PascalCase
387const handle_delete = () => {};    // 不使用 snake_case
388```
389 
390## Hook 命名规范
391 
392### 🪝 自定义 Hook 命名
393 
394**规则：use + 功能描述（PascalCase）**
395 
396```typescript
397// ✅ 正确示例
398const useUserInfo = (userId: string) => {
399  const [user, setUser] = useState<UserInfo | null>(null);
400  const [loading, setLoading] = useState(false);
401 
402  useEffect(() => {
403    fetchUserById(userId).then(setUser);
404  }, [userId]);
405 
406  return { user, loading };
407};
408 
409const useLocalStorage = <T>(key: string, defaultValue: T) => {
410  const [value, setValue] = useState<T>(() => {
411    const stored = localStorage.getItem(key);
412    return stored ? JSON.parse(stored) : defaultValue;
413  });
414 
415  return [value, setValue] as const;
416};
417 
418const useDebounce = <T>(value: T, delay: number) => {
419  const [debouncedValue, setDebouncedValue] = useState(value);
420 
421  useEffect(() => {
422    const handler = setTimeout(() => {
423      setDebouncedValue(value);
424    }, delay);
425 
426    return () => clearTimeout(handler);
427  }, [value, delay]);
428 
429  return debouncedValue;
430};
431 
432// ❌ 错误示例
433const userInfo = () => {};         // 缺少 use 前缀
434const getUserInfo = () => {};      // 不是 Hook，应该是普通函数
435const useuser_info = () => {};     // 不使用 snake_case
436const USE_USER_INFO = () => {};    // 不使用 UPPER_CASE
437```
438 
439## API 和服务命名
440 
441### 🌐 API 函数命名
442 
443**规则：fetch + 资源名称（PascalCase）**
444 
445```typescript
446// ✅ 正确示例
447export const fetchUserList = (params: UserListParams) => {
448  return request<UserListResponse>({
449    url: '/user/list',
450    method: 'GET',
451    params,
452  });
453};
454 
455export const fetchUserById = (id: string) => {
456  return request<UserInfo>({
457    url: `/user/${id}`,
458    method: 'GET',
459  });
460};
461 
462export const createUser = (data: CreateUserData) => {
463  return request<ApiResponse>({
464    url: '/user',
465    method: 'POST',
466    data,
467  });
468};
469 
470export const updateUser = (id: string, data: UpdateUserData) => {
471  return request<ApiResponse>({
472    url: `/user/${id}`,
473    method: 'PUT',
474    data,
475  });
476};
477 
478export const deleteUser = (id: string) => {
479  return request<ApiResponse>({
480    url: `/user/${id}`,
481    method: 'DELETE',
482  });
483};
484 
485// ❌ 错误示例
486export const getUserList = () => {};     // 不使用 fetch 前缀
487export const fetch_user_list = () => {}; // 不使用 snake_case
488export const FETCH_USER_LIST = () => {}; // 不使用 UPPER_CASE
489export const userListApi = () => {};     // 不清晰的命名
490```
491 
492### 🏢 服务类命名
493 
494**规则：资源名称 + Service 后缀**
495 
496```typescript
497// ✅ 正确示例
498class UserService {
499  async getList(params: UserListParams) {
500    return fetchUserList(params);
501  }
502 
503  async getById(id: string) {
504    return fetchUserById(id);
505  }
506 
507  async create(data: CreateUserData) {
508    return createUser(data);
509  }
510}
511 
512class AuthService {
513  async login(credentials: LoginCredentials) {
514    return request('/auth/login', { method: 'POST', data: credentials });
515  }
516 
517  async logout() {
518    return request('/auth/logout', { method: 'POST' });
519  }
520}
521 
522// ❌ 错误示例
523class userService {}              // 不使用 PascalCase
524class User_Service {}             // 不使用下划线
525class USERSERVICE {}              // 不使用 UPPER_CASE
526class UserApi {}                  // 不使用 Service 后缀
527```
528 
529## 样式和CSS命名
530 
531### 🎨 CSS 类名命名
532 
533**规则：使用 kebab-case，遵循 BEM 规范**
534 
535```scss
536// ✅ 正确示例
537.user-card {
538  padding: 16px;
539  border-radius: 8px;
540 
541  &__header {
542    display: flex;
543    justify-content: space-between;
544    margin-bottom: 12px;
545 
546    &__title {
547      font-size: 18px;
548      font-weight: bold;
549    }
550 
551    &__actions {
552      display: flex;
553      gap: 8px;
554    }
555  }
556 
557  &__content {
558    color: #666;
559    line-height: 1.5;
560  }
561 
562  &--active {
563    border: 2px solid #1890ff;
564  }
565 
566  &--disabled {
567    opacity: 0.5;
568    pointer-events: none;
569  }
570}
571 
572.data-table {
573  width: 100%;
574 
575  &__row {
576    &:hover {
577      background-color: #f5f5f5;
578    }
579 
580    &--selected {
581      background-color: #e6f7ff;
582    }
583  }
584}
585 
586// ❌ 错误示例
587.userCard {}                     // 不使用 camelCase
588.user_card {}                    // 不使用 snake_case
589.USER_CARD {}                    // 不使用 UPPER_CASE
590.user-card-header-title {}       // 不使用 BEM 规范
591```
592 
593### 🏷️ CSS Modules 命名
594 
595```scss
596// UserCard.module.scss
597// ✅ 正确示例
598.userCard {
599  @apply bg-white rounded-lg shadow-md p-4;
600 
601  .header {
602    @apply flex items-center justify-between mb-4;
603 
604    .title {
605      @apply text-lg font-bold text-gray-800;
606    }
607 
608    .actions {
609      @apply flex gap-2;
610    }
611  }
612 
613  .content {
614    @apply text-gray-600;
615  }
616 
617  .footer {
618    @apply mt-4 pt-4 border-t border-gray-200;
619  }
620}
621 
622// ❌ 错误示例
623.user-card {}                    // CSS modules 中不使用 kebab-case
624.user_card {}                    // 不使用 snake_case
625.USER_CARD {}                    // 不使用 UPPER_CASE
626```
627 
628## 图标命名规范
629 
630### 🎯 Iconify 图标使用
631 
632**规则：使用 kebab-case，遵循 iconify 规范**
633 
634```tsx
635// ✅ 正确示例
636<IconMdiHome />
637<iconTablerSearch />
638 
639 
640// ❌ 错误示例
641<icon-carbon-settings />        // 不使用 kebab-case
642<icon_mdi_home />                // 不使用 snake_case
643<ICON-MDI-HOME />                // 不使用 UPPER_CASE
644```
645 
646### 🖼️ 本地 SVG 图标
647 
648```bash
649# ✅ 正确示例
650src/assets/svg-icon/
651├── arrow-left.svg
652├── arrow-right.svg
653├── user-circle.svg
654├── settings-gear.svg
655└── notification-bell.svg
656 
657# ❌ 错误示例
658src/assets/svg-icon/
659├── arrowLeft.svg               # 不使用 camelCase
660├── arrow_right.svg             # 不使用 snake_case
661├── USERCIRCLE.svg              # 不使用 UPPER_CASE
662└── settings.Gear.svg           # 不使用混合命名
663```
664 
665## 配置和环境变量
666 
667### ⚙️ 环境变量命名
668 
669**规则：使用 UPPER_SNAKE_CASE，项目前缀**
670 
671```bash
672# ✅ 正确示例
673VITE_API_BASE_URL=https://api.example.com
674VITE_APP_TITLE=SoybeanAdmin
675VITE_APP_VERSION=1.0.0
676VITE_ENABLE_MOCK=true
677VITE_STORAGE_PREFIX=soybean_
678VITE_DEFAULT_THEME=light
679 
680# ❌ 错误示例
681viteApiBaseUrl=                 # 不使用 camelCase
682vite-api-base-url=              # 不使用 kebab-case
683ViteApiBaseUrl=                 # 不使用 PascalCase
684```
685 
686### 📋 配置对象命名
687 
688```typescript
689// ✅ 正确示例
690export const appConfig = {
691  name: 'SoybeanAdmin',
692  version: '1.0.0',
693  description: 'A fresh and elegant admin template'
694};
695 
696export const themeConfig = {
697  defaultTheme: 'light' as const,
698  enableDarkMode: true,
699  primaryColor: '#1890ff'
700};
701 
702export const routeConfig = {
703  homePath: '/home',
704  loginPath: '/login',
705  enableAuth: true
706};
707 
708// ❌ 错误示例
709export const AppConfig = {};             // 不使用 PascalCase 用于对象
710export const theme_config = {};         // 不使用 snake_case
711export const ROUTE_CONFIG = {};         // 不使用 UPPER_CASE
712```
713 
714## 总结
715 
716### 📝 命名规范速查表
717 
718| 类型 | 规范 | 示例 |
719|------|------|------|
720| 文件/文件夹 | kebab-case | `user-center/`, `global-header.tsx` |
721| React 组件 | PascalCase | `UserProfile`, `DataTable` |
722| 变量/函数 | camelCase | `userName`, `getUserInfo()` |
723| 常量 | UPPER_SNAKE_CASE | `MAX_RETRY_COUNT`, `API_BASE_URL` |
724| 类型/接口 | PascalCase | `UserInfo`, `ApiResponse<T>` |
725| CSS 类名 | kebab-case (BEM) | `.user-card__header--active` |
726| CSS Modules | camelCase | `.userCard`, `.headerTitle` |
727| Hooks | use + PascalCase | `useUserInfo`, `useLocalStorage` |
728| API 函数 | fetch + PascalCase | `fetchUserList`, `createUser` |
729| 图标 | kebab-case | `<icon-mdi-home />` |
730| 环境变量 | UPPER_SNAKE_CASE | `VITE_API_BASE_URL` |
731 
732### ⚡ 最佳实践
733 
7341. **保持一致性**：在整个项目中使用相同的命名约定
7352. **语义化命名**：名称应该能清楚地表达其用途和含义
7363. **避免缩写**：除非是公认的缩写，否则使用完整的单词
7374. **使用英文**：所有命名都应该使用英文，避免中文拼音
7385. **遵循约定**：优先使用团队和社区认可的命名约定
739 
740遵循这些命名规范将有助于提高代码的可读性、可维护性和团队协作效率。
741