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

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

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/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 基础与调试

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

2.3 文档 UI（Swagger UI / ReDoc）

2.4 路由与运行时行为

2.5 OpenAPI 输出定制

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

• 若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": "dp@x-force.example.com", }, license_info={"name": "Apache 2.0"}, default_response_class=ORJSONResponse, )

三、关键实例属性

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

3.1openapi_version

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

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

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

3.2webhooks

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

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

3.3state

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

3.4dependency_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.5openapi()：带缓存与路由版本检测的 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 注释）：

典型用法（取自源码 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的所有路由合并进应用，独有参数及其默认值：

示例（源码 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.1websocket(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.2frontend(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.1on_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.2middleware("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.3exception_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 路由、依赖覆盖、异常与中间件扩展）。

【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi