FastAPI系列02：FastAPI程序结构与生命周期

---

在“FastAPI系列01：FastAPI快速入门”一节中，我们编写了第一个FastAPI程序，对FastAPI有了一个初步的认识，本节将在前面的基础上以一个宏观的视野分析一下FastAPI框架的结构、一个典型FastAPI程序的生命周期、以及作为用户我们如何组织自己的FastAPI程序。

1、FastAPI 核心结构

FastAPI 的核心结构围绕着几个主要的组件进行组织，包括 FastAPI、APIRouter、Request、Response、Depends 等。

FastAPI

APIRouter

Middleware

Depends

Exception

Route

Request

Response

Pydantic

1）FastAPI (FastAPI应用)

FastAPI 类继承自 Starlette，用于启动 HTTP 服务和路由管理。负责应用生命周期事件管理、异常处理和中间件集成。

2）APIRouter (路由管理器)

提供路由管理的功能。支持分模块设计，将路由拆分为多个独立的模块。使用 include_router() 将路由器整合到主应用。

3）Route(具体路由对象)

每个 API 路由的具体表示。通过路由映射对应到视图函数或方法。

4）Request(请求对象)

由 Starlette 提供，封装 HTTP 请求数据。包含请求的 URL、Headers、Query Params、Body 等信息。

5）Response(响应对象)

用于封装和返回 HTTP 响应。支持多种格式，包括 JSON、HTML、文件等。

6）Pydantic(数据验证和解析)

FastAPI 使用 Pydantic 进行数据校验和解析。提供强类型验证、数据转换和错误提示。

7）Middleware(中间件处理器)

在请求和响应处理之间执行的函数。通常用于日志记录、请求验证、跨域处理等。

8）Depends(依赖注入处理器)

提供依赖注入的功能。用于处理认证、权限校验、数据库连接等场景。

9）Exception(异常处理器)

提供自定义异常处理功能。使用 HTTPException 等类抛出异常并返回友好的错误响应。

2、FastAPI 应用程序生命周期

1）FastAPI类

FastAPI 类是核心的应用程序类，用于创建 Web 应用。它提供了多种方法和属性，用于管理路由、依赖项、生命周期事件、异常处理等。

from fastapi import FastAPI

app = FastAPI(
	title="My API",
    description="这是一个示例 API",
    version="1.0.0",
    contact={
        "name": "API Support",
        "email": "[email protected]",
    },
    license_info={
        "name": "MIT",
        "url": "https://opensource.org/licenses/MIT",
    }
)

@app.get("/")
async def read_root():
    return {"message": "Hello, FastAPI!"}

在初始化 FastAPI 时，可以通过参数对应用程序进行配置，详细参数有：

参数名	类型	默认值	说明
title	str	“FastAPI”	API 文档的标题
description	str	“”	API 的描述信息
version	str	“0.1.0”	API 的版本号
terms_of_service	str	None	服务条款链接
contact	dict	None	联系信息，如邮箱、网址等
license_info	dict	None	许可证信息，如名称和链接
docs_url	str or None	“/docs”	Swagger UI 的路径，设置为 None 可禁用
redoc_url	str or None	“/redoc”	ReDoc 文档的路径，设置为 None 可禁用
openapi_url	str or None	“/openapi.json”	OpenAPI 文档的路径，设置为 None 可禁用
dependencies	List[Depends]	None	全局依赖项
default_response_class	Type[Response]	JSONResponse	设置默认的响应类型
servers	List[dict]	None	自定义服务器信息

2）FastAPI应用生命周期事件

在 FastAPI 中，应用程序的生命周期包括应用启动和关闭的过程。FastAPI提供了生命周期事件的钩子，通过 @app.on_event() 装饰器来监听这些事件。在这期间，可以执行一些特定的任务，例如初始化数据库、加载模型、清理资源等。

Startup（启动），当应用启动时触发，通常用于执行一些初始化任务，例如：
• 数据库连接
• 加载模型或配置
• 启动定时任务
• 初始化缓存等

Shutdown（关闭），当应用关闭时触发，通常用于执行清理任务，例如：
• 关闭数据库连接
• 释放资源
• 保存日志等

下面是一个简单的示例，演示如何在 FastAPI 中使用生命周期事件：

from fastapi import FastAPI

app = FastAPI()

# 模拟数据库连接
async def connect_to_db():
    print("数据库连接已建立")

