3.7 KiB
3.7 KiB
开发指南
🚀 快速开始
前置要求
- Docker & Docker Compose
- Node.js 18+
- Python 3.12+
- Git
一键启动
# Linux/Mac
./scripts/start.sh
# Windows
scripts\start.bat
手动启动
后端开发
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
前端开发
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
- 提交前运行测试和格式化
🧪 测试
后端测试
cd backend
pytest # 运行所有测试
pytest tests/test_health.py # 运行特定测试
pytest --cov=app # 生成覆盖率报告
前端测试
cd frontend
npm test # 运行测试
npm run test:e2e # E2E测试
🚀 部署
开发环境
docker-compose up -d
生产环境
./scripts/deploy.sh
🔍 调试
查看日志
docker-compose logs -f # 所有服务日志
docker-compose logs backend # 后端日志
docker-compose logs frontend # 前端日志
健康检查
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有足够权限访问文件系统
📞 支持
如有问题请查看：