xsl_node/backend/docs/后端依赖管理文档.md

后端依赖管理文档

文档信息

• 文档版本: V1.0
• 创建日期: 2026-01-26
• 文档类型: 后端依赖管理文档

---

1. 依赖管理工具

本项目使用以下工具管理依赖：

1.1 Poetry (推荐)

Poetry 是一个现代化的 Python 依赖管理和打包工具，提供了更简洁、更一致的依赖管理体验。

安装 Poetry:

# 使用 pip 安装
pip install poetry

# 或使用官方安装脚本
curl -sSL https://install.python-poetry.org | python3 -

1.2 pip

如果您不使用 Poetry，也可以使用 pip 管理依赖。

---

2. 核心依赖

2.1 主要依赖

依赖	版本	用途
fastapi	^0.104.0	后端 Web 框架
uvicorn[standard]	^0.24.0	ASGI 服务器
sqlalchemy	^2.0.0	ORM 框架
pymysql	^1.1.0	MySQL 数据库驱动
python-jose[cryptography]	^3.3.0	JWT 库
passlib[bcrypt]	^1.7.4	密码哈希库
pydantic	^2.5.0	数据验证库
pydantic-settings	^2.1.0	配置管理库
alembic	^1.12.0	数据库迁移工具
python-multipart	^0.0.6	表单数据处理
python-dotenv	^1.0.0	环境变量管理
aiomysql	^0.2.0	异步 MySQL 驱动

2.2 开发依赖

依赖	版本	用途
pytest	^7.4.0	测试框架
pytest-asyncio	^0.21.0	异步测试支持
pytest-cov	^4.1.0	测试覆盖率
flake8	^6.1.0	代码风格检查
black	^23.11.0	代码格式化
isort	^5.12.0	导入排序
mypy	^1.7.0	类型检查

---

3. 配置文件

3.1 pyproject.toml (Poetry)

[tool.poetry]
name = "project-management-backend"
version = "0.1.0"
description = "项目管理系统后端"
authors = [{ name = "Developer", email = "developer@example.com" }]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.104.0"
uvicorn = { version = "^0.24.0", extras = ["standard"] }
sqlalchemy = "^2.0.0"
pymysql = "^1.1.0"
python-jose = { version = "^3.3.0", extras = ["cryptography"] }
passlib = { version = "^1.7.4", extras = ["bcrypt"] }
pydantic = "^2.5.0"
pydantic-settings = "^2.1.0"
alembic = "^1.12.0"
python-multipart = "^0.0.6"
python-dotenv = "^1.0.0"
aiomysql = "^0.2.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
pytest-asyncio = "^0.21.0"
pytest-cov = "^4.1.0"
flake8 = "^6.1.0"
black = "^23.11.0"
isort = "^5.12.0"
mypy = "^1.7.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

3.2 requirements.txt (pip)

fastapi==0.104.0
uvicorn[standard]==0.24.0
sqlalchemy==2.0.0
pymysql==1.1.0
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
pydantic==2.5.0
pydantic-settings==2.1.0
alembic==1.12.0
python-multipart==0.0.6
python-dotenv==1.0.0
aiomysql==0.2.0

# 开发依赖
pytest==7.4.0
pytest-asyncio==0.21.0
pytest-cov==4.1.0
flake8==6.1.0
black==23.11.0
isort==5.12.0
mypy==1.7.0

---

4. 依赖管理命令

4.1 使用 Poetry

安装依赖

# 安装所有依赖（包括开发依赖）
poetry install

# 仅安装生产依赖
poetry install --no-dev

添加依赖

# 添加生产依赖
poetry add <package>

# 添加开发依赖
poetry add --group dev <package>

更新依赖

# 更新所有依赖
poetry update

# 更新特定依赖
poetry update <package>

导出依赖

# 导出到 requirements.txt
poetry export --output requirements.txt

# 导出生产依赖
poetry export --output requirements.txt --without dev

运行命令

# 在虚拟环境中运行命令
poetry run <command>

# 例如运行开发服务器
poetry run uvicorn app.main:app --reload

# 例如运行测试
poetry run pytest

4.2 使用 pip

安装依赖

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

# 安装生产依赖（需要单独创建生产依赖文件）
pip install -r requirements-prod.txt

添加依赖

