# fastapi框架

**Repository Path**: tdpc/fastapi-framework

## Basic Information

- **Project Name**: fastapi框架
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Owl - FastAPI Multi-Database RESTful API

多数据源（MySQL / Oracle / PostgreSQL）FastAPI 后端框架，集成阿里云百炼 LLM 对话能力。

## 项目结构

```
ai_owl/
├── main.py                          # 应用入口（FastAPI app、中间件、异常处理、生命周期）
├── requirements.txt                 # Python 依赖
├── alembic.ini                      # Alembic 数据库迁移配置
├── env/
│   ├── .env.development             # 开发环境配置（不入库）
│   └── .env.example                 # 配置模板
├── app/
│   ├── api/v1/
│   │   ├── router.py                # V1 路由聚合
│   │   └── endpoints/
│   │       └── user.py              # 用户 / Oracle / LLM 端点
│   ├── core/
│   │   ├── config.py                # Pydantic Settings 多层配置管理
│   │   ├── database.py              # 统一 Base + 多数据源引擎 + Session 路由
│   │   └── llm/client.py            # OpenAI 兼容 LLM 客户端
│   ├── dependencies.py              # 服务层依赖注入（工厂函数）
│   ├── models/                      # SQLAlchemy ORM 模型
│   │   └── __init__.py              # MODEL_BINDS 数据源路由映射
│   ├── schemas/                     # Pydantic 请求 / 响应 Schema
│   ├── services/                    # 业务逻辑层（CRUD）
│   └── utils/response.py            # 统一响应格式
└── alembic/                         # 数据库迁移脚本
    ├── env.py
    ├── script.py.mako
    └── versions/
```

## 快速开始

### 1. 环境准备

```bash
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\activate           # Windows

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

### 2. 配置

```bash
# 填写实际值
cp env/.env.example env/.env.development
```

```bash
# 启动指定环境
APP_ENV=staging uvicorn main:app --reload
```

### 3. 启动服务

```bash
python main.py
# 或
uvicorn main:app --reload --host 127.0.0.1 --port 8000
```

API 文档：http://127.0.0.1:8000/api/docs

## 架构设计

### 分层结构

```
请求 → Router → Endpoint → Service (via Depends) → Model → Database
                           ↑
                     dependencies.py
                    （工厂函数注入）
```

### 依赖注入

端点不直接接触 `db Session`，而是通过 `app/dependencies.py` 中的工厂函数注入 Service 实例：

```python
# app/dependencies.py
def get_user_service(db: Session = Depends(get_db)) -> UserService:
    return UserService(db)

# endpoint — 只需声明需要什么 service
@router.get("/{id}")
async def get_user(id: str, svc: UserService = Depends(get_user_service)):
    user = svc.get_by_simple_id(id)
```

依赖链 `get_db → get_user_service → 端点` 由 FastAPI 自动解析，Session 生命周期由 `get_db` 的 yield/finally 管理。测试时可通过 `app.dependency_overrides` 替换任意 service。

### 多数据源

所有模型统一继承 `Base`，不感知数据库类型（类似 Java JPA 的设计）。数据源路由通过 `app/models/__init__.py` 中的 `MODEL_BINDS` 集中配置：

`DatabaseManager` 启动时读取 `MODEL_BINDS`，自动将每个模型的表绑定到对应引擎，Session 查询自动路由。新增模型只需继承 `Base` 并在 `MODEL_BINDS` 添加一行映射。

### Schema 层

每个模型对应一组 Pydantic Schema（`app/schemas/`），分为 Brief（列表/摘要）、Detail（详情）、Create（创建请求）、Update（更新请求）。端点通过 `response_model` 声明响应格式，FastAPI 自动生成 Swagger 文档和输入校验。

## LLM 集成

内置 OpenAI 兼容客户端（`app/core/llm/client.py`），支持三种调用模式：

| 函数                         | 说明                        |
|-----------------------------|----------------------------|
| `chat()`                    | 一次性对话，返回完整文本       |
| `chat_stream()`             | 流式输出，逐块 yield 文本      |
| `chat_stream_with_thinking()`| 流式 + 深度思考，yield (content, reasoning) 元组 |

## 数据库迁移（Alembic）

```bash
# 生成迁移脚本（自动检测模型变更）
alembic revision --autogenerate -m "description"

# 执行迁移
alembic upgrade head

# 回退一步
alembic downgrade -1
```

所有模型共享同一个 `Base.metadata`，Alembic autogenerate 可自动检测全部表结构变更。

## API 端点

| 方法  | 路径                            | 说明                 | 数据源      |
|------|-------------------------------|---------------------|------------|
| GET  | `/health`                     | 健康检查              | -          |
| GET  | `/api/v1/user/mysql/{id}`     | 查询 MySQL 用户       | MySQL      |
| GET  | `/api/v1/user/postgresql/{id}`| 查询 PostgreSQL 用户   | PostgreSQL |
| GET  | `/api/v1/user/oracle/{sap_id}`| 查询 Oracle SAP 映射   | Oracle     |
| GET  | `/api/v1/user/llm/{question}` | LLM 问答              | -          |