FastAPI 类完全参考指南：构造参数、核心属性与全部方法逐项解析

本篇基于 FastAPI 官方参考文档（docs/en/docs/reference/fastapi.md）与仓库源码（fastapi/applications.py），对 FastAPI 类做逐项深度拆解：覆盖全部初始化参数及默认值、关键实例属性（openapi_version、webhooks、state、dependency_overrides）、OpenAPI 生成缓存机制、8 个 HTTP 路径操作装饰器、include_router、websocket、frontend、on_event、middleware 与 exception_handler 等全部成员。读完后你可以把这篇当作"API 应用配置速查手册"，并能结合源码行号定位每个行为的实际实现位置。

一、FastAPI 类是什么，如何导入

FastAPI 是创建 API 应用的主入口类，继承自 Starlette 的 Starlette 应用类（见 应用入口）：

class FastAPI(Starlette):
    """
    `FastAPI` app class, the main entrypoint to use FastAPI.
    """

它比 Starlette 多提供了三类能力：

1. 基于类型注解的自动请求校验与响应序列化（通过 Pydantic）；
2. 自动生成交互式 API 文档（OpenAPI 3.1.0，默认在 /docs、/redoc、/openapi.json）；
3. 依赖注入系统（Depends / dependency_overrides）。

官方文档给出的标准导入方式是从 fastapi 包顶层直接导入：

from fastapi import FastAPI

app = FastAPI()

当前仓库中的版本号为 0.141.1（见 版本定义）。

二、全部初始化参数与默认值总表

FastAPI.__init__ 采用纯关键字参数（全部在 * 之后），参数众多但分组清晰。下表汇总了源码 构造器签名 中的全部参数、类型与默认值：

2.1 基础与调试

参数	类型	默认值	说明
debug	bool	False	是否在服务器错误时返回调试 traceback
routes	list[BaseRoute] | None	None	直接提供路由列表；继承自 Starlette 的兼容参数，官方标注不建议在 FastAPI 中使用，应改用 app.get() 等路径操作装饰器（源码中已标记 deprecated）

2.2 OpenAPI 元数据（写入 /openapi.json，在 /docs 可见）

参数	类型	默认值	说明
title	str	"FastAPI"	API 标题；只要 openapi_url 非空，源码会 assert self.title，即必须提供非空标题
summary	str | None	None	API 的简短摘要
description	str	""	API 描述，支持 CommonMark Markdown 语法，在 Swagger UI 中渲染
version	str	"0.1.0"	你的应用的版本号，不是 OpenAPI 规范版本，也不是 FastAPI 框架版本
openapi_url	str | None	"/openapi.json"	OpenAPI 文档的提供地址；设为 None 时不公开提供文档，且 /docs、/redoc 自动禁用
openapi_tags	list[dict] | None	None	标签元数据列表，每项含 name、description（可选 Markdown）、externalDocs（含 description 与 url）；列表顺序即 Swagger UI 中分组展示顺序
servers	list[dict] | None	None	目标服务器连接信息，每项含 url（支持 {变量} 模板）、description、variables；未提供时若存在 root_path 则自动补一个指向 root_path 的 server，否则省略该字段
terms_of_service	str | None	None	服务条款 URL
contact	dict | None	None	联系人信息，可含 name、url、email 字段
license_info	dict | None	None	许可证信息，可含 name（设置后必填）、identifier（SPDX 表达式，与 url 互斥，OpenAPI 3.1.0 起）、url
openapi_external_docs	dict | None	None	外部文档链接，必须含 description 和 url（合法 URL 格式）
openapi_prefix	str	""	已弃用，改用更贴近 ASGI 标准的 root_path；传入非空值时源码会打印弃用警告（见 警告逻辑）
root_path	str	""	由代理处理、应用不可见但外部客户端可见的路径前缀，影响 Swagger UI 等行为
root_path_in_servers	bool	True	是否用 root_path 自动生成 OpenAPI servers 中的 URL；设为 False 可禁用

2.3 文档 UI（Swagger UI / ReDoc）

参数	类型	默认值	说明
docs_url	str | None	"/docs"	Swagger UI 交互文档路径；None 禁用；openapi_url 为 None 时自动禁用
redoc_url	str | None	"/redoc"	ReDoc 备用文档路径；规则同上
swagger_ui_oauth2_redirect_url	str | None	"/docs/oauth2-redirect"	Swagger UI 的 OAuth2 回调端点，仅在使用 "Authorize" 按钮时相关
swagger_ui_init_oauth	dict | None	None	Swagger UI 的 OAuth2 初始化配置字典
swagger_ui_parameters	dict | None	None	传给 Swagger UI 的额外初始化参数，可定制 UI 行为

