188 lines
3.7 KiB
Markdown
188 lines
3.7 KiB
Markdown
# 开发指南
|
|
|
|
## 🚀 快速开始
|
|
|
|
### 前置要求
|
|
- Docker & Docker Compose
|
|
- Node.js 18+
|
|
- Python 3.12+
|
|
- Git
|
|
|
|
### 一键启动
|
|
```bash
|
|
# Linux/Mac
|
|
./scripts/start.sh
|
|
|
|
# Windows
|
|
scripts\start.bat
|
|
```
|
|
|
|
### 手动启动
|
|
|
|
#### 后端开发
|
|
```bash
|
|
cd backend
|
|
|
|
# 创建虚拟环境
|
|
python -m venv venv
|
|
source venv/bin/activate # Windows: venv\Scripts\activate
|
|
|
|
# 安装依赖
|
|
pip install -r requirements-dev.txt
|
|
|
|
# 运行测试
|
|
pytest
|
|
|
|
# 启动开发服务器
|
|
uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
#### 前端开发
|
|
```bash
|
|
cd frontend
|
|
|
|
# 安装依赖
|
|
npm install
|
|
|
|
# 启动开发服务器
|
|
npm run dev
|
|
|
|
# 运行测试
|
|
npm test
|
|
|
|
# 构建生产版本
|
|
npm run build
|
|
```
|
|
|
|
## 🏗️ 项目结构
|
|
|
|
```
|
|
full-stack-doc/
|
|
├── backend/ # FastAPI后端
|
|
│ ├── app/
|
|
│ │ ├── api/ # API路由
|
|
│ │ ├── core/ # 核心配置
|
|
│ │ ├── models/ # 数据模型
|
|
│ │ ├── services/ # 业务逻辑
|
|
│ │ └── utils/ # 工具函数
|
|
│ ├── tests/ # 测试文件
|
|
│ ├── database/ # 数据库脚本
|
|
│ └── main.py # 应用入口
|
|
├── frontend/ # React前端
|
|
│ ├── src/
|
|
│ │ ├── components/ # 组件
|
|
│ │ ├── pages/ # 页面
|
|
│ │ ├── services/ # API服务
|
|
│ │ ├── hooks/ # 自定义钩子
|
|
│ │ ├── utils/ # 工具函数
|
|
│ │ └── types/ # TypeScript类型
|
|
│ └── public/ # 静态资源
|
|
├── docs/ # 项目文档
|
|
├── scripts/ # 部署脚本
|
|
└── docker-compose.yml # Docker编排
|
|
```
|
|
|
|
## 🔧 开发工具
|
|
|
|
### 后端
|
|
- **FastAPI**: Web框架
|
|
- **SQLAlchemy**: ORM
|
|
- **Pydantic**: 数据验证
|
|
- **Pytest**: 测试框架
|
|
- **Black**: 代码格式化
|
|
- **iSort**: 导入排序
|
|
|
|
### 前端
|
|
- **React 19**: UI框架
|
|
- **TypeScript**: 类型安全
|
|
- **Vite**: 构建工具
|
|
- **TailwindCSS**: 样式框架
|
|
- **Vitest**: 测试框架
|
|
- **ESLint**: 代码检查
|
|
|
|
## 📝 开发规范
|
|
|
|
### Git提交规范
|
|
```
|
|
feat: 新功能
|
|
fix: 修复bug
|
|
docs: 文档更新
|
|
style: 代码格式调整
|
|
refactor: 代码重构
|
|
test: 测试相关
|
|
chore: 构建过程或辅助工具的变动
|
|
```
|
|
|
|
### 代码规范
|
|
- 后端遵循PEP 8
|
|
- 前端使用ESLint + Prettier
|
|
- 提交前运行测试和格式化
|
|
|
|
## 🧪 测试
|
|
|
|
### 后端测试
|
|
```bash
|
|
cd backend
|
|
pytest # 运行所有测试
|
|
pytest tests/test_health.py # 运行特定测试
|
|
pytest --cov=app # 生成覆盖率报告
|
|
```
|
|
|
|
### 前端测试
|
|
```bash
|
|
cd frontend
|
|
npm test # 运行测试
|
|
npm run test:e2e # E2E测试
|
|
```
|
|
|
|
## 🚀 部署
|
|
|
|
### 开发环境
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### 生产环境
|
|
```bash
|
|
./scripts/deploy.sh
|
|
```
|
|
|
|
## 🔍 调试
|
|
|
|
### 查看日志
|
|
```bash
|
|
docker-compose logs -f # 所有服务日志
|
|
docker-compose logs backend # 后端日志
|
|
docker-compose logs frontend # 前端日志
|
|
```
|
|
|
|
### 健康检查
|
|
```bash
|
|
curl http://localhost:8000/api/v1/health
|
|
curl http://localhost:8000/api/v1/ready
|
|
```
|
|
|
|
## 📚 API文档
|
|
- Swagger UI: http://localhost:8000/docs
|
|
- ReDoc: http://localhost:8000/redoc
|
|
|
|
## 🆘 常见问题
|
|
|
|
### 1. 端口冲突
|
|
修改docker-compose.yml中的端口映射
|
|
|
|
### 2. 数据库连接失败
|
|
检查MySQL服务是否正常启动
|
|
|
|
### 3. 前端构建失败
|
|
删除node_modules重新安装依赖
|
|
|
|
### 4. 权限问题
|
|
确保Docker有足够权限访问文件系统
|
|
|
|
## 📞 支持
|
|
|
|
如有问题请查看：
|
|
1. [项目文档](docs/)
|
|
2. [API文档](http://localhost:8000/docs)
|
|
3. [GitHub Issues](https://github.com/your-repo/issues) |