# 开发者指南 ## 📖 目录 - [开发环境搭建](#开发环境搭建) - [项目结构说明](#项目结构说明) - [代码规范](#代码规范) - [开发流程](#开发流程) - [常用功能示例](#常用功能示例) - [调试技巧](#调试技巧) - [常见问题](#常见问题) ## 🛠️ 开发环境搭建 ### 1. 安装必要工具 ```bash # 安装 Node.js (推荐使用 nvm) nvm install 16 nvm use 16 # 安装 pnpm (可选,替代 npm) npm install -g pnpm # 安装依赖 npm install # 或 pnpm install ``` ### 2. 配置开发环境 ```bash # 复制环境变量文件 cp .env.development.example .env.development # 编辑 .env.development # 配置后端 API 地址 VITE_API_URL=http://localhost:8000 ``` ### 3. 启动开发服务器 ```bash npm run dev ``` ## 📁 项目结构说明 ### 核心目录 #### `/src/api/` - API 接口 ```typescript // 示例:src/api/login/index.ts import request from '/@/utils/service' export function login(data: any) { return request({ url: '/api/system/auth/login/', method: 'post', data }) } ``` #### `/src/views/` - 页面视图 ``` views/ ├── position/ # 职位管理页面 │ ├── list/ # 职位列表 │ ├── detail/ # 职位详情 │ └── crud.tsx # CRUD 配置 ├── questionBank/ # 题库管理 ├── talent/ # 人才管理 └── system/ # 系统管理 ``` #### `/src/components/` - 公共组件 - `auth/` - 权限控制组件 - `editor/` - 富文本编辑器 - `fileSelector/` - 文件选择器 - `table/` - 表格组件 #### `/src/utils/` - 工具函数 - `request.ts` - 请求封装 - `message.ts` - 消息提示 - `storage.ts` - 本地存储 - `formatTime.ts` - 时间格式化 #### `/src/stores/` - 状态管理 ```typescript // 示例:src/stores/userInfo.ts import { defineStore } from 'pinia' export const useUserInfo = defineStore('userInfo', { state: () => ({ userName: '', avatar: '' }), persist: { enabled: true } }) ``` ## 📝 代码规范 ### 1. TypeScript 规范 ```typescript // ✅ 正确:明确的类型定义 interface UserInfo { id: number name: string email: string } function getUserInfo(id: number): Promise { return request({ url: `/api/user/${id}/`, method: 'get' }) } // ❌ 错误:使用 any function getUserInfo(id: any): any { // ... } ``` ### 2. Vue 3 规范 ```vue ``` ### 3. 命名规范 - **组件名**:PascalCase - `UserManagement.vue` - **文件名**:kebab-case - `user-info.vue` - **变量/函数**:camelCase - `getUserInfo` - **常量**:UPPER_SNAKE_CASE - `API_BASE_URL` - **类型/接口**:PascalCase - `UserInfo` ### 4. 文件组织 ``` component/ ├── index.vue # 主组件 ├── components/ # 子组件 │ ├── Form.vue │ └── List.vue ├── api.ts # API 接口 ├── types.ts # 类型定义 └── crud.tsx # CRUD 配置(如需要) ``` ## 🔄 开发流程 ### 1. 创建新功能模块 #### 步骤一:创建目录结构 ```bash src/views/newFeature/ ├── index.vue # 主页面 ├── api.ts # API 接口 ├── types.ts # 类型定义 └── components/ # 子组件 └── Dialog.vue ``` #### 步骤二:定义类型 ```typescript // src/views/newFeature/types.ts export interface FeatureItem { id: number name: string description: string status: 'active' | 'inactive' } ``` #### 步骤三:定义 API ```typescript // src/views/newFeature/api.ts import request from '/@/utils/service' export function getFeatureList(params: any) { return request({ url: '/api/feature/', method: 'get', params }) } export function createFeature(data: any) { return request({ url: '/api/feature/', method: 'post', data }) } ``` #### 步骤四:创建页面 ```vue ``` ### 2. 使用 FastCRUD ```typescript // src/views/feature/crud.tsx import { useCrud } from '@fast-crud/fast-crud' import { createFeature, updateFeature, deleteFeature } from './api' export default useCrud({ async doAdd({ form }) { await createFeature(form) }, async doEdit({ form }) { await updateFeature(form.id, form) }, async doDel({ row }) { await deleteFeature(row.id) } }) ``` ## 💡 常用功能示例 ### 0. 项目中的实际示例 查看现有业务模块代码以了解项目风格: - **职位管理**:`src/views/position/` - 复杂的职位详情编辑 - **题库管理**:`src/views/questionBank/` - 题目CRUD和管理 - **系统管理**:`src/views/system/account/` - 用户管理示例 - **求职申请**:`src/views/JobApplication/` - 申请状态管理 ### 1. 权限控制 ```vue ``` ### 2. 消息提示 ```typescript import { successMessage, warningMessage, errorMessage } from '/@/utils/message' // 成功提示 successMessage('操作成功') // 警告提示 warningMessage('请填写完整信息') // 错误提示 errorMessage('操作失败') ``` ### 3. 表格操作 ```vue ``` ### 4. 表单验证 ```vue ``` ### 5. 文件上传 ```vue ``` ### 6. 富文本编辑器 ```vue ``` ### 7. 字典数据获取 ```vue ``` ### 8. 本地存储 ```typescript import { Local } from '/@/utils/storage' // 保存数据 Local.set('key', { data: 'value' }) // 获取数据 const data = Local.get('key') // 删除数据 Local.remove('key') ``` ### 9. 路由跳转 ```typescript import { useRouter } from 'vue-router' const router = useRouter() // 普通跳转 router.push('/position/list') // 带参数跳转 router.push({ path: '/position/detail', query: { id: 123 } }) // 在新标签页打开 window.open(`/position/detail?id=123`) ``` ### 10. 表格数据操作 ```vue ``` ## 🐛 调试技巧 ### 1. Vue DevTools 安装 Vue DevTools 浏览器插件,用于: - 查看组件树 - 检查组件状态 - 追踪组件更新 - 性能分析 ### 2. 控制台调试 ```typescript // 打印日志 console.log('Data:', data) // 打印表格 console.table(dataList) // 断点调试 debugger // 打印组件实例 console.log(this.$refs.myComponent) ``` ### 3. Vite HMR 修改代码后,Vite 会自动热更新,无需手动刷新页面。 ### 4. 网络请求调试 使用浏览器开发者工具的 Network 面板: - 查看请求/响应 - 检查请求头 - 查看响应数据 ## ❓ 常见问题 ### 1. 依赖安装失败 ```bash # 清除缓存 npm cache clean --force # 删除 node_modules rm -rf node_modules # 重新安装 npm install ``` ### 2. 端口被占用 ```bash # 修改 vite.config.ts 中的端口 server: { port: 3000 // 改为其他端口 } ``` ### 3. TypeScript 类型错误 ```bash # 重新生成类型声明 npm run type-check ``` ### 4. 样式不生效 - 检查样式文件导入 - 检查 scoped 属性 - 检查 Tailwind CSS 配置 ### 5. 路由跳转失败 ```typescript // 使用 router.push import { useRouter } from 'vue-router' const router = useRouter() router.push('/path') ``` ## 📚 参考资料 - [Vue 3 官方文档](https://cn.vuejs.org/) - [Element Plus 文档](https://element-plus.org/) - [FastCRUD 文档](http://fast-crud.docmirror.cn/) - [Pinia 文档](https://pinia.vuejs.org/) - [TypeScript 文档](https://www.typescriptlang.org/) ## 🎯 最佳实践 ### 1. 组件拆分 保持组件精简,单一职责。 ### 2. 代码复用 提取公共逻辑到 hooks 或 utils。 ### 3. 性能优化 - 使用 v-if 替代 v-show - 使用 computed 缓存计算 - 大列表使用虚拟滚动 ### 4. 错误处理 ```typescript try { await saveData() successMessage('保存成功') } catch (error) { errorMessage('保存失败') console.error(error) } ``` --- **提示**:遇到问题时,先查阅文档,然后查看已有代码实现,最后在团队中讨论。