blank/docs/architecture/coding-standards.md

编码规范

TypeScript 规范

类型定义

• 使用接口定义数据模型
• 优先使用 interface 而非 type

• 导出类型使用 export interface

  // 正确
  export interface IUserInfo {
  userName: string
  userId: number | string
  }
  
  // 避免
  type UserInfo = {
  userName: string
  userId: number | string
  }
  

组件规范

• 使用函数式组件 + Hooks
• 组件文件使用 .tsx 扩展名

• 组件名使用 PascalCase

  // 正确
  export const UserList: React.FC<UserListProps> = ({ data }) => {
  return <div>{/* 组件内容 */}</div>
  }
  

导入导出规范

• 使用绝对路径导入 (@/)
• 按类型分组导入

• 默认导出仅用于组件

  // 正确
  import React, { useState, useEffect } from "react"
  import { useSelector, useDispatch } from "react-redux"
  import { IUserInfo } from "@/types"
  import { apiGetUserInfo } from "@/common/request"
  

React 规范

Hooks 使用

• 自定义 Hook 以 use 开头
• 复杂逻辑封装为自定义 Hook

• 避免在循环/条件中使用 Hooks

  // 正确
  export const useUserData = (userId: string) => {
  const [user, setUser] = useState<IUserInfo>()
  
  useEffect(() => {
  // 获取用户数据
  }, [userId])
  
  return user
  }
  

状态管理

• 全局状态使用 Redux Toolkit
• 局部状态使用 useState
• 复杂状态逻辑使用 useReducer

文件组织规范

目录结构

src/
├── components/     # 可复用组件
├── pages/         # 页面组件
├── manager/       # 业务逻辑管理器
├── store/         # 状态管理
├── common/        # 通用工具
├── types/         # 类型定义
└── styles/        # 样式文件

命名约定

• 文件: kebab-case (user-list.tsx)
• 组件: PascalCase (UserList)
• 变量: camelCase (userName)
• 常量: UPPER_SNAKE_CASE (MAX_USERS)
• 接口: I + PascalCase (IUserInfo)

代码质量

错误处理

• 使用 try-catch 处理异步错误
• 提供有意义的错误消息

• 记录错误日志

  try {
  await apiCall()
  } catch (error) {
  console.error("API调用失败:", error)
  message.error("操作失败，请重试")
  }
  

性能优化

• 使用 React.memo 优化组件重渲染
• 使用 useMemo/useCallback 避免不必要的计算
• 懒加载大型组件

可维护性

• 函数不超过50行
• 组件职责单一
• 添加必要的注释
• 删除无用代码