285 lines
6.4 KiB
Markdown
285 lines
6.4 KiB
Markdown
# 资产管理系统 - 后端API
|
||
|
||
基于 FastAPI + SQLAlchemy + PostgreSQL 的企业级资产管理系统后端API
|
||
|
||
## 技术栈
|
||
|
||
- **框架**: FastAPI 0.104+
|
||
- **ORM**: SQLAlchemy 2.0+ (异步模式)
|
||
- **数据库**: PostgreSQL 14+
|
||
- **缓存**: Redis
|
||
- **认证**: JWT (python-jose)
|
||
- **密码加密**: bcrypt
|
||
- **数据验证**: Pydantic v2
|
||
- **数据库迁移**: Alembic
|
||
- **测试**: pytest
|
||
- **ASGI服务器**: Uvicorn
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
asset_management_backend/
|
||
├── app/
|
||
│ ├── api/ # API路由
|
||
│ │ └── v1/
|
||
│ │ ├── auth.py # 认证相关API
|
||
│ │ └── __init__.py
|
||
│ ├── core/ # 核心模块
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── security.py # 安全相关
|
||
│ │ ├── deps.py # 依赖注入
|
||
│ │ ├── exceptions.py # 自定义异常
|
||
│ │ └── response.py # 统一响应
|
||
│ ├── crud/ # 数据库CRUD操作
|
||
│ │ ├── user.py # 用户CRUD
|
||
│ │ └── ...
|
||
│ ├── db/ # 数据库相关
|
||
│ │ ├── base.py # 模型基类
|
||
│ │ └── session.py # 会话管理
|
||
│ ├── models/ # SQLAlchemy模型
|
||
│ │ ├── user.py # 用户模型
|
||
│ │ └── ...
|
||
│ ├── schemas/ # Pydantic Schema
|
||
│ │ ├── user.py # 用户Schema
|
||
│ │ └── ...
|
||
│ ├── services/ # 业务逻辑层
|
||
│ │ ├── auth_service.py # 认证服务
|
||
│ │ └── ...
|
||
│ └── utils/ # 工具函数
|
||
│ └── ...
|
||
├── alembic/ # 数据库迁移
|
||
│ └── versions/
|
||
├── tests/ # 测试
|
||
├── logs/ # 日志文件
|
||
├── uploads/ # 上传文件
|
||
├── .env.example # 环境变量示例
|
||
├── requirements.txt # 依赖包
|
||
├── run.py # 开发服务器启动脚本
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备
|
||
|
||
确保已安装：
|
||
- Python 3.10+
|
||
- PostgreSQL 14+
|
||
- Redis
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
|
||
# 激活虚拟环境
|
||
# Windows:
|
||
venv\Scripts\activate
|
||
# Linux/Mac:
|
||
source venv/bin/activate
|
||
|
||
# 安装依赖包
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量示例文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，配置数据库等信息
|
||
```
|
||
|
||
### 4. 初始化数据库
|
||
|
||
```bash
|
||
# 创建数据库
|
||
createdb asset_management
|
||
|
||
# 运行数据库迁移
|
||
alembic upgrade head
|
||
|
||
# 或在开发环境直接初始化（会自动创建表）
|
||
# 修改 app/main.py 中的 lifespan 函数，取消注释 init_db()
|
||
```
|
||
|
||
### 5. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（支持热重载）
|
||
python run.py
|
||
|
||
# 或使用 uvicorn
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 6. 访问API文档
|
||
|
||
启动成功后，访问以下地址：
|
||
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
- OpenAPI JSON: http://localhost:8000/openapi.json
|
||
|
||
## API端点
|
||
|
||
### 认证模块
|
||
|
||
- `POST /api/v1/auth/login` - 用户登录
|
||
- `POST /api/v1/auth/refresh` - 刷新令牌
|
||
- `POST /api/v1/auth/logout` - 用户登出
|
||
- `PUT /api/v1/auth/change-password` - 修改密码
|
||
- `GET /api/v1/auth/captcha` - 获取验证码
|
||
|
||
### 用户管理
|
||
|
||
- `GET /api/v1/users` - 用户列表
|
||
- `POST /api/v1/users` - 创建用户
|
||
- `GET /api/v1/users/{user_id}` - 获取用户详情
|
||
- `PUT /api/v1/users/{user_id}` - 更新用户
|
||
- `DELETE /api/v1/users/{user_id}` - 删除用户
|
||
- `POST /api/v1/users/{user_id}/reset-password` - 重置密码
|
||
- `GET /api/v1/users/me` - 获取当前用户信息
|
||
|
||
### 角色权限
|
||
|
||
- `GET /api/v1/roles` - 角色列表
|
||
- `POST /api/v1/roles` - 创建角色
|
||
- `GET /api/v1/roles/{role_id}` - 获取角色详情
|
||
- `PUT /api/v1/roles/{role_id}` - 更新角色
|
||
- `DELETE /api/v1/roles/{role_id}` - 删除角色
|
||
- `GET /api/v1/permissions/tree` - 权限树列表
|
||
|
||
更多API请查看Swagger文档。
|
||
|
||
## 开发规范
|
||
|
||
请参考 `development_standards_guide.md` 文件。
|
||
|
||
### 代码风格
|
||
|
||
- 遵循 PEP 8 规范
|
||
- 使用 Black 进行代码格式化
|
||
- 使用 isort 管理导入
|
||
- 使用 flake8 进行代码检查
|
||
- 使用 mypy 进行类型检查
|
||
|
||
### 提交规范
|
||
|
||
遵循 Conventional Commits 规范：
|
||
|
||
```
|
||
feat: 新功能
|
||
fix: Bug修复
|
||
docs: 文档更新
|
||
style: 代码格式
|
||
refactor: 重构
|
||
perf: 性能优化
|
||
test: 测试
|
||
chore: 构建/工具
|
||
```
|
||
|
||
示例：
|
||
```bash
|
||
git commit -m "feat(auth): 实现用户登录功能"
|
||
git commit -m "fix(asset): 修复资产状态转换问题"
|
||
```
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试文件
|
||
pytest tests/api/test_auth.py
|
||
|
||
# 生成覆盖率报告
|
||
pytest --cov=app --cov-report=html
|
||
|
||
# 查看覆盖率报告
|
||
open htmlcov/index.html
|
||
```
|
||
|
||
## 数据库迁移
|
||
|
||
```bash
|
||
# 创建新的迁移
|
||
alembic revision --autogenerate -m "描述信息"
|
||
|
||
# 执行迁移
|
||
alembic upgrade head
|
||
|
||
# 回滚迁移
|
||
alembic downgrade -1
|
||
|
||
# 查看迁移历史
|
||
alembic history
|
||
|
||
# 查看当前版本
|
||
alembic current
|
||
```
|
||
|
||
## 生产部署
|
||
|
||
### 使用 Docker
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t asset-management-backend .
|
||
|
||
# 运行容器
|
||
docker run -d \
|
||
--name asset-backend \
|
||
-p 8000:8000 \
|
||
--env-file .env \
|
||
asset-management-backend
|
||
```
|
||
|
||
### 使用 Gunicorn + Uvicorn
|
||
|
||
```bash
|
||
pip install gunicorn
|
||
|
||
gunicorn app.main:app \
|
||
--workers 4 \
|
||
--worker-class uvicorn.workers.UvicornWorker \
|
||
--bind 0.0.0.0:8000 \
|
||
--access-logfile - \
|
||
--error-logfile -
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 数据库连接失败
|
||
|
||
检查 `DATABASE_URL` 是否正确配置，确保PostgreSQL服务正在运行。
|
||
|
||
### Redis连接失败
|
||
|
||
检查 `REDIS_URL` 是否正确配置，确保Redis服务正在运行。
|
||
|
||
### Token验证失败
|
||
|
||
确保 `SECRET_KEY` 配置正确，并检查Token是否过期。
|
||
|
||
## 贡献指南
|
||
|
||
1. Fork 本仓库
|
||
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
|
||
3. 提交更改 (`git commit -m 'feat: Add some AmazingFeature'`)
|
||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证。
|
||
|
||
## 联系方式
|
||
|
||
- 项目负责人: 老王
|
||
- 创建时间: 2025-01-24
|
||
- 版本: v1.0.0
|