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

# 后端依赖管理文档

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

---

## 1. 依赖管理工具

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

### 1.1 Poetry (推荐)

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

**安装 Poetry**:
```bash
# 使用 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)

```toml
[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

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

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

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

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

#### 更新依赖
```bash
# 更新所有依赖
poetry update

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

#### 导出依赖
```bash
# 导出到 requirements.txt
poetry export --output requirements.txt

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

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

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

# 例如运行测试
poetry run pytest
```

### 4.2 使用 pip

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

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

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

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

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

---

## 5. 环境配置

### 5.1 环境变量

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

```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` 管理应用配置：

```python
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` 文件锁定依赖版本，确保在不同环境中安装相同版本的依赖：

```bash
# 生成锁定文件
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 | [官网下载](https://www.jetbrains.com/pycharm/) |
| VS Code | 编辑器 | [官网下载](https://code.visualstudio.com/) |
| MySQL Workbench | 数据库管理 | [官网下载](https://www.mysql.com/products/workbench/) |

### 9.3 变更记录

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