# 安装并添加到 requirements.txt
pip install <package> && pip freeze | grep <package> >> requirements.txt

更新依赖

# 更新所有依赖
pip install --upgrade -r requirements.txt

# 更新特定依赖
pip install --upgrade <package>

---

5. 环境配置

5.1 环境变量

项目使用 .env 文件管理环境变量，示例配置如下：

# 数据库连接信息
DATABASE_URL="mysql+pymysql://username:password@localhost:3306/project_management"

# JWT 配置
SECRET_KEY="your-secret-key"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30

# 应用配置
APP_NAME="Project Management System"
DEBUG=True

5.2 配置文件

项目使用 app/config.py 管理应用配置：

from pydantic_settings import BaseSettings
from functools import lru_cache


class Settings(BaseSettings):
    """应用配置"""
    # 应用配置
    app_name: str = "Project Management System"
    debug: bool = True
    
    # 数据库配置
    database_url: str
    
    # JWT 配置
    secret_key: str
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
    
    class Config:
        env_file = ".env"
        case_sensitive = False


@lru_cache()
def get_settings() -> Settings:
    """获取配置实例"""
    return Settings()


settings = get_settings()

---

6. 依赖版本管理

6.1 版本约束

Poetry 使用语义化版本约束，常见的版本约束格式：

格式	说明	示例
^1.0.0	兼容 1.x.x 版本	^2.0.0 匹配 2.0.0, 2.1.0 但不匹配 3.0.0
~1.0.0	兼容 1.0.x 版本	~1.0.0 匹配 1.0.0, 1.0.1 但不匹配 1.1.0
>=1.0.0	大于等于 1.0.0	>=2.0.0 匹配 2.0.0, 3.0.0
==1.0.0	精确匹配 1.0.0	==1.0.0 只匹配 1.0.0

6.2 依赖锁定

Poetry 使用 poetry.lock 文件锁定依赖版本，确保在不同环境中安装相同版本的依赖：

# 生成锁定文件
poetry lock

# 使用锁定文件安装依赖
poetry install

6.3 依赖解析

如果遇到依赖冲突，可以使用以下方法解决：

1. 更新依赖版本：尝试更新冲突的依赖版本
2. 指定版本：为冲突的依赖指定兼容的版本
3. 使用虚拟环境：为不同项目使用独立的虚拟环境

---

7. 开发最佳实践

7.1 依赖管理建议

1. 定期更新依赖：定期更新依赖以获取安全补丁和新特性
2. 使用锁定文件：在生产环境中使用锁定文件确保依赖版本一致
3. 分离开发和生产依赖：只在生产环境中安装必要的依赖
4. 使用虚拟环境：为每个项目使用独立的虚拟环境
5. 记录依赖变更：在提交代码时同时提交依赖变更

7.2 安全注意事项

1. 检查依赖安全：使用安全扫描工具检查依赖的安全漏洞
2. 使用可信依赖：只使用来自可信源的依赖
3. 固定依赖版本：在生产环境中固定依赖版本，避免自动更新引入问题
4. 定期审计依赖：定期审计项目依赖，移除不再使用的依赖

---

8. 常见问题

8.1 依赖安装失败

问题：依赖安装失败，出现版本冲突

解决方法：

1. 检查 Python 版本是否兼容
2. 尝试使用 poetry update 更新依赖
3. 检查网络连接是否正常
4. 尝试清理缓存：poetry cache clear --all pypi

8.2 数据库连接失败

问题：无法连接到数据库

解决方法：

1. 检查数据库服务是否运行
2. 检查数据库连接字符串是否正确
3. 检查数据库用户权限是否正确
4. 检查网络连接是否正常

8.3 JWT 认证失败

问题：JWT 认证失败

解决方法：

1. 检查 SECRET_KEY 是否正确设置
2. 检查 Token 是否过期
3. 检查 Token 格式是否正确
4. 检查认证中间件配置是否正确

---

9. 附录

9.1 Python 版本要求

本项目要求 Python 3.9 或更高版本。

9.2 开发工具推荐

工具	用途	安装命令
Poetry	依赖管理	pip install poetry
PyCharm	IDE	官网下载
VS Code	编辑器	官网下载
MySQL Workbench	数据库管理	官网下载

9.3 变更记录

版本	日期	修改人	修改内容
V1.0	2026-01-26	-	初始版本创建