據(jù)層)
前端靜態(tài)站點Web框架【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址https://gitcode.com/gh_mirrors/ga/gatsby點擊查看免費下載本篇技術(shù)指南以gatsby-source-graphql插件的 CHANGELOG 版本演進為主線結(jié)合 README 與倉庫源碼系統(tǒng)講解如何在 Gatsby 項目中接入任意第三方 GraphQL API涵蓋全部配置項、Schema 縫合原理、查詢批處理機制、Schema 定制與數(shù)據(jù)刷新策略。讀完本文你將掌握從零配置、認證接入到性能調(diào)優(yōu)與版本選型的完整實戰(zhàn)能力。插件定位它解決什么問題gatsby-source-graphql是一個將第三方 GraphQL API 直接接入 Gatsby GraphQL 數(shù)據(jù)層的官方插件。核心思路是遠程 Schema 通過縫合stitching技術(shù)并入 Gatsby Schema——聲明一個任意的類型名typeName包裹遠程 Schema 的 Query 類型并把遠程 Schema 掛載到 Gatsby 查詢的某個字段fieldName下之后你就可以在 Gatsby 頁面查詢里像查詢本地數(shù)據(jù)一樣查詢遠程 GraphQL 服務(wù)。從 CHANGELOG 可以看出該插件在 4.23.0 版本起被標記為soft deprecate軟棄用。官方在 README 中明確警告如果你的內(nèi)容源已有對應(yīng) source 插件如 WordPress 用gatsby-source-wordpress、Contentful 用gatsby-source-contentful不建議使用本插件因為它存在已知限制不支持增量構(gòu)建、CMS Preview、圖片優(yōu)化且對 GraphQL 數(shù)據(jù)層支持不完整。它只適合簡單概念驗證PoC以及沒有現(xiàn)成 source 插件的數(shù)據(jù)源場景。安裝與最小配置安裝命令與任何 Gatsby 插件一致npm install gatsby-source-graphql在gatsby-config.js中做最小配置只需三個核心選項url、typeName、fieldName// In your gatsby-config.js module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { // 遠程 Schema Query 類型的任意名稱 typeName: SWAPI, // 遠程 Schema 在 Gatsby 查詢中掛載的字段名查詢時直接使用 fieldName: swapi, // 遠程 GraphQL API 地址 url: https://swapi-graphql.netlify.app/.netlify/functions/index, }, }, ], }配置完成后即可在 Gatsby 頁面查詢中這樣使用fieldName即查詢?nèi)肟趝 # 這是你在配置里定義的 fieldName swapi { allSpecies { name } } }配置校驗規(guī)則源碼級從 gatsby-node.js 的pluginOptionsSchema可以看出插件的校驗約束typeName、fieldName為必填字符串必須滿足url與createLink至少提供其一Joi.object().or(url, createLink)headers允許是對象或函數(shù)fetch、createLink、createSchema、transformSchema必須是函數(shù)dataLoaderOptions會進一步校驗batch、maxBatchSize、batchScheduleFn、cache、cacheKeyFn、cacheMap含get/set/delete/clear方法等字段。對應(yīng)測試見 src/tests/gatsby-node.js缺少必填項時分別報錯typeName is required、fieldName is required、value must contain at least one of [url, createLink]。配置項全景下表匯總插件全部配置項及其作用依據(jù) README 與 gatsby-node.js配置項類型默認值說明urlstring—遠程 GraphQL 端點與createLink二選一typeNamestring必填—遠程 Schema Query 類型被包裝后的任意名稱fieldNamestring必填—遠程 Schema 在 Gatsby 查詢中掛載的根字段名headersobject | async function{}HTTP 請求頭函數(shù)形式支持異步獲取fetchfunction內(nèi)置fetchWrapper自定義 fetch 兼容函數(shù)fetchOptionsobject{}透傳給 node-fetch 的額外選項createLinkfunction—手動構(gòu)造 Apollo Link返回 Link 或 PromisecreateSchemafunction—自定義遠程 Schema 來源SDL/內(nèi)省 JSONbatchbooleanfalse是否開啟查詢批處理transformSchemafunction—在縫合前定制遠程 Schema 的變換邏輯dataLoaderOptionsobject—DataLoader 選項如maxBatchSizerefetchIntervalnumber無定時重新拉取數(shù)據(jù)的間隔秒Schema 縫合流程與緩存機制插件在createSchemaCustomization生命周期中完成遠程 Schema 的接入核心流程見 gatsby-node.js為構(gòu)建 Apollo Link若提供createLink則調(diào)用它否則用url、fetch、fetchOptions、headers構(gòu)造 HTTP Linkbatch: true時改為 DataLoader Link。獲取遠程 Schema未提供createSchema時通過introspectSchema(linkToExecutor(link))內(nèi)省遠程 Schema提供createSchema時直接采用其返回值。應(yīng)用默認變換通過wrapSchema包裹并依次應(yīng)用StripNonQueryTransform、RenameTypes、NamespaceUnderFieldTransform三個變換。注冊三方 Schema調(diào)用addThirdPartySchema({ schema })將縫合后的 Schema 并入 Gatsby 數(shù)據(jù)層。其中三個默認變換實現(xiàn)在 transforms.jsStripNonQueryTransform剔除遠程 Schema 中的 Mutation 與 Subscription 類型mapSchema中將MapperKind.MUTATION、MapperKind.SUBSCRIPTION置為nullRenameTypes把所有類型重命名為${typeName}_${typeName}前綴形式避免與 Gatsby 內(nèi)建類型沖突NamespaceUnderFieldTransform新建名為typeName的嵌套 Query 類型并在根 Query 上掛載fieldName字段指向它字段 resolver 會調(diào)用createPageDependency建立頁面依賴。Schema 緩存默認情況下內(nèi)省得到的 Schema 會以gatsby-source-graphql-schema-${typeName}-${fieldName}為 key 緩存到.cache目錄。刷新 Schema 需要刪除緩存例如重啟gatsby develop。這正是 CHANGELOG 2.1.19 / 2.1.18 中 use embedded remote schemas嵌入遠端 Schema改動帶來的能力。若希望完全控制 Schema 來源例如讀取本地 SDL 或內(nèi)省 JSON 文件可改用createSchema回調(diào)此時 Schema不會被緩存。createSchema可返回GraphQLSchema實例或解析為該實例的 Promiseconst fs require(fs) const { buildSchema, buildClientSchema } require(graphql) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, createSchema: async () { const json JSON.parse( fs.readFileSync(${__dirname}/introspection.json) ) return buildClientSchema(json.data) }, }, }, { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, createSchema: async () { const sdl fs.readFileSync(${__dirname}/schema.sdl).toString() return buildSchema(sdl) }, }, }, ], }認證與 HTTP 細節(jié)遠程 API 通常需要認證。官方推薦用dotenv加載環(huán)境變量避免把憑證提交進版本庫再通過process.env注入配置。headers對象或異步函數(shù){ resolve: gatsby-source-graphql, options: { typeName: GitHub, fieldName: github, url: https://api.github.com/graphql, // HTTP headers headers: { Authorization: Bearer ${process.env.GITHUB_TOKEN}, }, // HTTP headers 也可以接受函數(shù)支持異步 headers: async () { return { Authorization: await getAuthorizationToken(), } }, // 傳遞給 node-fetch 的額外選項 fetchOptions: {}, }, }在 gatsby-node.js 中函數(shù)形式的headers會被await headers()展開后傳入 Link。CHANGELOG 2.1.4 曾修復(fù)過Bearer大小寫錯誤incorrect capitalization of Bearer注意使用標準寫法。fetch自定義請求函數(shù)CHANGELOG 2.1.24 新增 Allow override fetch 特性支持傳入自定義 fetch 兼容函數(shù)便于在請求發(fā)出前做簽名、注入等處理{ resolve: gatsby-source-graphql, options: { typeName: GitHub, fieldName: github, url: https://api.github.com/graphql, // 一個 fetch 兼容 API用于發(fā)起請求 fetch: (uri, options {}) fetch(uri, { ...options, headers: sign(options.headers) }), }, }內(nèi)置錯誤包裝默認fetch為 fetch.js 中的fetchWrapper基于 node-fetch。它對 HTTP 狀態(tài)碼 400的響應(yīng)拋出帶有狀態(tài)碼與狀態(tài)文本的明確錯誤Source GraphQL API: HTTP error ${status} ${statusText}對應(yīng) CHANGELOG 2.12.0 Default Apollo Link fetch wrapper to show better API errors 的改進。createLink組合 Apollo Link 實現(xiàn)生產(chǎn)級網(wǎng)絡(luò)策略網(wǎng)絡(luò)請求可能失敗、超時或返回錯誤。CHANGELOG 2.12.0 增加了 docs on how to use apollo links 文檔官方推薦使用 Apollo Link 為 GraphQL 請求疊加重試、錯誤處理、日志等能力。createLink選項接收全部插件選項pluginOptions可以返回 Promise// gatsby-config.js const { createHttpLink, from } require(apollo/client) const { RetryLink } require(apollo/client/link/retry) const retryLink new RetryLink({ delay: { initial: 100, max: 2000, jitter: true, }, attempts: { max: 5, retryIf: (error, operation) Boolean(error) ![500, 400].includes(error.statusCode), }, }) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, // pluginOptions所有插件選項 createLink: pluginOptions from([retryLink, createHttpLink({ uri: pluginOptions.url })]), }, }, ], }常用 Link 類型包括apollo/client/link/retry失敗或超時重試、apollo/client/link/error錯誤處理、apollo/client/link/httpHTTP 請求默認使用。當配置了createLink時url可省略校驗規(guī)則為二者至少其一Link 完全由你掌控。transformSchema縫合前定制遠程 SchemaCHANGELOG 2.7.0 新增transformSchema選項對應(yīng) issue 討論見 README 指引它允許在 Schema 被縫合進 Gatsby Schema 之前自定義默認的變換邏輯。transformSchema收到一個包含以下字段的對象schema內(nèi)省得到的遠程 Schemalink默認 Linkresolver默認 resolver負責建立頁面依賴defaultTransforms默認變換數(shù)組StripNonQueryTransform、RenameTypes、NamespaceUnderFieldTransformoptions全部插件選項返回值將是最終用于縫合的 Schema。下面是與默認實現(xiàn)等價的示例即不傳transformSchema時的行為const { wrapSchema } require(graphql-tools/wrap) const { linkToExecutor } require(graphql-tools/links) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, transformSchema: ({ schema, link, resolver, defaultTransforms, options, }) { return wrapSchema( { schema, executor: linkToExecutor(link), }, defaultTransforms ) }, }, }, ], }從 gatsby-node.js 源碼看當提供transformSchema時插件不再直接調(diào)用wrapSchema而是將introspectionSchema、link、resolver、defaultTransforms、options原樣傳入你的回調(diào)由你決定最終 Schema。查詢批處理與性能調(diào)優(yōu)CHANGELOG 2.3.0 引入的Query batching查詢批處理是該插件最重要的性能特性。默認情況下每個查詢獨立發(fā)送一次網(wǎng)絡(luò)請求開啟批處理后多個查詢會被合并成單個請求發(fā)送。啟用方式# 提升 Gatsby 并行執(zhí)行查詢的并發(fā)數(shù)默認 4 cross-env GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY20 gatsby developmodule.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, batch: true, }, }, ], }注意批處理只能合并大約同時開始的查詢因此理論上限是 Gatsby 并行執(zhí)行的查詢數(shù)默認 4。要獲得更高批處理收益需同時調(diào)大GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY環(huán)境變量。批大小控制批大小通過dataLoaderOptions.maxBatchSize覆蓋CHANGELOG 4.22.0 為該選項補充了配置校驗{ resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, batch: true, dataLoaderOptions: { maxBatchSize: 10, }, }, }從當前倉庫源碼 batching/dataloader-link.js 看默認的maxBatchSize會根據(jù)并發(fā)度動態(tài)推導(dǎo)Math.min(4, Math.round(concurrency / 5))concurrency來自GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY缺省為 4同時 DataLoader 默認cache: false、batchScheduleFn為 50ms 延遲收集。官方 README 建議針對具體項目調(diào)優(yōu)這兩個變量并發(fā)數(shù)與批大小并提到某些配置下觀察到 5–10 倍的加速但實際效果依項目而異。合并算法原理批處理的底層基于 DataLoader合并邏輯實現(xiàn)在 batching/merge-queries.js。以兩條查詢?yōu)槔齵 query: query(id: Int!) { node(id: $id) { foo } }, variables: { id: 1 }, }{ query: query(id: Int!) { node(id: $id) { bar } }, variables: { id: 2 }, }合并后的單條查詢?yōu)閝uery($gatsby0_id: Int!, $gatsby1_id: Int!) { gatsby0_node: node(id: $gatsby0_id) { foo } gatsby1_node: node(id: $gatsby1_id) { bar } }變量被統(tǒng)一前綴為gatsbyN_形式。合并算法依次執(zhí)行 5 步變換源碼注釋明示將頂層 fragment spread 替換為 inline fragment... on Query {}為所有頂層查詢字段含 inline fragment 內(nèi)字段添加唯一別名gatsbyN_為所有變量定義與變量使用添加前綴為含變量的 fragment 名稱及 spread添加前綴對重復(fù) fragment 去重。返回結(jié)果時resolveResult依據(jù)gatsbyN_前綴把合并結(jié)果拆分回多條獨立結(jié)果仿佛每條查詢分別執(zhí)行。對應(yīng)測試見 batching/tests/merge-queries.js覆蓋簡單查詢、帶別名查詢、模板查詢同構(gòu)不同參、帶 fragment 的模板查詢等場景。重要限制如果批中任何一條查詢返回錯誤整個批次都會失敗README 與 dataloader-link.js 中的isValidGraphQLResult校驗邏輯均說明了這一點錯誤信息會通過formatErrors聚合展示。Apollo 風格批處理備選若遠端服務(wù)支持 apollo 風格的查詢批處理也可通過createLink接入 HttpLinkDataLoader。該策略通常比查詢合并慢但錯誤報告更精確。數(shù)據(jù)刷新與 refetchInterval默認情況下gatsby-source-graphql只在服務(wù)重啟后重新拉取數(shù)據(jù)。CHANGELOG 2.0.18 修復(fù)過 fix data refetching 問題隨后 2.3.0 起支持通過refetchInterval單位秒周期刷新module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, // 刷新間隔秒 refetchInterval: 60, }, }, ], }從 gatsby-node.js 的sourceNodes實現(xiàn)看插件會創(chuàng)建一個內(nèi)部類型為GraphQLSource、ignoreType: true的節(jié)點節(jié)點 id 為createNodeId(gatsby-source-graphql-${typeName})內(nèi)容為隨機 UUID contentDigest并僅在process.env.NODE_ENV ! production即非生產(chǎn)環(huán)境下按refetchInterval周期重建該節(jié)點以觸發(fā)數(shù)據(jù)刷新。注意這一機制與頁面依賴createPageDependency配合才能驅(qū)動依賴該 Schema 的查詢重新執(zhí)行。已知限制與適用場景總結(jié)結(jié)合 README 與 CHANGELOG 4.23.0 的軟棄用標記選用本插件前需明確以下邊界不支持增量構(gòu)建Incremental Builds對內(nèi)容量大、內(nèi)容多的站點可能造成明顯構(gòu)建變慢——CHANGELOG 4.3.0 也曾專門添加警告 warn people that source-graphql is slow for larger sites不支持 CMS Preview與內(nèi)容/API 更新的實時預(yù)覽對 GraphQL 數(shù)據(jù)層支持不完整包括圖片優(yōu)化/圖片 CDN 與指令支持有現(xiàn)成 source 插件WordPress、Contentful 等時優(yōu)先使用專用插件。因此其適用場景是無現(xiàn)成 source 插件的自定義 GraphQL API、快速原型驗證PoC以及需要把遠程 GraphQL 服務(wù)以最小成本并入 Gatsby 查詢體系的項目。版本演進速覽依據(jù) CHANGELOG下表提煉 CHANGELOG 中具有實質(zhì)意義的版本節(jié)點便于選型與升級排查版本時間關(guān)鍵變更2.1.42019-08修復(fù)Bearer大小寫問題2.1.19 / 2.1.182019-12使用嵌入遠端 Schemaembedded remote schemas2.1.242019-11支持覆蓋fetch函數(shù)2.3.02020-03引入查詢批處理Query batching2.7.02020-08新增transformSchema選項2.12.02021-01默認 fetch 包裝展示更清晰的 API 錯誤補充 Apollo Link 使用文檔4.0.02021-10支持 Gatsby 4遷移默認 uuid更新至 GraphQL 164.3.02021-12使用 node-fetch 默認導(dǎo)出提示大站點下該插件較慢4.22.02022-08為dataLoaderOptions增加配置校驗4.23.02022-09標記為軟棄用soft deprecate5.0.02022-11更新 peerDeps升級至 GraphQL 165.12.02023-08更新apollo/client至 ^3.7.165.16.02026-01明確更精確的 Node.js 版本范圍當前 package.json 聲明18.0.0 26其余大量版本條目均為 Version bump only僅隨 monorepo 主版本號同步提升未引入行為變化排查時可跳過。當前倉庫中的 peerDependencies 要求gatsby: ^5.0.0-next依賴棧以apollo/client、graphql-tools/wrap、graphql-tools/links、dataloader、node-fetch為核心見 package.json。結(jié)語gatsby-source-graphql用極小的配置成本為 Gatsby 打通了任意 GraphQL 后端這條路徑從簡單的url直連、headers認證到createSchema離線 Schema、createLink自定義網(wǎng)絡(luò)棧、transformSchema深度定制再到batchdataLoaderOptions的性能調(diào)優(yōu)其能力邊界與 CHANGELOG 中逐版演進的功能一一對應(yīng)。在引入生產(chǎn)項目前務(wù)必對照官方警告評估其已知限制而在快速原型與無專用 source 插件的場景下它依然是接入遠程 GraphQL 服務(wù)最直接的選擇。贊分享前端靜態(tài)站點Web框架【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址https://gitcode.com/gh_mirrors/ga/gatsby點擊查看免費下載相關(guān)推薦Gatsby 插件 gatsby-source-graphql 實戰(zhàn)將任意第三方 GraphQL API 無縫接入 Gatsby 數(shù)據(jù)層Gatsby 插件 gatsby source graphql 實戰(zhàn)將任意第三方 GraphQL API 無縫接入 Gatsby 數(shù)據(jù)層 gatsby sou前端靜態(tài)站點Web框架Gatsby 中使用 gatsby-source-graphql 將 GraphCMS 等遠程 GraphQL API 縫合進 Gatsby 數(shù)據(jù)層Gatsby 中使用 gatsby source graphql 將 GraphCMS 等遠程 GraphQL API 縫合進 Gatsby 數(shù)據(jù)層 導(dǎo)讀 本指前端靜態(tài)站點Web框架gatsby-source-mongodb 實戰(zhàn)指南將 MongoDB 集合注入 Gatsby 并構(gòu)建 GraphQL 數(shù)據(jù)層gatsby source mongodb 實戰(zhàn)指南將 MongoDB 集合注入 Gatsby 并構(gòu)建 GraphQL 數(shù)據(jù)層 Gatsby 的數(shù)據(jù)處理層以前端靜態(tài)站點Web框架上一篇用Rust構(gòu)建操作系統(tǒng)是什么體驗octox帶你從零打造安全的Unix世界下一篇CANN SHMEM 安全加固實戰(zhàn)指南TLS 通信加密、運行權(quán)限與文件權(quán)限控制創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 gatsby-source-graphql 插件全解析：將任意第三方 GraphQL API 縫合進 Gatsby 數(shù)據(jù)層
前端靜態(tài)站點Web框架【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址https://gitcode.com/gh_mirrors/ga/gatsby點擊查看免費下載本篇技術(shù)指南以gatsby-source-graphql插件的 CHANGELOG 版本演進為主線結(jié)合 README 與倉庫源碼系統(tǒng)講解如何在 Gatsby 項目中接入任意第三方 GraphQL API涵蓋全部配置項、Schema 縫合原理、查詢批處理機制、Schema 定制與數(shù)據(jù)刷新策略。讀完本文你將掌握從零配置、認證接入到性能調(diào)優(yōu)與版本選型的完整實戰(zhàn)能力。插件定位它解決什么問題gatsby-source-graphql是一個將第三方 GraphQL API 直接接入 Gatsby GraphQL 數(shù)據(jù)層的官方插件。核心思路是遠程 Schema 通過縫合stitching技術(shù)并入 Gatsby Schema——聲明一個任意的類型名typeName包裹遠程 Schema 的 Query 類型并把遠程 Schema 掛載到 Gatsby 查詢的某個字段fieldName下之后你就可以在 Gatsby 頁面查詢里像查詢本地數(shù)據(jù)一樣查詢遠程 GraphQL 服務(wù)。從 CHANGELOG 可以看出該插件在 4.23.0 版本起被標記為soft deprecate軟棄用。官方在 README 中明確警告如果你的內(nèi)容源已有對應(yīng) source 插件如 WordPress 用gatsby-source-wordpress、Contentful 用gatsby-source-contentful不建議使用本插件因為它存在已知限制不支持增量構(gòu)建、CMS Preview、圖片優(yōu)化且對 GraphQL 數(shù)據(jù)層支持不完整。它只適合簡單概念驗證PoC以及沒有現(xiàn)成 source 插件的數(shù)據(jù)源場景。安裝與最小配置安裝命令與任何 Gatsby 插件一致npm install gatsby-source-graphql在gatsby-config.js中做最小配置只需三個核心選項url、typeName、fieldName// In your gatsby-config.js module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { // 遠程 Schema Query 類型的任意名稱 typeName: SWAPI, // 遠程 Schema 在 Gatsby 查詢中掛載的字段名查詢時直接使用 fieldName: swapi, // 遠程 GraphQL API 地址 url: https://swapi-graphql.netlify.app/.netlify/functions/index, }, }, ], }配置完成后即可在 Gatsby 頁面查詢中這樣使用fieldName即查詢?nèi)肟趝 # 這是你在配置里定義的 fieldName swapi { allSpecies { name } } }配置校驗規(guī)則源碼級從 gatsby-node.js 的pluginOptionsSchema可以看出插件的校驗約束typeName、fieldName為必填字符串必須滿足url與createLink至少提供其一Joi.object().or(url, createLink)headers允許是對象或函數(shù)fetch、createLink、createSchema、transformSchema必須是函數(shù)dataLoaderOptions會進一步校驗batch、maxBatchSize、batchScheduleFn、cache、cacheKeyFn、cacheMap含get/set/delete/clear方法等字段。對應(yīng)測試見 src/tests/gatsby-node.js缺少必填項時分別報錯typeName is required、fieldName is required、value must contain at least one of [url, createLink]。配置項全景下表匯總插件全部配置項及其作用依據(jù) README 與 gatsby-node.js配置項類型默認值說明urlstring—遠程 GraphQL 端點與createLink二選一typeNamestring必填—遠程 Schema Query 類型被包裝后的任意名稱fieldNamestring必填—遠程 Schema 在 Gatsby 查詢中掛載的根字段名headersobject | async function{}HTTP 請求頭函數(shù)形式支持異步獲取fetchfunction內(nèi)置fetchWrapper自定義 fetch 兼容函數(shù)fetchOptionsobject{}透傳給 node-fetch 的額外選項createLinkfunction—手動構(gòu)造 Apollo Link返回 Link 或 PromisecreateSchemafunction—自定義遠程 Schema 來源SDL/內(nèi)省 JSONbatchbooleanfalse是否開啟查詢批處理transformSchemafunction—在縫合前定制遠程 Schema 的變換邏輯dataLoaderOptionsobject—DataLoader 選項如maxBatchSizerefetchIntervalnumber無定時重新拉取數(shù)據(jù)的間隔秒Schema 縫合流程與緩存機制插件在createSchemaCustomization生命周期中完成遠程 Schema 的接入核心流程見 gatsby-node.js為構(gòu)建 Apollo Link若提供createLink則調(diào)用它否則用url、fetch、fetchOptions、headers構(gòu)造 HTTP Linkbatch: true時改為 DataLoader Link。獲取遠程 Schema未提供createSchema時通過introspectSchema(linkToExecutor(link))內(nèi)省遠程 Schema提供createSchema時直接采用其返回值。應(yīng)用默認變換通過wrapSchema包裹并依次應(yīng)用StripNonQueryTransform、RenameTypes、NamespaceUnderFieldTransform三個變換。注冊三方 Schema調(diào)用addThirdPartySchema({ schema })將縫合后的 Schema 并入 Gatsby 數(shù)據(jù)層。其中三個默認變換實現(xiàn)在 transforms.jsStripNonQueryTransform剔除遠程 Schema 中的 Mutation 與 Subscription 類型mapSchema中將MapperKind.MUTATION、MapperKind.SUBSCRIPTION置為nullRenameTypes把所有類型重命名為${typeName}_${typeName}前綴形式避免與 Gatsby 內(nèi)建類型沖突NamespaceUnderFieldTransform新建名為typeName的嵌套 Query 類型并在根 Query 上掛載fieldName字段指向它字段 resolver 會調(diào)用createPageDependency建立頁面依賴。Schema 緩存默認情況下內(nèi)省得到的 Schema 會以gatsby-source-graphql-schema-${typeName}-${fieldName}為 key 緩存到.cache目錄。刷新 Schema 需要刪除緩存例如重啟gatsby develop。這正是 CHANGELOG 2.1.19 / 2.1.18 中 use embedded remote schemas嵌入遠端 Schema改動帶來的能力。若希望完全控制 Schema 來源例如讀取本地 SDL 或內(nèi)省 JSON 文件可改用createSchema回調(diào)此時 Schema不會被緩存。createSchema可返回GraphQLSchema實例或解析為該實例的 Promiseconst fs require(fs) const { buildSchema, buildClientSchema } require(graphql) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, createSchema: async () { const json JSON.parse( fs.readFileSync(${__dirname}/introspection.json) ) return buildClientSchema(json.data) }, }, }, { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, createSchema: async () { const sdl fs.readFileSync(${__dirname}/schema.sdl).toString() return buildSchema(sdl) }, }, }, ], }認證與 HTTP 細節(jié)遠程 API 通常需要認證。官方推薦用dotenv加載環(huán)境變量避免把憑證提交進版本庫再通過process.env注入配置。headers對象或異步函數(shù){ resolve: gatsby-source-graphql, options: { typeName: GitHub, fieldName: github, url: https://api.github.com/graphql, // HTTP headers headers: { Authorization: Bearer ${process.env.GITHUB_TOKEN}, }, // HTTP headers 也可以接受函數(shù)支持異步 headers: async () { return { Authorization: await getAuthorizationToken(), } }, // 傳遞給 node-fetch 的額外選項 fetchOptions: {}, }, }在 gatsby-node.js 中函數(shù)形式的headers會被await headers()展開后傳入 Link。CHANGELOG 2.1.4 曾修復(fù)過Bearer大小寫錯誤incorrect capitalization of Bearer注意使用標準寫法。fetch自定義請求函數(shù)CHANGELOG 2.1.24 新增 Allow override fetch 特性支持傳入自定義 fetch 兼容函數(shù)便于在請求發(fā)出前做簽名、注入等處理{ resolve: gatsby-source-graphql, options: { typeName: GitHub, fieldName: github, url: https://api.github.com/graphql, // 一個 fetch 兼容 API用于發(fā)起請求 fetch: (uri, options {}) fetch(uri, { ...options, headers: sign(options.headers) }), }, }內(nèi)置錯誤包裝默認fetch為 fetch.js 中的fetchWrapper基于 node-fetch。它對 HTTP 狀態(tài)碼 400的響應(yīng)拋出帶有狀態(tài)碼與狀態(tài)文本的明確錯誤Source GraphQL API: HTTP error ${status} ${statusText}對應(yīng) CHANGELOG 2.12.0 Default Apollo Link fetch wrapper to show better API errors 的改進。createLink組合 Apollo Link 實現(xiàn)生產(chǎn)級網(wǎng)絡(luò)策略網(wǎng)絡(luò)請求可能失敗、超時或返回錯誤。CHANGELOG 2.12.0 增加了 docs on how to use apollo links 文檔官方推薦使用 Apollo Link 為 GraphQL 請求疊加重試、錯誤處理、日志等能力。createLink選項接收全部插件選項pluginOptions可以返回 Promise// gatsby-config.js const { createHttpLink, from } require(apollo/client) const { RetryLink } require(apollo/client/link/retry) const retryLink new RetryLink({ delay: { initial: 100, max: 2000, jitter: true, }, attempts: { max: 5, retryIf: (error, operation) Boolean(error) ![500, 400].includes(error.statusCode), }, }) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, // pluginOptions所有插件選項 createLink: pluginOptions from([retryLink, createHttpLink({ uri: pluginOptions.url })]), }, }, ], }常用 Link 類型包括apollo/client/link/retry失敗或超時重試、apollo/client/link/error錯誤處理、apollo/client/link/httpHTTP 請求默認使用。當配置了createLink時url可省略校驗規(guī)則為二者至少其一Link 完全由你掌控。transformSchema縫合前定制遠程 SchemaCHANGELOG 2.7.0 新增transformSchema選項對應(yīng) issue 討論見 README 指引它允許在 Schema 被縫合進 Gatsby Schema 之前自定義默認的變換邏輯。transformSchema收到一個包含以下字段的對象schema內(nèi)省得到的遠程 Schemalink默認 Linkresolver默認 resolver負責建立頁面依賴defaultTransforms默認變換數(shù)組StripNonQueryTransform、RenameTypes、NamespaceUnderFieldTransformoptions全部插件選項返回值將是最終用于縫合的 Schema。下面是與默認實現(xiàn)等價的示例即不傳transformSchema時的行為const { wrapSchema } require(graphql-tools/wrap) const { linkToExecutor } require(graphql-tools/links) module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, transformSchema: ({ schema, link, resolver, defaultTransforms, options, }) { return wrapSchema( { schema, executor: linkToExecutor(link), }, defaultTransforms ) }, }, }, ], }從 gatsby-node.js 源碼看當提供transformSchema時插件不再直接調(diào)用wrapSchema而是將introspectionSchema、link、resolver、defaultTransforms、options原樣傳入你的回調(diào)由你決定最終 Schema。查詢批處理與性能調(diào)優(yōu)CHANGELOG 2.3.0 引入的Query batching查詢批處理是該插件最重要的性能特性。默認情況下每個查詢獨立發(fā)送一次網(wǎng)絡(luò)請求開啟批處理后多個查詢會被合并成單個請求發(fā)送。啟用方式# 提升 Gatsby 并行執(zhí)行查詢的并發(fā)數(shù)默認 4 cross-env GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY20 gatsby developmodule.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, batch: true, }, }, ], }注意批處理只能合并大約同時開始的查詢因此理論上限是 Gatsby 并行執(zhí)行的查詢數(shù)默認 4。要獲得更高批處理收益需同時調(diào)大GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY環(huán)境變量。批大小控制批大小通過dataLoaderOptions.maxBatchSize覆蓋CHANGELOG 4.22.0 為該選項補充了配置校驗{ resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, batch: true, dataLoaderOptions: { maxBatchSize: 10, }, }, }從當前倉庫源碼 batching/dataloader-link.js 看默認的maxBatchSize會根據(jù)并發(fā)度動態(tài)推導(dǎo)Math.min(4, Math.round(concurrency / 5))concurrency來自GATSBY_EXPERIMENTAL_QUERY_CONCURRENCY缺省為 4同時 DataLoader 默認cache: false、batchScheduleFn為 50ms 延遲收集。官方 README 建議針對具體項目調(diào)優(yōu)這兩個變量并發(fā)數(shù)與批大小并提到某些配置下觀察到 5–10 倍的加速但實際效果依項目而異。合并算法原理批處理的底層基于 DataLoader合并邏輯實現(xiàn)在 batching/merge-queries.js。以兩條查詢?yōu)槔齵 query: query(id: Int!) { node(id: $id) { foo } }, variables: { id: 1 }, }{ query: query(id: Int!) { node(id: $id) { bar } }, variables: { id: 2 }, }合并后的單條查詢?yōu)閝uery($gatsby0_id: Int!, $gatsby1_id: Int!) { gatsby0_node: node(id: $gatsby0_id) { foo } gatsby1_node: node(id: $gatsby1_id) { bar } }變量被統(tǒng)一前綴為gatsbyN_形式。合并算法依次執(zhí)行 5 步變換源碼注釋明示將頂層 fragment spread 替換為 inline fragment... on Query {}為所有頂層查詢字段含 inline fragment 內(nèi)字段添加唯一別名gatsbyN_為所有變量定義與變量使用添加前綴為含變量的 fragment 名稱及 spread添加前綴對重復(fù) fragment 去重。返回結(jié)果時resolveResult依據(jù)gatsbyN_前綴把合并結(jié)果拆分回多條獨立結(jié)果仿佛每條查詢分別執(zhí)行。對應(yīng)測試見 batching/tests/merge-queries.js覆蓋簡單查詢、帶別名查詢、模板查詢同構(gòu)不同參、帶 fragment 的模板查詢等場景。重要限制如果批中任何一條查詢返回錯誤整個批次都會失敗README 與 dataloader-link.js 中的isValidGraphQLResult校驗邏輯均說明了這一點錯誤信息會通過formatErrors聚合展示。Apollo 風格批處理備選若遠端服務(wù)支持 apollo 風格的查詢批處理也可通過createLink接入 HttpLinkDataLoader。該策略通常比查詢合并慢但錯誤報告更精確。數(shù)據(jù)刷新與 refetchInterval默認情況下gatsby-source-graphql只在服務(wù)重啟后重新拉取數(shù)據(jù)。CHANGELOG 2.0.18 修復(fù)過 fix data refetching 問題隨后 2.3.0 起支持通過refetchInterval單位秒周期刷新module.exports { plugins: [ { resolve: gatsby-source-graphql, options: { typeName: SWAPI, fieldName: swapi, url: https://api.graphcms.com/simple/v1/swapi, // 刷新間隔秒 refetchInterval: 60, }, }, ], }從 gatsby-node.js 的sourceNodes實現(xiàn)看插件會創(chuàng)建一個內(nèi)部類型為GraphQLSource、ignoreType: true的節(jié)點節(jié)點 id 為createNodeId(gatsby-source-graphql-${typeName})內(nèi)容為隨機 UUID contentDigest并僅在process.env.NODE_ENV ! production即非生產(chǎn)環(huán)境下按refetchInterval周期重建該節(jié)點以觸發(fā)數(shù)據(jù)刷新。注意這一機制與頁面依賴createPageDependency配合才能驅(qū)動依賴該 Schema 的查詢重新執(zhí)行。已知限制與適用場景總結(jié)結(jié)合 README 與 CHANGELOG 4.23.0 的軟棄用標記選用本插件前需明確以下邊界不支持增量構(gòu)建Incremental Builds對內(nèi)容量大、內(nèi)容多的站點可能造成明顯構(gòu)建變慢——CHANGELOG 4.3.0 也曾專門添加警告 warn people that source-graphql is slow for larger sites不支持 CMS Preview與內(nèi)容/API 更新的實時預(yù)覽對 GraphQL 數(shù)據(jù)層支持不完整包括圖片優(yōu)化/圖片 CDN 與指令支持有現(xiàn)成 source 插件WordPress、Contentful 等時優(yōu)先使用專用插件。因此其適用場景是無現(xiàn)成 source 插件的自定義 GraphQL API、快速原型驗證PoC以及需要把遠程 GraphQL 服務(wù)以最小成本并入 Gatsby 查詢體系的項目。版本演進速覽依據(jù) CHANGELOG下表提煉 CHANGELOG 中具有實質(zhì)意義的版本節(jié)點便于選型與升級排查版本時間關(guān)鍵變更2.1.42019-08修復(fù)Bearer大小寫問題2.1.19 / 2.1.182019-12使用嵌入遠端 Schemaembedded remote schemas2.1.242019-11支持覆蓋fetch函數(shù)2.3.02020-03引入查詢批處理Query batching2.7.02020-08新增transformSchema選項2.12.02021-01默認 fetch 包裝展示更清晰的 API 錯誤補充 Apollo Link 使用文檔4.0.02021-10支持 Gatsby 4遷移默認 uuid更新至 GraphQL 164.3.02021-12使用 node-fetch 默認導(dǎo)出提示大站點下該插件較慢4.22.02022-08為dataLoaderOptions增加配置校驗4.23.02022-09標記為軟棄用soft deprecate5.0.02022-11更新 peerDeps升級至 GraphQL 165.12.02023-08更新apollo/client至 ^3.7.165.16.02026-01明確更精確的 Node.js 版本范圍當前 package.json 聲明18.0.0 26其余大量版本條目均為 Version bump only僅隨 monorepo 主版本號同步提升未引入行為變化排查時可跳過。當前倉庫中的 peerDependencies 要求gatsby: ^5.0.0-next依賴棧以apollo/client、graphql-tools/wrap、graphql-tools/links、dataloader、node-fetch為核心見 package.json。結(jié)語gatsby-source-graphql用極小的配置成本為 Gatsby 打通了任意 GraphQL 后端這條路徑從簡單的url直連、headers認證到createSchema離線 Schema、createLink自定義網(wǎng)絡(luò)棧、transformSchema深度定制再到batchdataLoaderOptions的性能調(diào)優(yōu)其能力邊界與 CHANGELOG 中逐版演進的功能一一對應(yīng)。在引入生產(chǎn)項目前務(wù)必對照官方警告評估其已知限制而在快速原型與無專用 source 插件的場景下它依然是接入遠程 GraphQL 服務(wù)最直接的選擇。贊分享前端靜態(tài)站點Web框架【免費下載鏈接】gatsbyReact-based framework with performance, scalability, and security built in.項目地址https://gitcode.com/gh_mirrors/ga/gatsby點擊查看免費下載相關(guān)推薦Gatsby 插件 gatsby-source-graphql 實戰(zhàn)將任意第三方 GraphQL API 無縫接入 Gatsby 數(shù)據(jù)層Gatsby 插件 gatsby source graphql 實戰(zhàn)將任意第三方 GraphQL API 無縫接入 Gatsby 數(shù)據(jù)層 gatsby sou前端靜態(tài)站點Web框架Gatsby 中使用 gatsby-source-graphql 將 GraphCMS 等遠程 GraphQL API 縫合進 Gatsby 數(shù)據(jù)層Gatsby 中使用 gatsby source graphql 將 GraphCMS 等遠程 GraphQL API 縫合進 Gatsby 數(shù)據(jù)層 導(dǎo)讀 本指前端靜態(tài)站點Web框架gatsby-source-mongodb 實戰(zhàn)指南將 MongoDB 集合注入 Gatsby 并構(gòu)建 GraphQL 數(shù)據(jù)層gatsby source mongodb 實戰(zhàn)指南將 MongoDB 集合注入 Gatsby 并構(gòu)建 GraphQL 數(shù)據(jù)層 Gatsby 的數(shù)據(jù)處理層以前端靜態(tài)站點Web框架上一篇用Rust構(gòu)建操作系統(tǒng)是什么體驗octox帶你從零打造安全的Unix世界下一篇CANN SHMEM 安全加固實戰(zhàn)指南TLS 通信加密、運行權(quán)限與文件權(quán)限控制創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考