Python 最佳实践项目

本项目旨在展示现代 Python 工程的最佳实践，使用了 FastAPI、SQLAlchemy (Async)、Pydantic 和 Alembic 等技术。

特性

• FastAPI: 现代、快速（高性能）的 Web 框架，基于标准 Python 类型提示构建 API，支持 Python 3.6+。
• SQLAlchemy 2.0 (AsyncIO): 支持异步操作的数据库 ORM。
• Pydantic 2.0: 使用 Python 类型注解进行数据验证和设置管理。
• Alembic: 用于 Python SQLAlchemy 数据库工具包的轻量级数据库迁移工具。
• 认证: 基于 JWT (JSON Web Tokens) 的身份验证。
• 测试: 支持 AsyncIO 的 Pytest 测试框架。
• 代码质量: 使用 Ruff 进行代码检查和格式化，使用 MyPy 进行静态类型检查。
• 项目结构: 模块化且可扩展的目录结构。

项目结构

python-best-practices/
├── alembic/                # 数据库迁移脚本
├── src/                    # 源代码
│   ├── api/                # API 接口和依赖
│   ├── core/               # 核心配置 (config, security, logging)
│   ├── crud/               # CRUD 操作
│   ├── db/                 # 数据库连接和模型基类
│   ├── models/             # SQLAlchemy 模型
│   ├── schemas/            # Pydantic 模式 (Schemas)
│   ├── tests/              # 测试用例
│   ├── initial_data.py     # 初始数据创建脚本
│   └── main.py             # 应用程序入口点
├── pyproject.toml          # 项目配置和依赖
├── alembic.ini             # Alembic 配置文件
└── README.md               # 项目文档

快速开始

1. 安装依赖: 您可以使用 pip 安装 pyproject.toml 中列出的依赖项（通常需要转换为 requirements.txt 或使用 poetry/pdm 等工具，但为简单起见，如果手动提取依赖，标准 pip 安装也可以工作）。 注意: 在真实环境中，推荐使用 Poetry 或 PDM。

2. 配置: 应用程序使用环境变量进行配置。请参阅 src/core/config.py 查看可用设置。 您可能需要将 SQLALCHEMY_DATABASE_URI 设置为有效的数据库 URL（例如 PostgreSQL）。对于测试，它默认使用本地 PostgreSQL 实例。

3. 运行迁移:

   alembic upgrade head

4. 创建初始数据:

   python src/initial_data.py

5. 运行应用程序:

   uvicorn src.main:app --reload

AI Agent 功能

本项目包含使用 LangChain 和 Google Gemini 模型的 AI Agent 功能。

配置

在 .env 文件或环境变量中设置您的 Google API Key：

GOOGLE_API_KEY=your_api_key_here

接口

• POST /api/v1/agent/chat: 与 Agent 聊天的接口，支持工具调用（例如：计算字符串长度、查询天气）。
• POST /api/v1/agent/multimodal: 与多模态模型 (Gemini Pro Vision) 交互的接口，支持图像处理。

测试

使用 pytest 运行测试:

pytest