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