async def disconnect_from_db():
    print("数据库连接已关闭")

# 启动事件
@app.on_event("startup")
async def startup_event():
    print("应用启动中...")
    await connect_to_db()

# 关闭事件
@app.on_event("shutdown")
async def shutdown_event():
    print("应用关闭中...")
    await disconnect_from_db()

@app.get("/")
async def read_root():
    return {"message": "Hello, FastAPI!"}

3）FastAPI核心方法

FastAPI 提供了一组核心方法，用于管理路由、依赖项、中间件等。
路由相关方法

方法名	说明
app.get()	定义 GET 请求的路由
app.post()	定义 POST 请求的路由
app.put()	定义 PUT 请求的路由
app.patch()	定义 PATCH 请求的路由
app.delete()	定义 DELETE 请求的路由
app.options()	定义 OPTIONS 请求的路由
app.head()	定义 HEAD 请求的路由
app.include_router()	导入路由模块
app.mount()	挂载静态文件或子应用

请求和响应方法

方法	说明
app.request_class	自定义请求类
app.response_class	自定义响应类

中间件方法

方法名	说明
app.middleware()	注册中间件，拦截请求和响应

依赖项方法

方法名	说明
Depends()	声明依赖项
app.router.dependencies	添加全局依赖项
app.dependency_overrides	覆盖依赖项（通常用于测试）

异常处理方法

方法名	说明
app.exception_handler()	注册异常处理器

文档和 OpenAPI 方法

方法	说明
app.openapi()	获取 OpenAPI 模型
app.openapi_schema()	自定义 OpenAPI Schema
app.docs_url	设置 Swagger UI 文档路径
app.redoc_url	设置 ReDoc 文档路径

3、FastAPI 请求-响应生命周期

在 FastAPI 中，请求-响应生命周期是指客户端从发送请求到接收响应的整个过程。

FastAPI APP

Post-Processing

Dependency-Injection

Return Response

Exception Handling

Error Response

Router

Middleware

Response

Dependencies

Business-Logic

Exception

Database / External Services

Client

ASGI-Server

一个完整的生命周期通常包含以下阶段：

1）客户端发送请求

• 客户端（如浏览器、Postman 或 Curl）向 FastAPI 应用发送 HTTP 请求。

2）ASGI 服务器接收请求

• 例如，Uvicorn 接收 HTTP 请求并将其转换为 ASGI 事件。

3）中间件处理（Middleware）

• FastAPI 执行在应用层中定义的中间件，它们可用于日志记录、请求验证、性能监控等。

4）路由匹配与请求解析

• FastAPI 根据请求的路径和方法查找匹配的路由。
• 请求数据（Query参数、Body数据、Headers等）会被解析。

5）依赖项注入（Dependency Injection）

• 如果路由处理函数使用依赖项（Depends()），FastAPI 会执行这些依赖项并将结果注入到视图函数中。

6）业务逻辑处理

• 调用对应的视图函数处理业务逻辑。
• 可以包含数据库查询、数据处理、第三方服务调用等。

7）生成响应

• 视图函数返回响应对象，FastAPI 将其转换为 HTTP 响应。
• 支持 JSON、HTML、文件流等多种响应类型。

8）中间件后处理（Middleware）

• 还可以有一些后处理逻辑，例如日志记录、数据清理等。

9）ASGI 服务器发送响应

• ASGI 服务器将 HTTP 响应发送回客户端。

4、FastAPI 项目结构

从前面的内容我们了解了FastAPI 的核心结构，围绕这些结构我们都可以进行自定义开发以实现项目需求。因此，一个典型的 FastAPI 项目大体上可以有如下结构：

my_fastapi_project/
├── app/ # API层
│   ├── __init__.py
│   ├── main.py # 程序入口
│   ├── routers/ # 自定义路由文件
│   │   ├── items.py
│   │   ├── users.py
│   ├── responses.py # 自定义response
│   ├── dependencies.py # 自定义依赖项
│   ├── middlewares.py # 自定义中间件
│   ├── exceptions.py # 自定义错误处理
│   ├── configs/ # 应用配置文件
│   ├── static/ # 静态文件
│   └── templates/ # 模版文件
├── business_logic_modules/ # 业务逻辑层
│   ├── module_a/
│   ├── module_b/
├── tests/
│   ├── test_main.py
└── requirements.txt