Python Web框架-FastAPI教程-app.mount()详细说明-马育民老师

# 介绍

`app.mount()` 是 FastAPI 用于**挂载独立 ASGI 应用**的方法，可将另一个完整应用（FastAPI/Starlette/StaticFiles）绑定到主应用的指定路径下，该路径下的所有请求由被挂载应用独立处理。

### 语法

```python
def mount(
    self,
    path: str,
    app: ASGIApp,
    name: Optional[str] = None
) -> None:
```
- **path**：挂载路径（如 `/api/v2`），主应用中该前缀请求转发给子应用。
- **app**：被挂载的 ASGI 应用实例（FastAPI、Starlette、StaticFiles 等）。
- **name**：可选，挂载点标识名，用于内部路由管理。

---

# 与 APIRouter 区别

|特性|`app.mount()`|`APIRouter`（`app.include_router`）|
|---|---|---|
|**应用独立性**|完全独立：**独立生命周期、中间件、文档、OpenAPI**|共享主应用：**共用生命周期、中间件、文档、OpenAPI**|
|**路由隔离**|挂载路径下**完全接管**，主应用不干涉|主应用与路由**合并**，共享命名空间|
|**适用场景**|多版本API、微服务聚合、静态文件服务|模块化路由、单应用内功能拆分|
|**文档地址**|子应用独立文档：`/mount-path/docs`|统一文档：`/docs`|

---

# 使用场景与代码示例

### 场景1：挂载静态文件

FastAPI 内置 [StaticFiles](https://www.malaoshi.top/show_1GW3MyuMpxH6.html "StaticFiles") 用于托管静态资源（HTML/CSS/JS/图片）。

```python
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# 挂载静态目录到 /static
app.mount(
    "/static",
    StaticFiles(directory="static"),  # 本地 static 目录
    name="static"
)
```

访问：`http://localhost:8000/static/logo.png` → 读取 `static/logo.png`

### 场景2：挂载 FastAPI 子应用（多版本API）

```python
from fastapi import FastAPI

# 主应用
app = FastAPI(title="主应用")

# 子应用 v1
app_v1 = FastAPI(title="API v1")
@app_v1.get("/users")
def get_users_v1():
    return {"version": "v1", "users": ["Alice"]}

# 子应用 v2
app_v2 = FastAPI(title="API v2")
@app_v2.get("/users")
def get_users_v2():
    return {"version": "v2", "users": ["Bob", "Charlie"]}

# 挂载子应用
app.mount("/api/v1", app_v1)
app.mount("/api/v2", app_v2)

# 主应用路由
@app.get("/")
def root():
    return {"message": "主应用根路径"}
```

- 请求示例：
  - `GET /` → 主应用响应
  - `GET /api/v1/users` → 子应用 v1 响应
  - `GET /api/v2/users` → 子应用 v2 响应
- 独立文档：
  - 主应用：`http://localhost:8000/docs`
  - v1 文档：`http://localhost:8000/api/v1/docs`
  - v2 文档：`http://localhost:8000/api/v2/docs`

# 路径匹配规则

- **前缀匹配**：`/api/v1` 挂载后，`/api/v1`、`/api/v1/xxx` 均由子应用处理。
- **无重叠优先级**：主应用路由与挂载路径冲突时，**挂载路径优先**。

# 生命周期与中间件隔离
- **独立 Lifespan**：子应用可定义独立 `lifespan`，与主应用生命周期互不干扰。
- **中间件隔离**：主应用中间件**不作用于子应用**，子应用需单独注册中间件。

# OpenAPI 与文档
- 每个挂载的 FastAPI 子应用**拥有独立 OpenAPI schema** 和文档页面。
- 子应用文档路径：`/mount-path/docs`，Redoc：`/mount-path/redoc`。

# root_path 自动处理
FastAPI 自动通过 ASGI `root_path` 传递挂载路径给子应用，子应用内部路由无需感知挂载前缀。
例如：子应用 `/users` → 实际访问 `/api/v1/users`。

---

# 常见问题

1. ❌ **混淆 `mount` 与 `include_router`**：`mount` 是**应用级挂载**，`include_router` 是**路由级合并**，不可混用。
2. ❌ **共享状态风险**：主应用与子应用 `state` 隔离，需通过**外部存储（Redis/数据库）**共享数据。
3. ⚠️ **挂载路径不可为空**：`path` 必须以 `/` 开头，不可为 `/`（主应用根路径）。
4. ⚠️ **子应用必须是 ASGI 应用**：仅支持 ASGI 协议应用，不支持 WSGI 应用（如 Flask 需适配）。

---

# 总结
`app.mount()` 是 FastAPI 实现**应用级模块化**的核心工具，核心价值在于**完全隔离的独立应用挂载**，适合多版本API、静态文件托管、第三方ASGI应用集成等场景。与 `APIRouter` 配合使用，可兼顾**模块化拆分**与**应用级隔离**，构建清晰的大型FastAPI项目架构。

原文出处：http://www.malaoshi.top/show_1GW3Mz7HdtD6.html