FastAPI 集成 GraphQL 完整指南ASGI 原理、Strawberry 实战与旧版 GraphQLApp 迁移【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文以 FastAPI 官方文档《GraphQL》(德语版位于 docs/de/docs/how-to/graphql.md英文版位于 docs/en/docs/how-to/graphql.md) 为主体系统讲解如何在 FastAPI 应用中集成 GraphQL包括基于 ASGI 标准的集成原理、可选 GraphQL 库的对比、推荐方案 Strawberry 的完整集成代码以及如何把旧版 StarletteGraphQLApp代码迁移到替代方案。读完后你可以独立完成一个 FastAPI GraphQL 混合应用的搭建并理解其底层路由机制与可验证的运行行为。为什么 FastAPI 可以轻松集成 GraphQLASGI 是前提FastAPI 的底层基于ASGIAsynchronous Server Gateway Interface异步服务器网关接口标准。这一事实决定了任何同样兼容 ASGI 的GraphQL库都可以直接挂到 FastAPI 应用上无需适配器或特殊改造。更关键的一点是普通的 FastAPI 路径操作path operations可以与 GraphQL 共存于同一个应用中。也就是说你可以让 REST 风格的 API 端点和 GraphQL 端点共享同一个FastAPI()实例各自承担不同职责。选型提示官方文档原话GraphQL 只解决非常特定的应用场景。与常见的 Web API如 REST相比它同时存在优势与劣势。在引入之前请务必评估它为你的用例带来的收益是否足以抵消其带来的代价。从源码结构看这种共存能力来自 FastAPI 对标准 ASGI 应用的路由聚合机制。FastAPI 的include_router()方法定义于 fastapi/applications.py其实现最终只是把参数透传给self.router.include_router(...)见该文件 L1633-L1644。由于 Strawberry 的GraphQLRouter本身就是APIRouter的子类即一个标准的 FastAPI/Starlette 路由容器它才能被像普通 Router 一样挂载并参与同一份 OpenAPI schema 的生成。可选的 GraphQL 库及其 ASGI 集成方式官方文档列出了以下具有ASGI支持、可与 FastAPI 配合使用的 GraphQL 库库与 FastAPI 的集成方式特点Strawberry内置 FastAPI 集成文档使用strawberry.fastapi.GraphQLRouter全基于类型注解设计上最接近 FastAPIAriadne提供专门的 FastAPI 集成文档成熟的独立 GraphQL 框架Tartiflette通过独立的Tartiflette ASGI包提供 ASGI 集成以 ASGI 中间件/应用形式接入Graphene通过starlette-graphene3包接入与旧版 StarletteGraphQLApp接口几乎一致适合迁移各库的完整用法请查阅其官方文档仓库文档中已给出对应入口。推荐方案Strawberry FastAPI 完整集成在需要或希望使用 GraphQL 的场景下FastAPI 官方文档推荐Strawberry原因是它的设计与 FastAPI 的设计最为接近——一切都基于类型注解type annotations而不是自定义的类体系与类型系统。文档同时保留了灵活性如果你的用例更适合其他库可以自由选择但官方立场是建议你优先尝试 Strawberry。FastAPI 仓库自带了一份可运行的集成示例位于 docs_src/graphql_/tutorial001_py310.py。完整代码如下import strawberry from fastapi import FastAPI from strawberry.fastapi import GraphQLRouter strawberry.type class User: name: str age: int strawberry.type class Query: strawberry.field def user(self) - User: return User(namePatrick, age100) schema strawberry.Schema(queryQuery) graphql_app GraphQLRouter(schema) app FastAPI() app.include_router(graphql_app, prefix/graphql)逐段解析原文档用hl[3,22,25]标注了第 3、22、25 行为关键行定义类型与查询L6-L16strawberry.type把普通 Python 类标记为 GraphQL 对象类型UserQuery类上的strawberry.field声明查询字段。这与 FastAPI 使用 Pydantic 模型 类型注解声明请求/响应的方式在风格上高度一致——这也是官方推荐它的核心原因。构建 SchemaL19strawberry.Schema(queryQuery)将所有查询类型组装成 GraphQL Schema。创建 ASGI 路由L22关键行GraphQLRouter(schema)返回一个可直接挂载的路由容器它内部实现了 GraphQL 端点的 GETGraphiQL IDE与 POST执行查询处理。挂载到 FastAPIL25关键行app.include_router(graphql_app, prefix/graphql)将其注册到/graphql前缀下。如前文所述这一步走的就是 fastapi/applications.py 中的标准include_router()流程因此 GraphQL 端点会和其他路径操作一样出现在应用的 OpenAPI 文档中。依赖说明该示例运行需要安装 Strawberrystrawberry-graphql包。FastAPI 仓库自身的测试依赖中已锁定该版本范围见 pyproject.toml 的tests依赖组strawberry-graphql 0.200.0,1.0.0位于文件 L174。当前仓库的 FastAPI 版本为 0.141.1见 fastapi/init.py。运行时行为验证查询响应与 OpenAPI 输出仓库中配套的功能测试 tests/test_tutorial/test_graphql/test_tutorial001.py 直接导入了上面的示例应用from docs_src.graphql_.tutorial001_py310 import app并用 Starlette 的TestClient验证了两点可作为集成成功与否的可验证依据1. POST 查询能正常返回 GraphQL 数据def test_query(client: TestClient): response client.post(/graphql, json{query: { user { name, age } }}) assert response.status_code 200 assert response.json() {data: {user: {name: Patrick, age: 100}}}2. GraphQL 端点自动进入 OpenAPI schema/openapi.json的快照断言显示/graphql路径包含GET与POST两个操作。其中GET操作的响应描述明确写着The GraphiQL integrated development environment.即GET /graphql在浏览器中打开时返回GraphiQL 集成开发环境页面若未启用则返回 404。POST /graphql用于执行 GraphQL 查询并返回application/json响应。这两个断言意味着只要照抄示例代码你就获得了「浏览器里可交互的 GraphiQL 调试界面 标准 JSON 查询接口 与 FastAPI 文档统一展示」三合一的结果无需任何额外配置。旧版 StarletteGraphQLApp的迁移方案早期版本的 Starlette 曾内置一个GraphQLApp类用于与 Graphene 集成。该类已从 Starlette 中废弃deprecated。如果你的存量代码仍在使用它迁移路径非常直接迁移到starlette-graphene3包——它覆盖相同的使用场景并且接口与旧GraphQLApp几乎完全一致almost identical interface基本可以换包名 换导入完成迁移。同时官方文档在此再次给出提示即便你只是为迁移而来也值得评估Strawberry——它基于类型注解而非自定义类与类型与 FastAPI 的开发体验更一致。总结与延伸阅读前提FastAPI 基于 ASGI任何 ASGI 兼容的 GraphQL 库均可挂载且能与普通路径操作共存于同一应用路由聚合机制见 fastapi/applications.py。选型Strawberry、Ariadne、Tartiflette、Graphene经 starlette-graphene3四条路线均可行官方推荐 Strawberry示例代码见 docs_src/graphql_/tutorial001_py310.py验证用例见 tests/test_tutorial/test_graphql/test_tutorial001.py。遗留代码Starlette 旧版GraphQLApp已废弃迁移到 starlette-graphene3 即可平滑过渡。决策GraphQL 解决的是特定场景问题引入前必须权衡其相对于常规 Web API 的利弊。关于 GraphQL 规范本身可查阅 GraphQL 官方文档关于各库的完整 API 与进阶用法认证、订阅、持久化查询等请分别参阅 Strawberry、Ariadne、Tartiflette、Graphene 各项目的官方文档——FastAPI 仓库的这篇 how-to 聚焦的是如何把它们接进来而非 GraphQL 语言本身的完整教程。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/5 16:40:11 · 阅读 1.2k FastAPI 集成 GraphQL 完整指南：ASGI 原理、Strawberry 实战与旧版 GraphQLApp 迁移
FastAPI 集成 GraphQL 完整指南ASGI 原理、Strawberry 实战与旧版 GraphQLApp 迁移【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文以 FastAPI 官方文档《GraphQL》(德语版位于 docs/de/docs/how-to/graphql.md英文版位于 docs/en/docs/how-to/graphql.md) 为主体系统讲解如何在 FastAPI 应用中集成 GraphQL包括基于 ASGI 标准的集成原理、可选 GraphQL 库的对比、推荐方案 Strawberry 的完整集成代码以及如何把旧版 StarletteGraphQLApp代码迁移到替代方案。读完后你可以独立完成一个 FastAPI GraphQL 混合应用的搭建并理解其底层路由机制与可验证的运行行为。为什么 FastAPI 可以轻松集成 GraphQLASGI 是前提FastAPI 的底层基于ASGIAsynchronous Server Gateway Interface异步服务器网关接口标准。这一事实决定了任何同样兼容 ASGI 的GraphQL库都可以直接挂到 FastAPI 应用上无需适配器或特殊改造。更关键的一点是普通的 FastAPI 路径操作path operations可以与 GraphQL 共存于同一个应用中。也就是说你可以让 REST 风格的 API 端点和 GraphQL 端点共享同一个FastAPI()实例各自承担不同职责。选型提示官方文档原话GraphQL 只解决非常特定的应用场景。与常见的 Web API如 REST相比它同时存在优势与劣势。在引入之前请务必评估它为你的用例带来的收益是否足以抵消其带来的代价。从源码结构看这种共存能力来自 FastAPI 对标准 ASGI 应用的路由聚合机制。FastAPI 的include_router()方法定义于 fastapi/applications.py其实现最终只是把参数透传给self.router.include_router(...)见该文件 L1633-L1644。由于 Strawberry 的GraphQLRouter本身就是APIRouter的子类即一个标准的 FastAPI/Starlette 路由容器它才能被像普通 Router 一样挂载并参与同一份 OpenAPI schema 的生成。可选的 GraphQL 库及其 ASGI 集成方式官方文档列出了以下具有ASGI支持、可与 FastAPI 配合使用的 GraphQL 库库与 FastAPI 的集成方式特点Strawberry内置 FastAPI 集成文档使用strawberry.fastapi.GraphQLRouter全基于类型注解设计上最接近 FastAPIAriadne提供专门的 FastAPI 集成文档成熟的独立 GraphQL 框架Tartiflette通过独立的Tartiflette ASGI包提供 ASGI 集成以 ASGI 中间件/应用形式接入Graphene通过starlette-graphene3包接入与旧版 StarletteGraphQLApp接口几乎一致适合迁移各库的完整用法请查阅其官方文档仓库文档中已给出对应入口。推荐方案Strawberry FastAPI 完整集成在需要或希望使用 GraphQL 的场景下FastAPI 官方文档推荐Strawberry原因是它的设计与 FastAPI 的设计最为接近——一切都基于类型注解type annotations而不是自定义的类体系与类型系统。文档同时保留了灵活性如果你的用例更适合其他库可以自由选择但官方立场是建议你优先尝试 Strawberry。FastAPI 仓库自带了一份可运行的集成示例位于 docs_src/graphql_/tutorial001_py310.py。完整代码如下import strawberry from fastapi import FastAPI from strawberry.fastapi import GraphQLRouter strawberry.type class User: name: str age: int strawberry.type class Query: strawberry.field def user(self) - User: return User(namePatrick, age100) schema strawberry.Schema(queryQuery) graphql_app GraphQLRouter(schema) app FastAPI() app.include_router(graphql_app, prefix/graphql)逐段解析原文档用hl[3,22,25]标注了第 3、22、25 行为关键行定义类型与查询L6-L16strawberry.type把普通 Python 类标记为 GraphQL 对象类型UserQuery类上的strawberry.field声明查询字段。这与 FastAPI 使用 Pydantic 模型 类型注解声明请求/响应的方式在风格上高度一致——这也是官方推荐它的核心原因。构建 SchemaL19strawberry.Schema(queryQuery)将所有查询类型组装成 GraphQL Schema。创建 ASGI 路由L22关键行GraphQLRouter(schema)返回一个可直接挂载的路由容器它内部实现了 GraphQL 端点的 GETGraphiQL IDE与 POST执行查询处理。挂载到 FastAPIL25关键行app.include_router(graphql_app, prefix/graphql)将其注册到/graphql前缀下。如前文所述这一步走的就是 fastapi/applications.py 中的标准include_router()流程因此 GraphQL 端点会和其他路径操作一样出现在应用的 OpenAPI 文档中。依赖说明该示例运行需要安装 Strawberrystrawberry-graphql包。FastAPI 仓库自身的测试依赖中已锁定该版本范围见 pyproject.toml 的tests依赖组strawberry-graphql 0.200.0,1.0.0位于文件 L174。当前仓库的 FastAPI 版本为 0.141.1见 fastapi/init.py。运行时行为验证查询响应与 OpenAPI 输出仓库中配套的功能测试 tests/test_tutorial/test_graphql/test_tutorial001.py 直接导入了上面的示例应用from docs_src.graphql_.tutorial001_py310 import app并用 Starlette 的TestClient验证了两点可作为集成成功与否的可验证依据1. POST 查询能正常返回 GraphQL 数据def test_query(client: TestClient): response client.post(/graphql, json{query: { user { name, age } }}) assert response.status_code 200 assert response.json() {data: {user: {name: Patrick, age: 100}}}2. GraphQL 端点自动进入 OpenAPI schema/openapi.json的快照断言显示/graphql路径包含GET与POST两个操作。其中GET操作的响应描述明确写着The GraphiQL integrated development environment.即GET /graphql在浏览器中打开时返回GraphiQL 集成开发环境页面若未启用则返回 404。POST /graphql用于执行 GraphQL 查询并返回application/json响应。这两个断言意味着只要照抄示例代码你就获得了「浏览器里可交互的 GraphiQL 调试界面 标准 JSON 查询接口 与 FastAPI 文档统一展示」三合一的结果无需任何额外配置。旧版 StarletteGraphQLApp的迁移方案早期版本的 Starlette 曾内置一个GraphQLApp类用于与 Graphene 集成。该类已从 Starlette 中废弃deprecated。如果你的存量代码仍在使用它迁移路径非常直接迁移到starlette-graphene3包——它覆盖相同的使用场景并且接口与旧GraphQLApp几乎完全一致almost identical interface基本可以换包名 换导入完成迁移。同时官方文档在此再次给出提示即便你只是为迁移而来也值得评估Strawberry——它基于类型注解而非自定义类与类型与 FastAPI 的开发体验更一致。总结与延伸阅读前提FastAPI 基于 ASGI任何 ASGI 兼容的 GraphQL 库均可挂载且能与普通路径操作共存于同一应用路由聚合机制见 fastapi/applications.py。选型Strawberry、Ariadne、Tartiflette、Graphene经 starlette-graphene3四条路线均可行官方推荐 Strawberry示例代码见 docs_src/graphql_/tutorial001_py310.py验证用例见 tests/test_tutorial/test_graphql/test_tutorial001.py。遗留代码Starlette 旧版GraphQLApp已废弃迁移到 starlette-graphene3 即可平滑过渡。决策GraphQL 解决的是特定场景问题引入前必须权衡其相对于常规 Web API 的利弊。关于 GraphQL 规范本身可查阅 GraphQL 官方文档关于各库的完整 API 与进阶用法认证、订阅、持久化查询等请分别参阅 Strawberry、Ariadne、Tartiflette、Graphene 各项目的官方文档——FastAPI 仓库的这篇 how-to 聚焦的是如何把它们接进来而非 GraphQL 语言本身的完整教程。【免费下载链接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考