6.7 KiB
6.7 KiB
开发指南
版本历史
| 版本 | 日期 | 修改人 | 修改内容 |
|---|---|---|---|
| 1.0.0 | 2024-01-20 | 开发团队 | 初始版本 |
1. 开发环境搭建
1.1 系统要求
- 操作系统: macOS 10.15+, Ubuntu 18.04+, Windows 10+
- Node.js: 16.x 或更高版本
- MySQL: 8.0 或更高版本
- Redis: 6.0 或更高版本
- Git: 2.20 或更高版本
1.2 开发工具推荐
- IDE: VS Code, WebStorm
- 数据库管理: Navicat, DBeaver
- API测试: Postman, Insomnia
- 版本控制: Git, SourceTree
1.3 环境安装
1.3.1 Node.js 环境
# 使用 nvm 管理 Node.js 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18
1.3.2 数据库安装
# MySQL 安装 (macOS)
brew install mysql
brew services start mysql
# Redis 安装 (macOS)
brew install redis
brew services start redis
1.3.3 项目克隆与依赖安装
# 克隆项目
git clone https://github.com/your-org/niumall.git
cd niumall
# 安装后端依赖
cd backend
npm install
# 安装前端管理系统依赖
cd ../admin-system
npm install
# 安装小程序依赖
cd ../mini_program/staff-mp
npm install
2. 项目结构
niumall/
├── backend/ # 后端服务 (Node.js)
│ ├── src/
│ │ ├── controllers/ # 控制器
│ │ ├── models/ # 数据模型
│ │ ├── services/ # 业务逻辑
│ │ ├── middleware/ # 中间件
│ │ ├── routes/ # 路由配置
│ │ └── utils/ # 工具函数
│ └── package.json
├── admin-system/ # 前端管理系统 (Vue3 + TypeScript)
│ ├── src/
│ │ ├── views/ # 页面组件
│ │ ├── api/ # API服务
│ │ ├── utils/ # 工具函数
│ │ └── stores/ # 状态管理
│ └── package.json
├── mini_program/ # 小程序矩阵
│ ├── staff-mp/ # 员工小程序
│ ├── driver-mp/ # 司机小程序
│ ├── supplier-mp/ # 供应商小程序
│ └── client-mp/ # 客户小程序
├── go-backend/ # Go后端服务 (备选)
├── fastapi-backend/ # FastAPI后端服务 (备选)
├── website/ # 官方网站
└── docs/ # 项目文档
3. 开发流程
3.1 分支管理
采用 Git Flow 工作流：
- main: 生产环境分支
- develop: 开发环境分支
- feature/*: 功能开发分支
- hotfix/*: 紧急修复分支
- release/*: 发布准备分支
3.2 开发步骤
- 创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/订单管理优化
- 开发与提交
# 开发完成后提交
git add .
git commit -m "feat: 添加订单状态自动更新功能"
- 代码审查
# 推送到远程分支
git push origin feature/订单管理优化
# 在 GitHub/GitLab 创建 Pull Request
3.3 提交规范
使用 Conventional Commits 规范：
feat: 新功能fix: 修复bugdocs: 文档更新style: 代码格式调整refactor: 代码重构test: 测试相关chore: 构建过程或辅助工具的变动
4. 本地开发
4.1 环境配置
4.1.1 后端配置
创建 backend/.env 文件：
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=niumall
DB_USER=root
DB_PASSWORD=your_password
# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
# JWT配置
JWT_SECRET=your_jwt_secret
JWT_EXPIRES_IN=7d
# 微信小程序配置
WECHAT_APP_ID=your_app_id
WECHAT_APP_SECRET=your_app_secret
4.1.2 前端配置
创建 admin-system/.env.development 文件：
# API基础URL
VITE_API_BASE_URL=http://localhost:3000/api
VITE_UPLOAD_URL=http://localhost:3000/uploads
4.2 启动服务
4.2.1 启动后端服务
cd backend
npm run dev
# 服务启动在 http://localhost:3000
4.2.2 启动前端管理系统
cd admin-system
npm run dev
# 服务启动在 http://localhost:5173
4.2.3 启动小程序开发
cd mini_program/staff-mp
# 使用微信开发者工具打开项目目录
4.3 数据库初始化
# 创建数据库
mysql -u root -p
CREATE DATABASE niumall CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
# 运行初始化脚本
cd backend
node init_database.js
5. 代码规范
5.1 JavaScript/TypeScript 规范
- 使用 ESLint + Prettier 进行代码格式化
- 遵循 Airbnb JavaScript 风格指南
- 使用 TypeScript 进行类型检查
5.2 Vue 组件规范
- 使用 Composition API
- 组件命名采用 PascalCase
- Props 定义使用 TypeScript 接口
5.3 API 接口规范
- 遵循 RESTful 设计原则
- 统一的响应格式
- 完善的错误处理
6. 测试指南
6.1 单元测试
# 运行后端单元测试
cd backend
npm test
# 运行前端单元测试
cd admin-system
npm run test:unit
6.2 API测试
使用 Postman 或 Insomnia 进行 API 测试，测试文件位于 docs/api/ 目录。
7. 调试技巧
7.1 后端调试
- 使用 VS Code 调试配置
- 查看日志文件
- 使用 Postman 测试 API
7.2 前端调试
- 使用浏览器开发者工具
- Vue DevTools 扩展
- 网络请求监控
7.3 小程序调试
- 微信开发者工具调试器
- 真机调试
- 性能监控
8. 常见问题
8.1 环境问题
Q: 数据库连接失败
# 检查数据库服务状态
brew services list | grep mysql
# 重启数据库服务
brew services restart mysql
Q: 端口被占用
# 查看端口占用
lsof -i :3000
# 杀死进程
kill -9 <PID>
8.2 开发问题
Q: 热重载不生效
# 清除缓存重启
rm -rf node_modules/.cache
npm run dev
Q: 小程序真机预览失败
- 检查网络连接
- 确认域名配置
- 查看控制台错误信息
9. 性能优化
9.1 后端优化
- 数据库查询优化
- Redis 缓存策略
- 异步处理优化
9.2 前端优化
- 代码分割
- 懒加载
- 图片优化
9.3 小程序优化
- 分包加载
- 图片压缩
- 请求合并
10. 联系信息
- 技术支持: tech-support@company.com
- 开发团队: dev-team@company.com
- 文档维护: docs@company.com