Cursor rule

1---
2description:
3globs:
4alwaysApply: false
5---
6# SoybeanAdmin React 注释规范
7 
8## 概述
9 
10本文档定义了 SoybeanAdmin React 项目的注释规范，旨在提高代码的可读性、可维护性和团队协作效率。良好的注释是代码自文档化的重要组成部分。
11 
12## 注释基本原则
13 
14### 🎯 核心原则
15 
161. **注释要说明"为什么"，而不是"做什么"**
172. **注释应该是代码的补充，而不是重复**
183. **保持注释与代码同步更新**
194. **使用中文注释，提高团队理解效率**
205. **遵循统一的注释格式和风格**
21 
22### ⚡ 何时需要注释
23 
24```typescript
25// ✅ 需要注释的场景
26// 1. 复杂的业务逻辑
27// 2. 算法实现
28// 3. 魔法数字和常量
29// 4. API 接口说明
30// 5. 公共组件和工具函数
31// 6. 临时解决方案（TODO/FIXME）
32 
33// ❌ 不需要注释的场景
34// 1. 自解释的代码
35// 2. 简单的变量赋值
36// 3. 显而易见的操作
37```
38 
39## JSDoc 注释规范
40 
41### 📝 函数注释
42 
43**规则：使用 JSDoc 风格，包含描述、参数、返回值**
44 
45```typescript
46// ✅ 正确示例
47/**
48 * 格式化日期
49 * @param date 日期对象、时间戳或日期字符串
50 * @param format 格式化模板，默认为 'YYYY-MM-DD HH:mm:ss'
51 * @returns 格式化后的日期字符串
52 * @example
53 * formatDate(new Date(), 'YYYY-MM-DD') // '2024-01-15'
54 * formatDate(1642204800000, 'MM/DD/YYYY') // '01/15/2022'
55 */
56export const formatDate = (
57  date: Date | number | string,
58  format = 'YYYY-MM-DD HH:mm:ss'
59): string => {
60  // 实现逻辑
61  return dayjs(date).format(format);
62};
63 
64/**
65 * 防抖函数 - 在指定时间内多次调用只执行最后一次
66 * @param fn 要防抖的函数
67 * @param delay 延迟时间（毫秒）
68 * @returns 防抖后的函数
69 * @example
70 * const debouncedSearch = debounce(search, 300);
71 * debouncedSearch('keyword'); // 300ms 后执行
72 */
73export const debounce = <T extends (...args: any[]) => any>(
74  fn: T,
75  delay: number
76): T => {
77  let timeoutId: NodeJS.Timeout;
78  return ((...args: Parameters<T>) => {
79    clearTimeout(timeoutId);
80    timeoutId = setTimeout(() => fn(...args), delay);
81  }) as T;
82};
83 
84/**
85 * 深拷贝对象或数组
86 * @param obj 要拷贝的对象
87 * @returns 深拷贝后的新对象
88 * @throws {Error} 当对象包含循环引用时抛出错误
89 */
90export const deepClone = <T>(obj: T): T => {
91  if (obj === null || typeof obj !== 'object') return obj;
92  // 实现逻辑
93};
94 
95// ❌ 错误示例
96// 缺少注释
97export const formatDate = (date: Date, format: string) => {
98  return dayjs(date).format(format);
99};
100 
101// 注释过于简单，没有提供有用信息
102/**
103 * 格式化日期
104 */
105export const formatDate = (date: Date, format: string) => {
106  return dayjs(date).format(format);
107};
108```
109 
110### 🏗️ 类和接口注释
111 
112```typescript
113// ✅ 正确示例
114/**
115 * 用户信息接口
116 * @description 定义用户的基本信息结构
117 */
118interface UserInfo {
119  /** 用户唯一标识 */
120  id: string;
121  /** 用户名 */
122  name: string;
123  /** 邮箱地址 */
124  email: string;
125  /** 用户角色 */
126  role: 'admin' | 'user' | 'guest';
127  /** 账户创建时间 */
128  createTime: string;
129  /** 最后更新时间 */
130  updateTime: string;
131  /** 是否激活 */
132  isActive: boolean;
133}
134 
135/**
136 * API 响应数据结构
137 * @template T 响应数据的类型
138 */
139interface ApiResponse<T = any> {
140  /** 响应状态码 */
141  code: number;
142  /** 响应消息 */
143  message: string;
144  /** 响应数据 */
145  data: T;
146  /** 请求是否成功 */
147  success: boolean;
148}
149 
150/**
151 * 用户服务类
152 * @description 处理用户相关的 API 请求
153 */
154class UserService {
155  private apiClient: ApiClient;
156 
157  /**
158   * 构造函数
159   * @param apiClient API 客户端实例
160   */
161  constructor(apiClient: ApiClient) {
162    this.apiClient = apiClient;
163  }
164 
165  /**
166   * 获取用户列表
167   * @param params 查询参数
168   * @returns Promise<UserListResponse>
169   */
170  async getUserList(params: UserListParams): Promise<UserListResponse> {
171    return this.apiClient.get('/users', { params });
172  }
173}
174```
175 
176### 🧩 组件注释
177 
178```typescript
179// ✅ 正确示例
180/**
181 * 用户信息卡片组件
182 * @description 展示用户基本信息，支持编辑和删除操作
183 * @author 张三
184 * @since 1.0.0
185 */
186interface UserCardProps {
187  /** 用户信息对象 */
188  user: UserInfo;
189  /** 是否显示操作按钮 */
190  showActions?: boolean;
191  /** 卡片尺寸 */
192  size?: 'small' | 'medium' | 'large';
193  /** 编辑回调函数 */
194  onEdit?: (user: UserInfo) => void;
195  /** 删除回调函数 */
196  onDelete?: (userId: string) => void;
197}
198 
199/**
200 * 用户信息卡片组件
201 * @param props 组件属性
202 * @returns JSX.Element
203 */
204const UserCard: React.FC<UserCardProps> = ({
205  user,
206  showActions = true,
207  size = 'medium',
208  onEdit,
209  onDelete
210}) => {
211  // 处理编辑操作
212  const handleEdit = useCallback(() => {
213    onEdit?.(user);
214  }, [user, onEdit]);
215 
216  // 处理删除操作
217  const handleDelete = useCallback(() => {
218    if (window.confirm('确认删除此用户？')) {
219      onDelete?.(user.id);
220    }
221  }, [user.id, onDelete]);
222 
223  return (
224    <Card className={`user-card user-card--${size}`}>
225      {/* 用户头像区域 */}
226      <div className="user-card__avatar">
227        <Avatar size={size === 'large' ? 64 : 48} src={user.avatar} />
228      </div>
229 
230      {/* 用户信息区域 */}
231      <div className="user-card__info">
232        <h3 className="user-card__name">{user.name}</h3>
233        <p className="user-card__email">{user.email}</p>
234        <Tag color={user.role === 'admin' ? 'red' : 'blue'}>
235          {user.role}
236        </Tag>
237      </div>
238 
239      {/* 操作按钮区域 */}
240      {showActions && (
241        <div className="user-card__actions">
242          <Button size="small" onClick={handleEdit}>
243            编辑
244          </Button>
245          <Button size="small" danger onClick={handleDelete}>
246            删除
247          </Button>
248        </div>
249      )}
250    </Card>
251  );
252};
253 
254export default UserCard;
255```
256 
257### 🪝 Hook 注释
258 
259```typescript
260// ✅ 正确示例
261/**
262 * 用户信息管理 Hook
263 * @description 提供用户信息的获取、更新和缓存功能
264 * @param userId 用户ID
265 * @returns 用户信息和相关操作方法
266 * @example
267 * const { user, loading, updateUser, refreshUser } = useUserInfo('123');
268 */
269export const useUserInfo = (userId: string) => {
270  const [user, setUser] = useState<UserInfo | null>(null);
271  const [loading, setLoading] = useState(false);
272  const [error, setError] = useState<string | null>(null);
273 
274  // 获取用户信息
275  const fetchUser = useCallback(async () => {
276    if (!userId) return;
277 
278    setLoading(true);
279    setError(null);
280 
281    try {
282      const userData = await fetchUserById(userId);
283      setUser(userData);
284    } catch (err) {
285      setError(err instanceof Error ? err.message : '获取用户信息失败');
286    } finally {
287      setLoading(false);
288    }
289  }, [userId]);
290 
291  // 更新用户信息
292  const updateUser = useCallback(async (updates: Partial<UserInfo>) => {
293    if (!user) return;
294 
295    try {
296      const updatedUser = await updateUserById(user.id, updates);
297      setUser(updatedUser);
298      return updatedUser;
299    } catch (err) {
300      setError(err instanceof Error ? err.message : '更新用户信息失败');
301      throw err;
302    }
303  }, [user]);
304 
305  useEffect(() => {
306    fetchUser();
307  }, [fetchUser]);
308 
309  return {
310    user,
311    loading,
312    error,
313    updateUser,
314    refreshUser: fetchUser
315  };
316};
317```
318 
319## 行内注释规范
320 
321### 💬 单行注释
322 
323```typescript
324// ✅ 正确示例
325// 计算用户权限等级（1-5级，5级为最高权限）
326const calculateUserLevel = (permissions: string[]) => {
327  // 管理员权限直接返回最高等级
328  if (permissions.includes('admin')) {
329    return 5;
330  }
331 
332  // 根据权限数量计算等级
333  const level = Math.min(Math.floor(permissions.length / 2) + 1, 4);
334  return level;
335};
336 
337// 处理API响应错误
338const handleApiError = (error: ApiError) => {
339  // 401 未授权，跳转到登录页
340  if (error.code === 401) {
341    router.push('/login');
342    return;
343  }
344 
345  // 403 权限不足，显示错误提示
346  if (error.code === 403) {
347    notification.error({
348      message: '权限不足',
349      description: '您没有执行此操作的权限'
350    });
351    return;
352  }
353 
354  // 其他错误显示通用错误信息
355  notification.error({
356    message: '操作失败',
357    description: error.message || '请稍后重试'
358  });
359};
360 
361// ❌ 错误示例
362const userName = 'admin'; // 用户名  <- 无意义的注释
363const age = 25; // 年龄是25  <- 重复代码内容
364// 这是一个函数  <- 太泛泛的注释
365function getData() {
366  return data;
367}
368```
369 
370### 🏷️ 特殊标记注释
371 
372```typescript
373// ✅ 正确示例
374const UserProfile: React.FC<UserProfileProps> = ({ user }) => {
375  // TODO: 添加用户头像上传功能
376  // 计划在下个版本中实现头像拖拽上传
377 
378  // FIXME: 修复在移动端显示异常的问题
379  // 当前在 iOS Safari 中用户信息卡片会出现布局错乱
380 
381  // HACK: 临时解决方案 - 强制刷新组件
382  // 等待 React 18 并发特性稳定后重构此部分代码
383  const [forceUpdate, setForceUpdate] = useState(0);
384 
385  // NOTE: 这里使用了特殊的数据格式
386  // 服务端返回的时间格式为 Unix timestamp，需要转换
387  const formattedTime = useMemo(() => {
388    return dayjs.unix(user.createTime).format('YYYY-MM-DD HH:mm:ss');
389  }, [user.createTime]);
390 
391  // WARNING: 此方法会修改原始对象
392  // 调用前请确认是否需要深拷贝
393  const processUserData = (userData: UserInfo) => {
394    userData.name = userData.name.trim();
395    return userData;
396  };
397 
398  return (
399    <div className="user-profile">
400      {/* 用户基本信息 */}
401      <div className="user-profile__basic">
402        <h2>{user.name}</h2>
403        <p>{user.email}</p>
404      </div>
405 
406      {/* 用户详细信息 */}
407      <div className="user-profile__details">
408        <p>创建时间: {formattedTime}</p>
409        <p>用户角色: {user.role}</p>
410      </div>
411    </div>
412  );
413};
414```
415 
416### 📝 特殊标记说明
417 
418| 标记 | 用途 | 示例 |
419|------|------|------|
420| `TODO` | 计划添加的功能 | `// TODO: 添加数据导出功能` |
421| `FIXME` | 需要修复的问题 | `// FIXME: 修复内存泄漏问题` |
422| `HACK` | 临时解决方案 | `// HACK: 绕过第三方库的bug` |
423| `NOTE` | 重要说明 | `// NOTE: 此API在v2.0中已废弃` |
424| `WARNING` | 警告信息 | `// WARNING: 此操作不可逆` |
425| `OPTIMIZE` | 性能优化点 | `// OPTIMIZE: 考虑使用虚拟滚动` |
426| `REVIEW` | 需要代码审查 | `// REVIEW: 确认业务逻辑是否正确` |
427 
428 
429## API 和配置注释
430 
431### 🌐 API 接口注释
432 
433```typescript
434// ✅ 正确示例
435/**
436 * 用户相关 API 接口
437 */
438export const userApi = {
439  /**
440   * 获取用户列表
441   * @param params 查询参数
442   * @param params.page 页码，从1开始
443   * @param params.pageSize 每页数量，默认20
444   * @param params.keyword 搜索关键词，支持用户名和邮箱搜索
445   * @param params.role 用户角色筛选
446   * @param params.status 用户状态筛选
447   * @returns Promise<UserListResponse> 用户列表数据
448   * @example
449   * const result = await userApi.fetchUserList({
450   *   page: 1,
451   *   pageSize: 20,
452   *   keyword: 'admin'
453   * });
454   */
455  fetchUserList: (params: UserListParams) => {
456    return request<UserListResponse>({
457      url: '/api/users',
458      method: 'GET',
459      params
460    });
461  },
462 
463  /**
464   * 根据ID获取用户详情
465   * @param id 用户ID
466   * @returns Promise<UserInfo> 用户详细信息
467   * @throws {ApiError} 当用户不存在时抛出404错误
468   */
469  fetchUserById: (id: string) => {
470    return request<UserInfo>({
471      url: `/api/users/${id}`,
472      method: 'GET'
473    });
474  },
475 
476  /**
477   * 创建新用户
478   * @param userData 用户数据
479   * @returns Promise<UserInfo> 创建成功的用户信息
480   * @throws {ValidationError} 当数据验证失败时抛出400错误
481   */
482  createUser: (userData: CreateUserData) => {
483    return request<UserInfo>({
484      url: '/api/users',
485      method: 'POST',
486      data: userData
487    });
488  }
489};
490```
491 
492### ⚙️ 配置文件注释
493 
494```typescript
495// ✅ 正确示例
496/**
497 * 应用配置
498 * @description 包含应用的基本配置信息
499 */
500export const appConfig = {
501  /** 应用名称 */
502  name: 'SoybeanAdmin',
503 
504  /** 应用版本 */
505  version: '1.0.0',
506 
507  /** 应用描述 */
508  description: '基于 React + TypeScript 的后台管理系统',
509 
510  /** 默认语言 */
511  defaultLang: 'zh-CN',
512 
513  /** 是否启用国际化 */
514  enableI18n: true,
515 
516  /**
517   * 分页配置
518   * @description 表格分页的默认配置
519   */
520  pagination: {
521    /** 默认页码 */
522    defaultPage: 1,
523    /** 默认每页数量 */
524    defaultPageSize: 20,
525    /** 每页数量选项 */
526    pageSizeOptions: ['10', '20', '50', '100'],
527    /** 是否显示快速跳转 */
528    showQuickJumper: true,
529    /** 是否显示总数 */
530    showTotal: true
531  },
532 
533  /**
534   * 请求配置
535   * @description HTTP请求的默认配置
536   */
537  request: {
538    /** 请求超时时间（毫秒） */
539    timeout: 10000,
540    /** 基础URL */
541    baseURL: import.meta.env.VITE_API_BASE_URL,
542    /** 重试次数 */
543    retryCount: 3,
544    /** 重试间隔（毫秒） */
545    retryDelay: 1000
546  }
547};
548 
549/**
550 * 主题配置
551 * @description 定义应用的主题样式配置
552 */
553export const themeConfig = {
554  /** 默认主题模式 */
555  defaultMode: 'light' as const,
556 
557  /** 是否启用暗色模式 */
558  enableDarkMode: true,
559 
560  /**
561   * 主色调配置
562   * @description 影响按钮、链接等主要元素的颜色
563   */
564  primaryColor: '#1890ff',
565 
566  /**
567   * 成功状态颜色
568   * @description 用于成功提示、完成状态等
569   */
570  successColor: '#52c41a',
571 
572  /**
573   * 警告状态颜色
574   * @description 用于警告提示、待处理状态等
575   */
576  warningColor: '#faad14',
577 
578  /**
579   * 错误状态颜色
580   * @description 用于错误提示、失败状态等
581   */
582  errorColor: '#ff4d4f'
583};
584```
585 
586## 注释最佳实践
587 
588### ✅ 推荐做法
589 
590```typescript
591// 1. 解释复杂业务逻辑
592const calculateUserScore = (user: UserInfo) => {
593  // 用户评分算法：基础分数50分
594  let score = 50;
595 
596  // 根据注册时长加分（每年+10分，最多+30分）
597  const yearsSinceRegistration = dayjs().diff(user.registerTime, 'year');
598  score += Math.min(yearsSinceRegistration * 10, 30);
599 
600  // 根据活跃度加分（每月活跃+5分，最多+20分）
601  score += Math.min(user.activeMonths * 5, 20);
602 
603  // 违规记录扣分（每次违规-10分）
604  score -= user.violationCount * 10;
605 
606  // 确保分数在0-100范围内
607  return Math.max(0, Math.min(100, score));
608};
609 
610// 2. 解释魔法数字
611const MAX_UPLOAD_SIZE = 5 * 1024 * 1024; // 5MB - 用户头像上传限制
612const DEBOUNCE_DELAY = 300; // 300ms - 搜索防抖延迟，平衡用户体验和性能
613 
614// 3. 解释复杂的正则表达式
615const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; // 邮箱格式验证正则
616 
617// 4. 解释算法思路
618const quickSort = (arr: number[]): number[] => {
619  // 快速排序算法实现
620  // 选择最后一个元素作为基准点，分为小于和大于基准的两部分
621  if (arr.length <= 1) return arr;
622 
623  const pivot = arr[arr.length - 1];
624  const left = arr.slice(0, -1).filter(x => x <= pivot);
625  const right = arr.slice(0, -1).filter(x => x > pivot);
626 
627  return [...quickSort(left), pivot, ...quickSort(right)];
628};
629```
630 
631### ❌ 避免的做法
632 
633```typescript
634// ❌ 不要重复代码
635const userName = 'admin'; // 设置用户名为admin
636 
637// ❌ 不要注释显而易见的代码
638const sum = a + b; // 把a和b相加
639 
640// ❌ 不要使用过时的注释
641const fetchUserData = async () => {
642  // 使用axios发送请求 <- 实际代码已改为fetch
643  return fetch('/api/users');
644};
645 
646// ❌ 不要使用无意义的注释
647// 这是一个函数
648function getData() {
649  return data;
650}
651 
652// ❌ 不要使用英文注释（在中文团队中）
653// Get user information from server
654const getUserInfo = () => {
655  // Implementation
656};
657```
658 
659## 注释维护
660 
661### 🔄 注释更新原则
662 
6631. **代码修改时同步更新注释**
6642. **删除过时和无效的注释**
6653. **定期审查注释的准确性**
6664. **保持注释格式的一致性**
667 
668### 📋 代码审查检查清单
669 
670- [ ] 所有公共函数都有JSDoc注释
671- [ ] 复杂业务逻辑有说明注释
672- [ ] 魔法数字有解释说明
673- [ ] TODO/FIXME等标记有明确描述
674- [ ] 注释内容与代码实现一致
675- [ ] 注释语言统一（推荐中文）
676- [ ] 注释格式规范统一
677 
678## 总结
679 
680### 📝 注释规范速查表
681 
682| 注释类型 | 格式 | 适用场景 |
683|---------|------|----------|
684| JSDoc注释 | `/** */` | 函数、类、接口、组件 |
685| 单行注释 | `//` | 行内说明、简短解释 |
686| 多行注释 | `/* */` | 大段说明、临时禁用代码 |
687| 特殊标记 | `// TODO:` | 待办事项、问题标记 |
688 
689### 🎯 注释质量标准
690 
691**高质量注释的特征：**
692- 解释代码的"为什么"而不是"是什么"
693- 提供有价值的上下文信息
694- 格式规范，易于阅读
695- 与代码保持同步
696- 使用合适的语言（团队统一）
697 
698**避免的注释：**
699- 重复代码内容的注释
700- 过时不准确的注释
701- 过于显而易见的注释
702- 格式不规范的注释
703- 语言不统一的注释
704- 不需要头部文件注释
705 
706遵循这些注释规范将大大提高代码的可读性和可维护性，让团队协作更加高效！
707