You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
131 lines
3.7 KiB
131 lines
3.7 KiB
# 项目代码规范与最佳实践
|
|
|
|
## 技术栈
|
|
- Vue 3 + Composition API
|
|
- TypeScript
|
|
- UnoCSS
|
|
- Element Plus
|
|
- Vite
|
|
- Pinia (状态管理)
|
|
- Vue Router
|
|
|
|
## 代码规范
|
|
|
|
### Vue 组件规范
|
|
- 使用 Composition API 和 `<script setup>` 语法
|
|
- 组件名使用 PascalCase 命名
|
|
- Props 必须定义类型，使用 `defineProps<T>()` 语法
|
|
- Emits 必须定义类型，使用 `defineEmits<T>()` 语法
|
|
- 组件文件使用 `.vue` 扩展名
|
|
- 单文件组件结构：`<template>` -> `<script setup>` -> `<style>`
|
|
|
|
### TypeScript 规范
|
|
- 严格模式：启用 `strict: true`
|
|
- 类型定义完整，避免使用 `any`
|
|
- 接口命名使用 PascalCase，以 `I` 开头（如 `IUserInfo`）
|
|
- 类型别名使用 PascalCase
|
|
- 枚举使用 PascalCase
|
|
- 函数参数和返回值必须定义类型
|
|
|
|
### UnoCSS 使用规范
|
|
- 优先使用 UnoCSS 原子类
|
|
- 自定义规则在 `uno.config.ts` 中定义
|
|
- 使用语义化的类名（如 `custom-hover`、`layout-border__left`）
|
|
- 响应式设计使用 UnoCSS 断点前缀
|
|
|
|
### 样式规范
|
|
- 使用 SCSS 预处理器
|
|
- 全局变量在 `@/styles/variables.scss` 中定义
|
|
- 组件样式使用 scoped 或 CSS Modules
|
|
- 遵循 BEM 命名规范
|
|
- 使用 CSS 变量（CSS Custom Properties）
|
|
|
|
### 文件组织
|
|
- 组件放在 `src/components/` 目录
|
|
- 页面放在 `src/views/` 目录
|
|
- 工具函数放在 `src/utils/` 目录
|
|
- 类型定义放在 `src/types/` 目录
|
|
- API 接口放在 `src/api/` 目录
|
|
- 状态管理放在 `src/stores/` 目录
|
|
|
|
### 命名规范
|
|
- 文件名使用 kebab-case
|
|
- 组件名使用 PascalCase
|
|
- 变量和函数使用 camelCase
|
|
- 常量使用 UPPER_SNAKE_CASE
|
|
- 私有属性使用下划线前缀
|
|
|
|
### 代码质量
|
|
- 使用 ESLint + Prettier 进行代码格式化
|
|
- 遵循 Vue 3 官方风格指南
|
|
- 组件职责单一，避免过度复杂
|
|
- 合理使用注释，复杂逻辑必须注释
|
|
- 错误处理完善，使用 try-catch 和错误边界
|
|
|
|
### 性能优化
|
|
- 合理使用 `v-memo` 和 `v-once`
|
|
- 避免在模板中使用复杂表达式
|
|
- 使用 `shallowRef` 和 `shallowReactive` 优化大对象
|
|
- 合理使用 `computed` 和 `watch`
|
|
- 图片懒加载和资源预加载
|
|
|
|
### 国际化
|
|
- 使用 vue-i18n 进行国际化
|
|
- 文本内容使用 `$t()` 函数
|
|
- 语言包文件放在 `src/locales/` 目录
|
|
|
|
### 状态管理
|
|
- 使用 Pinia 进行状态管理
|
|
- Store 文件放在 `src/stores/` 目录
|
|
- 使用 `defineStore` 定义 store
|
|
- 合理使用 `persist` 插件进行状态持久化
|
|
|
|
### 路由管理
|
|
- 路由配置放在 `src/router/` 目录
|
|
- 使用路由懒加载
|
|
- 路由守卫统一管理
|
|
- 动态路由权限控制
|
|
|
|
### API 接口
|
|
- 使用 axios 进行 HTTP 请求
|
|
- API 接口统一管理在 `src/api/` 目录
|
|
- 请求和响应拦截器统一处理
|
|
- 错误处理和重试机制
|
|
|
|
### 构建和部署
|
|
- 使用 Vite 作为构建工具
|
|
- 环境变量配置在 `.env.*` 文件中
|
|
- 构建产物优化（代码分割、压缩等）
|
|
- 支持多环境部署（dev/test/prod）
|
|
|
|
### 安全规范
|
|
- 输入验证和 XSS 防护
|
|
- CSRF 防护
|
|
- 敏感信息不暴露在前端
|
|
- 使用 HTTPS 协议
|
|
|
|
### 可访问性
|
|
- 语义化 HTML 标签
|
|
- ARIA 属性支持
|
|
- 键盘导航支持
|
|
- 屏幕阅读器友好
|
|
|
|
## 开发工具配置
|
|
- 使用 VS Code 作为主要开发工具
|
|
- 安装 Vue 3 相关插件
|
|
- 配置 TypeScript 智能提示
|
|
- 启用 ESLint 和 Prettier 自动格式化
|
|
- 使用 Git 进行版本控制
|
|
|
|
## 提交规范
|
|
- 使用 Conventional Commits 规范
|
|
- 提交信息格式：`type(scope): description`
|
|
- 类型：feat, fix, docs, style, refactor, test, chore
|
|
- 每次提交前运行 lint 检查
|
|
|
|
## 注意事项
|
|
- 遵循项目现有架构设计
|
|
- 不破坏现有功能和组件复用性
|
|
- 新功能开发前先了解相关代码结构
|
|
- 遇到问题先查看文档和现有代码
|
|
- 定期进行代码审查和重构
|
|
|