资产管理系统 - 后端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. 安装依赖

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安装依赖包
pip install -r requirements.txt

3. 配置环境变量

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置数据库等信息

4. 初始化数据库

# 创建数据库
createdb asset_management

# 运行数据库迁移
alembic upgrade head

# 或在开发环境直接初始化（会自动创建表）
# 修改 app/main.py 中的 lifespan 函数，取消注释 init_db()

5. 启动服务

# 开发模式（支持热重载）
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: 构建/工具

示例：

git commit -m "feat(auth): 实现用户登录功能"
git commit -m "fix(asset): 修复资产状态转换问题"

测试

# 运行所有测试
pytest

# 运行特定测试文件
pytest tests/api/test_auth.py

# 生成覆盖率报告
pytest --cov=app --cov-report=html

# 查看覆盖率报告
open htmlcov/index.html

数据库迁移

# 创建新的迁移
alembic revision --autogenerate -m "描述信息"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 查看当前版本
alembic current

生产部署

使用 Docker

# 构建镜像
docker build -t asset-management-backend .

# 运行容器
docker run -d \
  --name asset-backend \
  -p 8000:8000 \
  --env-file .env \
  asset-management-backend

使用 Gunicorn + Uvicorn

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