FastAPI 集成 GraphQL 完整指南ASGI 原理、Strawberry 實(shí)戰(zhàn)與舊版 GraphQLApp 遷移【免費(fèi)下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastapi本文以 FastAPI 官方文檔《GraphQL》(德語版位于 docs/de/docs/how-to/graphql.md英文版位于 docs/en/docs/how-to/graphql.md) 為主體系統(tǒng)講解如何在 FastAPI 應(yīng)用中集成 GraphQL包括基于 ASGI 標(biāo)準(zhǔn)的集成原理、可選 GraphQL 庫的對(duì)比、推薦方案 Strawberry 的完整集成代碼以及如何把舊版 StarletteGraphQLApp代碼遷移到替代方案。讀完后你可以獨(dú)立完成一個(gè) FastAPI GraphQL 混合應(yīng)用的搭建并理解其底層路由機(jī)制與可驗(yàn)證的運(yùn)行行為。為什么 FastAPI 可以輕松集成 GraphQLASGI 是前提FastAPI 的底層基于ASGIAsynchronous Server Gateway Interface異步服務(wù)器網(wǎng)關(guān)接口標(biāo)準(zhǔn)。這一事實(shí)決定了任何同樣兼容 ASGI 的GraphQL庫都可以直接掛到 FastAPI 應(yīng)用上無需適配器或特殊改造。更關(guān)鍵的一點(diǎn)是普通的 FastAPI 路徑操作path operations可以與 GraphQL 共存于同一個(gè)應(yīng)用中。也就是說你可以讓 REST 風(fēng)格的 API 端點(diǎn)和 GraphQL 端點(diǎn)共享同一個(gè)FastAPI()實(shí)例各自承擔(dān)不同職責(zé)。選型提示官方文檔原話GraphQL 只解決非常特定的應(yīng)用場景。與常見的 Web API如 REST相比它同時(shí)存在優(yōu)勢與劣勢。在引入之前請(qǐng)務(wù)必評(píng)估它為你的用例帶來的收益是否足以抵消其帶來的代價(jià)。從源碼結(jié)構(gòu)看這種共存能力來自 FastAPI 對(duì)標(biāo)準(zhǔn) ASGI 應(yīng)用的路由聚合機(jī)制。FastAPI 的include_router()方法定義于 fastapi/applications.py其實(shí)現(xiàn)最終只是把參數(shù)透傳給self.router.include_router(...)見該文件 L1633-L1644。由于 Strawberry 的GraphQLRouter本身就是APIRouter的子類即一個(gè)標(biāo)準(zhǔn)的 FastAPI/Starlette 路由容器它才能被像普通 Router 一樣掛載并參與同一份 OpenAPI schema 的生成?？蛇x的 GraphQL 庫及其 ASGI 集成方式官方文檔列出了以下具有ASGI支持、可與 FastAPI 配合使用的 GraphQL 庫庫與 FastAPI 的集成方式特點(diǎn)Strawberry內(nèi)置 FastAPI 集成文檔使用strawberry.fastapi.GraphQLRouter全基于類型注解設(shè)計(jì)上最接近 FastAPIAriadne提供專門的 FastAPI 集成文檔成熟的獨(dú)立 GraphQL 框架Tartiflette通過獨(dú)立的Tartiflette ASGI包提供 ASGI 集成以 ASGI 中間件/應(yīng)用形式接入Graphene通過starlette-graphene3包接入與舊版 StarletteGraphQLApp接口幾乎一致適合遷移各庫的完整用法請(qǐng)查閱其官方文檔倉庫文檔中已給出對(duì)應(yīng)入口。推薦方案Strawberry FastAPI 完整集成在需要或希望使用 GraphQL 的場景下FastAPI 官方文檔推薦Strawberry原因是它的設(shè)計(jì)與 FastAPI 的設(shè)計(jì)最為接近——一切都基于類型注解type annotations而不是自定義的類體系與類型系統(tǒng)。文檔同時(shí)保留了靈活性如果你的用例更適合其他庫可以自由選擇但官方立場是建議你優(yōu)先嘗試 Strawberry。FastAPI 倉庫自帶了一份可運(yùn)行的集成示例位于 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]標(biāo)注了第 3、22、25 行為關(guān)鍵行定義類型與查詢L6-L16strawberry.type把普通 Python 類標(biāo)記為 GraphQL 對(duì)象類型UserQuery類上的strawberry.field聲明查詢字段。這與 FastAPI 使用 Pydantic 模型 類型注解聲明請(qǐng)求/響應(yīng)的方式在風(fēng)格上高度一致——這也是官方推薦它的核心原因。構(gòu)建 SchemaL19strawberry.Schema(queryQuery)將所有查詢類型組裝成 GraphQL Schema。創(chuàng)建 ASGI 路由L22關(guān)鍵行GraphQLRouter(schema)返回一個(gè)可直接掛載的路由容器它內(nèi)部實(shí)現(xiàn)了 GraphQL 端點(diǎn)的 GETGraphiQL IDE與 POST執(zhí)行查詢處理。掛載到 FastAPIL25關(guān)鍵行app.include_router(graphql_app, prefix/graphql)將其注冊(cè)到/graphql前綴下。如前文所述這一步走的就是 fastapi/applications.py 中的標(biāo)準(zhǔn)include_router()流程因此 GraphQL 端點(diǎn)會(huì)和其他路徑操作一樣出現(xiàn)在應(yīng)用的 OpenAPI 文檔中。依賴說明該示例運(yùn)行需要安裝 Strawberrystrawberry-graphql包。FastAPI 倉庫自身的測試依賴中已鎖定該版本范圍見 pyproject.toml 的tests依賴組strawberry-graphql 0.200.0,1.0.0位于文件 L174。當(dāng)前倉庫的 FastAPI 版本為 0.141.1見 fastapi/init.py。運(yùn)行時(shí)行為驗(yàn)證查詢響應(yīng)與 OpenAPI 輸出倉庫中配套的功能測試 tests/test_tutorial/test_graphql/test_tutorial001.py 直接導(dǎo)入了上面的示例應(yīng)用from docs_src.graphql_.tutorial001_py310 import app并用 Starlette 的TestClient驗(yàn)證了兩點(diǎn)可作為集成成功與否的可驗(yàn)證依據(jù)1. POST 查詢能正常返回 GraphQL 數(shù)據(jù)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 端點(diǎn)自動(dòng)進(jìn)入 OpenAPI schema/openapi.json的快照斷言顯示/graphql路徑包含GET與POST兩個(gè)操作。其中GET操作的響應(yīng)描述明確寫著The GraphiQL integrated development environment.即GET /graphql在瀏覽器中打開時(shí)返回GraphiQL 集成開發(fā)環(huán)境頁面若未啟用則返回 404。POST /graphql用于執(zhí)行 GraphQL 查詢并返回application/json響應(yīng)。這兩個(gè)斷言意味著只要照抄示例代碼你就獲得了「瀏覽器里可交互的 GraphiQL 調(diào)試界面 標(biāo)準(zhǔn) JSON 查詢接口 與 FastAPI 文檔統(tǒng)一展示」三合一的結(jié)果無需任何額外配置。舊版 StarletteGraphQLApp的遷移方案早期版本的 Starlette 曾內(nèi)置一個(gè)GraphQLApp類用于與 Graphene 集成。該類已從 Starlette 中廢棄deprecated。如果你的存量代碼仍在使用它遷移路徑非常直接遷移到starlette-graphene3包——它覆蓋相同的使用場景并且接口與舊GraphQLApp幾乎完全一致almost identical interface基本可以換包名 換導(dǎo)入完成遷移。同時(shí)官方文檔在此再次給出提示即便你只是為遷移而來也值得評(píng)估Strawberry——它基于類型注解而非自定義類與類型與 FastAPI 的開發(fā)體驗(yàn)更一致?？偨Y(jié)與延伸閱讀前提FastAPI 基于 ASGI任何 ASGI 兼容的 GraphQL 庫均可掛載且能與普通路徑操作共存于同一應(yīng)用路由聚合機(jī)制見 fastapi/applications.py。選型Strawberry、Ariadne、Tartiflette、Graphene經(jīng) starlette-graphene3四條路線均可行官方推薦 Strawberry示例代碼見 docs_src/graphql_/tutorial001_py310.py驗(yàn)證用例見 tests/test_tutorial/test_graphql/test_tutorial001.py。遺留代碼Starlette 舊版GraphQLApp已廢棄遷移到 starlette-graphene3 即可平滑過渡。決策GraphQL 解決的是特定場景問題引入前必須權(quán)衡其相對(duì)于常規(guī) Web API 的利弊。關(guān)于 GraphQL 規(guī)范本身可查閱 GraphQL 官方文檔關(guān)于各庫的完整 API 與進(jìn)階用法認(rèn)證、訂閱、持久化查詢等請(qǐng)分別參閱 Strawberry、Ariadne、Tartiflette、Graphene 各項(xiàng)目的官方文檔——FastAPI 倉庫的這篇 how-to 聚焦的是如何把它們接進(jìn)來而非 GraphQL 語言本身的完整教程?！久赓M(fèi)下載鏈接】fastapiFastAPI framework, high performance, easy to learn, fast to code, ready for production項(xiàng)目地址: https://gitcode.com/GitHub_Trending/fa/fastapi創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考