FastAPI自学教程（63） - 子应用挂载机制

1.基础用法

from fastapi import FastAPI

# 创建主应用
app = FastAPI()

# 创建子应用
subapi = FastAPI()

# 主应用路由
@app.get("/")
def read_main():
    return {"message": "主应用数据"}

# 子应用路由
@subapi.get("/sub")
def read_sub():
    return {"message": "子应用数据"}

# 挂载子应用到主应用
app.mount("/subapi", subapi)

• 通过app.mount()方法将子应用挂载到指定路径（如/subapi）
• 每个子应用拥有独立的路由系统和OpenAPI文档，访问路径分别为：
  • 主应用文档：/docs
  • 子应用文档：/subapi/docs

流程图：

graph TD
    A[客户端请求] --> B{路径匹配}
    B -->|匹配主应用路由| C[主应用处理]
    B -->|匹配子应用前缀| D[子应用处理]
    C & D --> E[返回响应]

2.核心特性

2.1 独立配置

• 每个子应用可独立配置中间件、异常处理器和生命周期
• 状态管理隔离：主应用与子应用的app.state相互独立

2.2 文档系统

# 子应用自定义文档描述
subapi = FastAPI(title="用户模块", description="用户相关操作API")

• 支持自定义子应用的OpenAPI元数据
• 文档URL自动继承挂载路径前缀（如/subapi/openapi.json）

2.3 技术实现

• 底层通过ASGI的root_path机制处理路径前缀
• 支持多层嵌套挂载（子应用可再挂载子应用）

3.应用场景

1. 模块化开发
   • 用户模块、订单模块等独立开发后挂载到主应用
2. 版本管理
   • 通过/v1和/v2路径区分API版本
3. 服务整合
   • 集成第三方服务（如挂载Flask应用）

4.与APIRouter对比

特性	APIRouter	子应用
独立性	共享主应用配置	完全独立配置
文档系统	合并到主文档	独立文档系统
适用场景	单应用内路由分组	多服务集成/模块化部署
中间件管理	共享主应用中间件	可配置独立中间件
性能影响	低	略高（需处理路径分发）

测试命令示例：

# 启动主应用
uvicorn main:app --reload --port 8000

# 访问子应用文档
curl http://localhost:8000/subapi/docs