2.4 路由与运行时行为

参数	类型	默认值	说明
dependencies	Sequence[Depends] | None	None	全局依赖列表，会应用到每一个路径操作，包括子路由中的操作
default_response_class	type[Response]	JSONResponse	默认响应类，如可改为 ORJSONResponse
redirect_slashes	bool	True	是否对尾斜杠不一致的 URL 做 307 重定向，如 /items → /items/
middleware	Sequence[Middleware] | None	None	创建应用时加入的中间件列表；FastAPI 中更常用 app.add_middleware()
exception_handlers	dict | None	None	异常处理器字典；FastAPI 中更常用 @app.exception_handler() 装饰器
on_startup	Sequence[Callable] | None	None	启动事件处理函数列表；官方建议改用 lifespan
on_shutdown	Sequence[Callable] | None	None	关闭事件处理函数列表；官方建议改用 lifespan
lifespan	Lifespan[AppType] | None	None	以单个上下文管理器替代 startup/shutdown 两组函数
strict_content_type	bool	True	严格校验请求 Content-Type：为 True 时，不带该头的带 body 请求不会被按 JSON 解析，可防御绕过 CORS 预检的 CSRF 类攻击；设为 False 则兼容不发 Content-Type 的旧客户端
**extra	Any	—	透传给 Starlette 的额外关键字参数，仅存于应用实例，FastAPI 本身不使用

2.5 OpenAPI 输出定制

参数	类型	默认值	说明
responses	dict[int | str, dict] | None	None	附加在 OpenAPI 中的额外响应声明
callbacks	list[BaseRoute] | None	None	应用到所有路径操作的 OpenAPI 回调（仅文档用途）
webhooks	APIRouter | None	None	OpenAPI 3.1 webhooks 路由（自 OpenAPI 3.1.0 / FastAPI 0.99.0 起），与 callbacks 不同，不依赖具体路径操作
deprecated	bool | None	None	将全部路径操作标记为弃用
include_in_schema	bool	True	是否将所有路径操作写入 OpenAPI
generate_unique_id_function	Callable[[APIRoute], str]	generate_unique_id	定制 OpenAPI 操作唯一 ID 的生成函数，对自动生成客户端/SDK 尤其有用
separate_input_output_schemas	bool	True	输入输出结果不同时生成独立 schema。例如模型 Item.tags: list[str] = [] 作为请求体时 tags 非必填，作为响应体时恒存在（有默认值），开启后分别生成两套 schema，提升生成客户端的精确度

构造时的关键行为（初始化主体）：

• 若 openapi_url 非空，强制 title 与 version 非空（assert 校验）；
• 内部创建 self.router = APIRouter(...)，并把 dependencies、callbacks、responses、deprecated、include_in_schema、strict_content_type 等参数一并传给路由，这就是"全局参数"生效的机制；
• exception_handlers 默认注册三个内建处理器：HTTPException、RequestValidationError、WebSocketRequestValidationError；
• 最后调用 self.setup()，注册 /openapi.json、/docs、/redoc、OAuth2 重定向四条内置路由（include_in_schema=False）。

一个综合示例（参数均来自源码 Doc 中的官方示例）：

from fastapi import FastAPI
from fastapi.responses import ORJSONResponse

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://fastapi.tiangolo.com/",
        },
    },
]

app = FastAPI(
    title="ChimichangApp",
    summary="Deadpond's favorite app. Nuff said.",
    description="ChimichangApp API helps you do awesome stuff. 🚀",
    version="0.0.1",
    openapi_tags=tags_metadata,
    contact={
        "name": "Deadpoolio the Amazing",
        "email": "[e-mail]",
    },
    license_info={"name": "Apache 2.0"},
    default_response_class=ORJSONResponse,
)

三、关键实例属性

参考文档列出的成员中，以下四个属性最常用，源码均位于 属性赋值区：

3.1 openapi_version

OpenAPI 版本字符串，默认 "3.1.0"，只能作为属性修改，不是构造参数。用途是"骗过"不认识 3.1.0 的旧工具：

app = FastAPI()
app.openapi_version = "3.0.2"  # 需避免使用 3.1.0 才引入的特性

源码注释明确提醒：这是 hack 手段，因为 FastAPI 实际生成的 schema 并不会降级。

3.2 webhooks

APIRouter 实例（未提供时自动创建），其中定义的路径操作仅用于 OpenAPI 文档中的 webhooks 部分，不产生真实可访问的路由：

app = FastAPI()

@app.webhooks.post("/payments/")
async def payment_webhook():
    ...

3.3 state

