尧图网页设计 
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 多提供了三类能力基于类型注解的自动请求校验与响应序列化通过 Pydantic自动生成交互式 API 文档OpenAPI 3.1.0默认在/docs、/redoc、/openapi.json依赖注入系统Depends/dependency_overrides。官方文档给出的标准导入方式是从fastapi包顶层直接导入from fastapi import FastAPI app FastAPI()当前仓库中的版本号为 0.141.1见 版本定义。二、全部初始化参数与默认值总表FastAPI.__init__采用纯关键字参数全部在*之后参数众多但分组清晰。下表汇总了源码 构造器签名 中的全部参数、类型与默认值2.1 基础与调试参数类型默认值说明debugboolFalse是否在服务器错误时返回调试 tracebackrouteslist[BaseRoute] \| NoneNone直接提供路由列表继承自 Starlette 的兼容参数官方标注不建议在 FastAPI 中使用应改用app.get()等路径操作装饰器源码中已标记deprecated2.2 OpenAPI 元数据写入/openapi.json在/docs可见参数类型默认值说明titlestrFastAPIAPI 标题只要openapi_url非空源码会assert self.title即必须提供非空标题summarystr \| NoneNoneAPI 的简短摘要descriptionstrAPI 描述支持 CommonMark Markdown 语法在 Swagger UI 中渲染versionstr0.1.0你的应用的版本号不是 OpenAPI 规范版本也不是 FastAPI 框架版本openapi_urlstr \| None/openapi.jsonOpenAPI 文档的提供地址设为None时不公开提供文档且/docs、/redoc自动禁用openapi_tagslist[dict] \| NoneNone标签元数据列表每项含name、description可选 Markdown、externalDocs含description与url列表顺序即 Swagger UI 中分组展示顺序serverslist[dict] \| NoneNone目标服务器连接信息每项含url支持{变量}模板、description、variables未提供时若存在root_path则自动补一个指向root_path的 server否则省略该字段terms_of_servicestr \| NoneNone服务条款 URLcontactdict \| NoneNone联系人信息可含name、url、email字段license_infodict \| NoneNone许可证信息可含name设置后必填、identifierSPDX 表达式与url互斥OpenAPI 3.1.0 起、urlopenapi_external_docsdict \| NoneNone外部文档链接必须含description和url合法 URL 格式openapi_prefixstr已弃用改用更贴近 ASGI 标准的root_path传入非空值时源码会打印弃用警告见 警告逻辑root_pathstr由代理处理、应用不可见但外部客户端可见的路径前缀影响 Swagger UI 等行为root_path_in_serversboolTrue是否用root_path自动生成 OpenAPIservers中的 URL设为False可禁用2.3 文档 UISwagger UI / ReDoc参数类型默认值说明docs_urlstr \| None/docsSwagger UI 交互文档路径None禁用openapi_url为None时自动禁用redoc_urlstr \| None/redocReDoc 备用文档路径规则同上swagger_ui_oauth2_redirect_urlstr \| None/docs/oauth2-redirectSwagger UI 的 OAuth2 回调端点仅在使用 Authorize 按钮时相关swagger_ui_init_oauthdict \| NoneNoneSwagger UI 的 OAuth2 初始化配置字典swagger_ui_parametersdict \| NoneNone传给 Swagger UI 的额外初始化参数可定制 UI 行为2.4 路由与运行时行为参数类型默认值说明dependenciesSequence[Depends] \| NoneNone全局依赖列表会应用到每一个路径操作包括子路由中的操作default_response_classtype[Response]JSONResponse默认响应类如可改为ORJSONResponseredirect_slashesboolTrue是否对尾斜杠不一致的 URL 做 307 重定向如/items→/items/middlewareSequence[Middleware] \| NoneNone创建应用时加入的中间件列表FastAPI 中更常用app.add_middleware()exception_handlersdict \| NoneNone异常处理器字典FastAPI 中更常用app.exception_handler()装饰器on_startupSequence[Callable] \| NoneNone启动事件处理函数列表官方建议改用lifespanon_shutdownSequence[Callable] \| NoneNone关闭事件处理函数列表官方建议改用lifespanlifespanLifespan[AppType] \| NoneNone以单个上下文管理器替代 startup/shutdown 两组函数strict_content_typeboolTrue严格校验请求Content-Type为True时不带该头的带 body 请求不会被按 JSON 解析可防御绕过 CORS 预检的 CSRF 类攻击设为False则兼容不发Content-Type的旧客户端**extraAny—透传给 Starlette 的额外关键字参数仅存于应用实例FastAPI 本身不使用2.5 OpenAPI 输出定制参数类型默认值说明responsesdict[int \| str, dict] \| NoneNone附加在 OpenAPI 中的额外响应声明callbackslist[BaseRoute] \| NoneNone应用到所有路径操作的 OpenAPI 回调仅文档用途webhooksAPIRouter \| NoneNoneOpenAPI 3.1 webhooks 路由自 OpenAPI 3.1.0 / FastAPI 0.99.0 起与callbacks不同不依赖具体路径操作deprecatedbool \| NoneNone将全部路径操作标记为弃用include_in_schemaboolTrue是否将所有路径操作写入 OpenAPIgenerate_unique_id_functionCallable[[APIRoute], str]generate_unique_id定制 OpenAPI 操作唯一 ID 的生成函数对自动生成客户端/SDK 尤其有用separate_input_output_schemasboolTrue输入输出结果不同时生成独立 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_schemaFalse。一个综合示例参数均来自源码 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( titleChimichangApp, summaryDeadponds favorite app. Nuff said., descriptionChimichangApp API helps you do awesome stuff. , version0.0.1, openapi_tagstags_metadata, contact{ name: Deadpoolio the Amazing, email: dpx-force.example.com, }, license_info{name: Apache 2.0}, default_response_classORJSONResponse, )三、关键实例属性参考文档列出的成员中以下四个属性最常用源码均位于 属性赋值区3.1openapi_versionOpenAPI 版本字符串默认3.1.0只能作为属性修改不是构造参数。用途是骗过不认识 3.1.0 的旧工具app FastAPI() app.openapi_version 3.0.2 # 需避免使用 3.1.0 才引入的特性源码注释明确提醒这是 hack 手段因为 FastAPI 实际生成的 schema 并不会降级。3.2webhooksAPIRouter实例未提供时自动创建其中定义的路径操作仅用于 OpenAPI 文档中的 webhooks 部分不产生真实可访问的路由app FastAPI() app.webhooks.post(/payments/) async def payment_webhook(): ...3.3stateStarlette 的State对象整个应用生命周期内是同一个对象、不随请求变化。官方说明多数场景应使用 FastAPI 依赖而非state它是直接继承自 Starlette 的用法。3.4dependency_overridesdict[原始依赖, 替换依赖]专为测试设计把昂贵的依赖数据库会话、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 方法 的调用链值得注意先取self.router._get_routes_version()作为路由版本号仅当openapi_schema为空或路由版本发生变化时才调用get_openapi(...)来自 fastapi/openapi/utils.py重新生成生成时传入title、version、openapi_version、summary、description、terms_of_service、contact、license_info、routes、webhooks.routes、tags、servers、separate_input_output_schemas、external_docs——与第二节的元数据参数一一对应结果缓存在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/traceFastAPI提供了与 HTTP 动词一一对应的 8 个装饰器方法如 get 方法它们本质都是薄封装签名完全相同仅转发到self.router.method(...)并带上全部参数。各方法共享的参数集每个方法内都有完整 Doc 注释参数默认值说明path必填路径如/items/{item_id}response_modelNone响应类型。用途四重文档JSON Schema、序列化任意对象转 JSON、过滤仅返回模型定义的字段如剔除password、校验返回数据不合法时 FastAPI 报 500因为这属于 API 开发者违约status_codeNone默认响应状态码直接返回 Response 可覆盖tagsNone操作标签写入 OpenAPIdependenciesNone该操作的Depends()列表summary/descriptionNone标题与描述description未提供时自动从函数 docstring 提取支持 Markdownresponse_descriptionSuccessful Response默认响应的描述responsesNone额外响应声明deprecatedNone标记弃用operation_idNone自定义操作 ID须全 API 唯一可用generate_unique_id_function定制生成规则response_model_include/response_model_excludeNone传给 Pydantic 的字段级 include/excluderesponse_model_by_aliasTrue是否按 alias 序列化response_model_exclude_unsetFalse排除未显式设置的字段保留显式设置为默认值的字段response_model_exclude_defaultsFalse排除值等于默认值的字段无论是否显式设置response_model_exclude_noneFalse排除None字段比前两个更简单粗暴官方建议优先用前两者include_in_schemaTrue是否写入 OpenAPIresponse_classJSONResponse该操作的响应类直接返回 Response 时不生效nameNone内部使用的操作名callbacksNone该操作的 OpenAPI 回调仅文档openapi_extraNone注入该操作 OpenAPI schema 的额外元数据generate_unique_id_functiongenerate_unique_id覆盖全局唯一 ID 生成函数典型用法取自源码 docstringfrom 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必填要包含的APIRouterprefix路径前缀如prefix/userstagsNone应用于该路由全部操作的标签dependenciesNone应用于该路由全部操作的依赖responsesNone该路由级别的额外 OpenAPI 响应deprecatedNone将该路由全部操作标记弃用include_in_schemaTrue是否将该路由全部操作写入 OpenAPIdefault_response_classJSONResponse该路由的默认响应类callbacksNone该路由级别的 OpenAPI 回调generate_unique_id_functiongenerate_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与frontend6.1websocket(path, nameNone, *, dependenciesNone)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(fMessage text was: {data})另有一个继承自 Starlette 的低层websocket_route源码仅做路由注册不带 FastAPI 的依赖注入能力。6.2frontend(path, *, directory, fallbackauto, check_dirauto)frontend 方法 用于把前端静态构建产物如dist/作为低优先级路由提供服务FastAPI 路径操作优先匹配只有没有普通路由命中时才回落到前端文件——因此 API 与 SPA 可共存于同一应用app FastAPI() app.frontend(/, directorydist)参数要点directory静态构建产物所在目录fallback缺失路径的回退文件取值为auto/index.html/404.html/Nonecheck_dir创建应用时是否检查目录存在auto时若环境变量FASTAPI_ENV为developmentfastapi dev命令会自动设置则跳过检查并给出警告否则严格检查。七、on_event已弃用、middleware与exception_handler7.1on_event已弃用改用lifespanon_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(lifespanlifespan)7.2middleware(http)装饰器middleware 方法 当前仅支持http类型装饰器内部等价于self.add_middleware(BaseHTTPMiddleware, dispatchfunc)。官方 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_stackFastAPI 覆写了 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_code418, content{message: fOops! {exc.name} did something.}, )八、源码结构小结与延伸阅读类实现全部集中在 fastapi/applications.py构造器L58-L1018、中间件栈L1020-L1068、openapi()L1070-L1103、setup()内置路由L1105-L1158、frontendL1222、include_routerL1441、HTTP 动词方法L1646 起、on_event/middleware/exception_handlerL4654-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 多提供了三类能力基于类型注解的自动请求校验与响应序列化通过 Pydantic自动生成交互式 API 文档OpenAPI 3.1.0默认在/docs、/redoc、/openapi.json依赖注入系统Depends/dependency_overrides。官方文档给出的标准导入方式是从fastapi包顶层直接导入from fastapi import FastAPI app FastAPI()当前仓库中的版本号为 0.141.1见 版本定义。二、全部初始化参数与默认值总表FastAPI.__init__采用纯关键字参数全部在*之后参数众多但分组清晰。下表汇总了源码 构造器签名 中的全部参数、类型与默认值2.1 基础与调试参数类型默认值说明debugboolFalse是否在服务器错误时返回调试 tracebackrouteslist[BaseRoute] \| NoneNone直接提供路由列表继承自 Starlette 的兼容参数官方标注不建议在 FastAPI 中使用应改用app.get()等路径操作装饰器源码中已标记deprecated2.2 OpenAPI 元数据写入/openapi.json在/docs可见参数类型默认值说明titlestrFastAPIAPI 标题只要openapi_url非空源码会assert self.title即必须提供非空标题summarystr \| NoneNoneAPI 的简短摘要descriptionstrAPI 描述支持 CommonMark Markdown 语法在 Swagger UI 中渲染versionstr0.1.0你的应用的版本号不是 OpenAPI 规范版本也不是 FastAPI 框架版本openapi_urlstr \| None/openapi.jsonOpenAPI 文档的提供地址设为None时不公开提供文档且/docs、/redoc自动禁用openapi_tagslist[dict] \| NoneNone标签元数据列表每项含name、description可选 Markdown、externalDocs含description与url列表顺序即 Swagger UI 中分组展示顺序serverslist[dict] \| NoneNone目标服务器连接信息每项含url支持{变量}模板、description、variables未提供时若存在root_path则自动补一个指向root_path的 server否则省略该字段terms_of_servicestr \| NoneNone服务条款 URLcontactdict \| NoneNone联系人信息可含name、url、email字段license_infodict \| NoneNone许可证信息可含name设置后必填、identifierSPDX 表达式与url互斥OpenAPI 3.1.0 起、urlopenapi_external_docsdict \| NoneNone外部文档链接必须含description和url合法 URL 格式openapi_prefixstr已弃用改用更贴近 ASGI 标准的root_path传入非空值时源码会打印弃用警告见 警告逻辑root_pathstr由代理处理、应用不可见但外部客户端可见的路径前缀影响 Swagger UI 等行为root_path_in_serversboolTrue是否用root_path自动生成 OpenAPIservers中的 URL设为False可禁用2.3 文档 UISwagger UI / ReDoc参数类型默认值说明docs_urlstr \| None/docsSwagger UI 交互文档路径None禁用openapi_url为None时自动禁用redoc_urlstr \| None/redocReDoc 备用文档路径规则同上swagger_ui_oauth2_redirect_urlstr \| None/docs/oauth2-redirectSwagger UI 的 OAuth2 回调端点仅在使用 Authorize 按钮时相关swagger_ui_init_oauthdict \| NoneNoneSwagger UI 的 OAuth2 初始化配置字典swagger_ui_parametersdict \| NoneNone传给 Swagger UI 的额外初始化参数可定制 UI 行为2.4 路由与运行时行为参数类型默认值说明dependenciesSequence[Depends] \| NoneNone全局依赖列表会应用到每一个路径操作包括子路由中的操作default_response_classtype[Response]JSONResponse默认响应类如可改为ORJSONResponseredirect_slashesboolTrue是否对尾斜杠不一致的 URL 做 307 重定向如/items→/items/middlewareSequence[Middleware] \| NoneNone创建应用时加入的中间件列表FastAPI 中更常用app.add_middleware()exception_handlersdict \| NoneNone异常处理器字典FastAPI 中更常用app.exception_handler()装饰器on_startupSequence[Callable] \| NoneNone启动事件处理函数列表官方建议改用lifespanon_shutdownSequence[Callable] \| NoneNone关闭事件处理函数列表官方建议改用lifespanlifespanLifespan[AppType] \| NoneNone以单个上下文管理器替代 startup/shutdown 两组函数strict_content_typeboolTrue严格校验请求Content-Type为True时不带该头的带 body 请求不会被按 JSON 解析可防御绕过 CORS 预检的 CSRF 类攻击设为False则兼容不发Content-Type的旧客户端**extraAny—透传给 Starlette 的额外关键字参数仅存于应用实例FastAPI 本身不使用2.5 OpenAPI 输出定制参数类型默认值说明responsesdict[int \| str, dict] \| NoneNone附加在 OpenAPI 中的额外响应声明callbackslist[BaseRoute] \| NoneNone应用到所有路径操作的 OpenAPI 回调仅文档用途webhooksAPIRouter \| NoneNoneOpenAPI 3.1 webhooks 路由自 OpenAPI 3.1.0 / FastAPI 0.99.0 起与callbacks不同不依赖具体路径操作deprecatedbool \| NoneNone将全部路径操作标记为弃用include_in_schemaboolTrue是否将所有路径操作写入 OpenAPIgenerate_unique_id_functionCallable[[APIRoute], str]generate_unique_id定制 OpenAPI 操作唯一 ID 的生成函数对自动生成客户端/SDK 尤其有用separate_input_output_schemasboolTrue输入输出结果不同时生成独立 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_schemaFalse。一个综合示例参数均来自源码 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( titleChimichangApp, summaryDeadponds favorite app. Nuff said., descriptionChimichangApp API helps you do awesome stuff. , version0.0.1, openapi_tagstags_metadata, contact{ name: Deadpoolio the Amazing, email: dpx-force.example.com, }, license_info{name: Apache 2.0}, default_response_classORJSONResponse, )三、关键实例属性参考文档列出的成员中以下四个属性最常用源码均位于 属性赋值区3.1openapi_versionOpenAPI 版本字符串默认3.1.0只能作为属性修改不是构造参数。用途是骗过不认识 3.1.0 的旧工具app FastAPI() app.openapi_version 3.0.2 # 需避免使用 3.1.0 才引入的特性源码注释明确提醒这是 hack 手段因为 FastAPI 实际生成的 schema 并不会降级。3.2webhooksAPIRouter实例未提供时自动创建其中定义的路径操作仅用于 OpenAPI 文档中的 webhooks 部分不产生真实可访问的路由app FastAPI() app.webhooks.post(/payments/) async def payment_webhook(): ...3.3stateStarlette 的State对象整个应用生命周期内是同一个对象、不随请求变化。官方说明多数场景应使用 FastAPI 依赖而非state它是直接继承自 Starlette 的用法。3.4dependency_overridesdict[原始依赖, 替换依赖]专为测试设计把昂贵的依赖数据库会话、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 方法 的调用链值得注意先取self.router._get_routes_version()作为路由版本号仅当openapi_schema为空或路由版本发生变化时才调用get_openapi(...)来自 fastapi/openapi/utils.py重新生成生成时传入title、version、openapi_version、summary、description、terms_of_service、contact、license_info、routes、webhooks.routes、tags、servers、separate_input_output_schemas、external_docs——与第二节的元数据参数一一对应结果缓存在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/traceFastAPI提供了与 HTTP 动词一一对应的 8 个装饰器方法如 get 方法它们本质都是薄封装签名完全相同仅转发到self.router.method(...)并带上全部参数。各方法共享的参数集每个方法内都有完整 Doc 注释参数默认值说明path必填路径如/items/{item_id}response_modelNone响应类型。用途四重文档JSON Schema、序列化任意对象转 JSON、过滤仅返回模型定义的字段如剔除password、校验返回数据不合法时 FastAPI 报 500因为这属于 API 开发者违约status_codeNone默认响应状态码直接返回 Response 可覆盖tagsNone操作标签写入 OpenAPIdependenciesNone该操作的Depends()列表summary/descriptionNone标题与描述description未提供时自动从函数 docstring 提取支持 Markdownresponse_descriptionSuccessful Response默认响应的描述responsesNone额外响应声明deprecatedNone标记弃用operation_idNone自定义操作 ID须全 API 唯一可用generate_unique_id_function定制生成规则response_model_include/response_model_excludeNone传给 Pydantic 的字段级 include/excluderesponse_model_by_aliasTrue是否按 alias 序列化response_model_exclude_unsetFalse排除未显式设置的字段保留显式设置为默认值的字段response_model_exclude_defaultsFalse排除值等于默认值的字段无论是否显式设置response_model_exclude_noneFalse排除None字段比前两个更简单粗暴官方建议优先用前两者include_in_schemaTrue是否写入 OpenAPIresponse_classJSONResponse该操作的响应类直接返回 Response 时不生效nameNone内部使用的操作名callbacksNone该操作的 OpenAPI 回调仅文档openapi_extraNone注入该操作 OpenAPI schema 的额外元数据generate_unique_id_functiongenerate_unique_id覆盖全局唯一 ID 生成函数典型用法取自源码 docstringfrom 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必填要包含的APIRouterprefix路径前缀如prefix/userstagsNone应用于该路由全部操作的标签dependenciesNone应用于该路由全部操作的依赖responsesNone该路由级别的额外 OpenAPI 响应deprecatedNone将该路由全部操作标记弃用include_in_schemaTrue是否将该路由全部操作写入 OpenAPIdefault_response_classJSONResponse该路由的默认响应类callbacksNone该路由级别的 OpenAPI 回调generate_unique_id_functiongenerate_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与frontend6.1websocket(path, nameNone, *, dependenciesNone)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(fMessage text was: {data})另有一个继承自 Starlette 的低层websocket_route源码仅做路由注册不带 FastAPI 的依赖注入能力。6.2frontend(path, *, directory, fallbackauto, check_dirauto)frontend 方法 用于把前端静态构建产物如dist/作为低优先级路由提供服务FastAPI 路径操作优先匹配只有没有普通路由命中时才回落到前端文件——因此 API 与 SPA 可共存于同一应用app FastAPI() app.frontend(/, directorydist)参数要点directory静态构建产物所在目录fallback缺失路径的回退文件取值为auto/index.html/404.html/Nonecheck_dir创建应用时是否检查目录存在auto时若环境变量FASTAPI_ENV为developmentfastapi dev命令会自动设置则跳过检查并给出警告否则严格检查。七、on_event已弃用、middleware与exception_handler7.1on_event已弃用改用lifespanon_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(lifespanlifespan)7.2middleware(http)装饰器middleware 方法 当前仅支持http类型装饰器内部等价于self.add_middleware(BaseHTTPMiddleware, dispatchfunc)。官方 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_stackFastAPI 覆写了 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_code418, content{message: fOops! {exc.name} did something.}, )八、源码结构小结与延伸阅读类实现全部集中在 fastapi/applications.py构造器L58-L1018、中间件栈L1020-L1068、openapi()L1070-L1103、setup()内置路由L1105-L1158、frontendL1222、include_routerL1441、HTTP 动词方法L1646 起、on_event/middleware/exception_handlerL4654-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考