Starlette 的 State 对象，整个应用生命周期内是同一个对象、不随请求变化。官方说明：多数场景应使用 FastAPI 依赖而非 state，它是直接继承自 Starlette 的用法。

3.4 dependency_overrides

dict[原始依赖, 替换依赖]，专为测试设计：把昂贵的依赖（数据库会话、HTTP 客户端等）替换为测试版本。典型用法：

from fastapi.testclient import TestClient
from main import app, get_db

def override_get_db():
    return TestingSession()

app.dependency_overrides[get_db] = override_get_db

测试体系中的印证可参考 依赖测试教程代码 与教程文档 依赖测试。

3.5 openapi()：带缓存与路由版本检测的 schema 生成

openapi 方法 的调用链值得注意：

1. 先取 self.router._get_routes_version() 作为路由"版本号"；
2. 仅当 openapi_schema 为空，或路由版本发生变化时，才调用 get_openapi(...)（来自 fastapi/openapi/utils.py）重新生成；
3. 生成时传入 title、version、openapi_version、summary、description、terms_of_service、contact、license_info、routes、webhooks.routes、tags、servers、separate_input_output_schemas、external_docs——与第二节的元数据参数一一对应；
4. 结果缓存在 self.openapi_schema，后续调用零成本返回。

/openapi.json 路由本身还有一个细节：setup 中的 openapi 函数 会在响应前检查请求的 root_path，若 root_path_in_servers 为真且 servers 中尚无该 URL，就把它前置插入 servers 列表，保证代理部署下 Swagger UI 请求地址正确。

测试侧的证据：test_openapi_schema 断言响应 "openapi": "3.1.0"、info.title == "FastAPI"，并快照校验了 externalDocs 等字段。

四、路径操作方法：get / put / post / delete / options / head / patch / trace

FastAPI 提供了与 HTTP 动词一一对应的 8 个装饰器方法（如 get 方法），它们本质都是薄封装：签名完全相同，仅转发到 self.router.<method>(...) 并带上全部参数。

各方法共享的参数集（每个方法内都有完整 Doc 注释）：

参数	默认值	说明
path	必填	路径，如 /items/{item_id}
response_model	None	响应类型。用途四重：文档（JSON Schema）、序列化（任意对象转 JSON）、过滤（仅返回模型定义的字段，如剔除 password）、校验（返回数据不合法时 FastAPI 报 500，因为这属于 API 开发者违约）
status_code	None	默认响应状态码；直接返回 Response 可覆盖
tags	None	操作标签，写入 OpenAPI
dependencies	None	该操作的 Depends() 列表
summary / description	None	标题与描述；description 未提供时自动从函数 docstring 提取，支持 Markdown
response_description	"Successful Response"	默认响应的描述
responses	None	额外响应声明
deprecated	None	标记弃用
operation_id	None	自定义操作 ID（须全 API 唯一）；可用 generate_unique_id_function 定制生成规则
response_model_include / response_model_exclude	None	传给 Pydantic 的字段级 include/exclude
response_model_by_alias	True	是否按 alias 序列化
response_model_exclude_unset	False	排除"未显式设置"的字段（保留显式设置为默认值的字段）
response_model_exclude_defaults	False	排除"值等于默认值"的字段（无论是否显式设置）
response_model_exclude_none	False	排除 None 字段；比前两个更简单粗暴，官方建议优先用前两者
include_in_schema	True	是否写入 OpenAPI
response_class	JSONResponse	该操作的响应类；直接返回 Response 时不生效
name	None	内部使用的操作名
callbacks	None	该操作的 OpenAPI 回调（仅文档）
openapi_extra	None	注入该操作 OpenAPI schema 的额外元数据
generate_unique_id_function	generate_unique_id	覆盖全局唯一 ID 生成函数

典型用法（取自源码 docstring）：

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]

除装饰器形式外，还有两个等价的命令式方法：

• api_route(path, *, methods=[...], ...)：装饰器形式，显式指定方法列表；
• add_api_route(path, endpoint, ...)：命令式注册，签名见 add_api_route。

测试证据：tests/test_application.py 中 test_get_path 用参数化用例验证了装饰器路由、非装饰器路由（add_api_route 风格）与 404 行为，test_openapi_schema 则快照校验了两种注册方式生成的 operationId（如 non_operation_api_route_get）。

五、include_router：大应用组装的核心

include_router 把 APIRouter 的所有路由合并进应用，独有参数及其默认值：

参数	默认值	说明
router	必填	要包含的 APIRouter
prefix	""	路径前缀，如 prefix="/users"
tags	None	应用于该路由全部操作的标签
dependencies	None	应用于该路由全部操作的依赖
responses	None	该路由级别的额外 OpenAPI 响应
deprecated	None	将该路由全部操作标记弃用
include_in_schema	True	是否将该路由全部操作写入 OpenAPI
default_response_class	JSONResponse	该路由的默认响应类
callbacks	None	该路由级别的 OpenAPI 回调
generate_unique_id_function	generate_unique_id	该路由级别的唯一 ID 生成函数

示例（源码 Doc 中的官方片段）：

from fastapi import Depends, FastAPI
from .internal import admin

app = FastAPI()

app.include_router(
    admin.router,
    dependencies=[Depends(get_token_header)],
)

实现上它只是委托给 self.router.include_router(...)，因此 APIRouter 自身也支持同样的参数，可多级嵌套。相关教程示例可看 docs_src/bigger_applications/ 目录与文档 Bigger Applications。

六、websocket 与 frontend

6.1 websocket(path, name=None, *, dependencies=None)

websocket 装饰器 装饰 WebSocket 处理函数，内部调用 add_api_websocket_route（其仅支持 name 与 dependencies 两个额外参数）。示例：

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message text was: {data}")

另有一个继承自 Starlette 的低层 websocket_route（源码），仅做路由注册，不带 FastAPI 的依赖注入能力。

6.2 frontend(path, *, directory, fallback="auto", check_dir="auto")

frontend 方法 用于把前端静态构建产物（如 dist/）作为低优先级路由提供服务：FastAPI 路径操作优先匹配，只有没有普通路由命中时才回落到前端文件——因此 API 与 SPA 可共存于同一应用：

app = FastAPI()
app.frontend("/", directory="dist")

参数要点：

• directory：静态构建产物所在目录；
• fallback：缺失路径的回退文件，取值为 "auto" / "index.html" / "404.html" / None；
• check_dir：创建应用时是否检查目录存在；"auto" 时若环境变量 FASTAPI_ENV 为 "development"（fastapi dev 命令会自动设置）则跳过检查并给出警告，否则严格检查。

七、on_event（已弃用）、middleware 与 exception_handler

7.1 on_event：已弃用，改用 lifespan

on_event("startup") / on_event("shutdown") 已标记 deprecated（源码），官方推荐用 lifespan 上下文管理器参数：

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app):
    # 启动逻辑（替代 on_event("startup")）
    yield
    # 关闭逻辑（替代 on_event("shutdown")）

app = FastAPI(lifespan=lifespan)

7.2 middleware("http") 装饰器

middleware 方法 当前仅支持 http 类型，装饰器内部等价于 self.add_middleware(BaseHTTPMiddleware, dispatch=func)。官方 docstring 示例：

import time
from typing import Awaitable, Callable

from fastapi import FastAPI, Request, Response

app = FastAPI()

@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

注意中间件栈的组装细节在 build_middleware_stack：FastAPI 覆写了 Starlette 的同名方法，在外层 ServerErrorMiddleware 与用户中间件之内、ExceptionMiddleware 之下额外插入了一层 AsyncExitStackMiddleware，用于在保持 contextvars 上下文一致的前提下正确关闭文件等资源。

7.3 exception_handler 装饰器

exception_handler 方法 接收异常类或状态码，装饰器内部调用 self.add_exception_handler(...)。docstring 示例（自定义异常 → 418 响应）：

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something."},
    )

八、源码结构小结与延伸阅读

• 类实现全部集中在 fastapi/applications.py：构造器（L58-L1018）、中间件栈（L1020-L1068）、openapi()（L1070-L1103）、setup() 内置路由（L1105-L1158）、frontend（L1222）、include_router（L1441）、HTTP 动词方法（L1646 起）、on_event/middleware/exception_handler（L4654-L4774）。
• OpenAPI 生成的底层逻辑在 fastapi/openapi/utils.py，文档 UI 的 HTML 模板在 fastapi/openapi/docs.py。
• 内置文档端点的行为由 tests/test_application.py 固化：/docs 返回含 swagger-ui-dist 的 HTML、/redoc 返回 ReDoc 页面、/docs/oauth2-redirect 返回 OAuth2 回调页、/openapi.json 的完整 schema 以 inline_snapshot 快照断言。
• 与本文各主题对应的官方教程（英文文档，本仓库内可直接查看）：元数据与文档 URL、中间件、错误处理、更大型应用、依赖测试。

掌握上述参数与方法的分工后，一个常见的心智模型是：构造参数决定"应用是什么"（元数据、文档开关、全局依赖、响应类），装饰器方法决定"应用提供什么"（HTTP/WebSocket 端点、路由组装），属性与命令式方法决定"应用如何被观察和替换"（OpenAPI 版本覆盖、webhooks 路由、依赖覆盖、异常与中间件扩展）。