Corsair 集成 Contentful GraphQL从插件安装到查询执行的完整实战指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本指南以corsair-dev/contentfulgraphql插件为核心讲解如何通过 Corsair 以统一的类型安全 API 访问 Contentful GraphQL Content API。读者将掌握插件安装与注册、API Key 认证、三个核心操作获取 CMA Token、普通 GraphQL 查询、自动持久化查询的调用方式与参数细节并通过源码级解析理解底层请求链路、限流与错误处理机制。插件概述Contentful 是一个以内容建模、内容交付与全渠道发布为核心的无头 CMSHeadless CMS其 GraphQL Content API 允许开发者以 GraphQL 方式拉取空间Space与环境Environment中的内容。Corsair 通过corsair-dev/contentfulgraphql插件将这一能力封装为类型安全的客户端操作让应用可以用“一个客户端、一组类型化 API 调用”的方式访问 Contentful而无需关心认证、路径拼接与请求细节。从插件声明packages/contentfulgraphql/index.ts可以看到该插件插件 ID 为contentfulgraphql默认认证方式为api_key暴露 3 个类型化 API 操作全部标记为read风险级别不注册任何 Webhook使用 Zod schema基于corsair/core的类型系统校验输入与输出。安装与注册安装插件包在已初始化 Corsair 的项目中通过包管理器安装插件pnpm add corsair-dev/contentfulgraphql包声明packages/contentfulgraphql/package.json显示其 peer 依赖为corsair 0.1.0与zod ^4.1.13插件通过corsair/core的类型与运行时设施实现。npm 用户可执行npm install corsair corsair-dev/contentfulgraphqlyarn/bun 用户同理只需将对应包管理器换成yarn add或bun add。在 Corsair 实例中注册插件将插件加入createCorsair的plugins数组即可完成注册import Database from better-sqlite3; import { createCorsair } from corsair; import { contentfulgraphql } from corsair-dev/contentfulgraphql; export const corsair createCorsair({ plugins: [ contentfulgraphql(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });其中kekKey Encryption Key与hub配置项projectApiKey、signingSecret的具体获取方式参见 快速开始。多租户是默认行为插件工厂返回的实例以租户维度隔离数据业务代码中通过corsair.withTenant(id)圈定当前租户隔离机制详见 多租户。从源码看packages/contentfulgraphql/index.tscontentfulgraphql()工厂函数支持以下可选参数authType认证方式默认api_keykey直接提供 API Key用于绕开凭据存储层仅端点调用来源时生效hooks生命周期钩子errorHandlers自定义错误处理器会与内置errorHandlers合并permissions基于端点嵌套结构的权限配置。连接租户应用需要为用户租户建立 Contentful 凭据连接。通过corsair.manage.connect.createLink铸造一个 Connect 链接并引导用户浏览器访问Hub 承载该页面并把连接结果回传给应用流程详见 Connect / OAuthconst { connectUrl } await corsair.manage.connect.createLink({ plugin: contentfulgraphql, tenantId: acme, }); // redirect the users browser to connectUrl认证方式API Key插件认证采用API Key方式。在租户首次发起请求时Corsair 会提示该租户提供 API Key无需在注册阶段预先配置。认证配置在源码中被声明为packages/contentfulgraphql/index.tsexport const contentfulGraphqlAuthConfig { api_key: { account: [space_id, environment_id] as const, }, } as const satisfies PluginAuthConfig;这意味着每个租户账户下保存的凭据字段为space_idContentful Space ID必填environment_idContentful Environment ID可选缺省时指向 Space 的默认环境。keyBuilder在端点调用时先从租户密钥存储中读取api_key若缺失则抛出AuthMissingErrorpackages/contentfulgraphql/index.ts。API Key 认证的通用机制可参考 API Key 概念。核心操作Endpoints插件共暴露 3 个操作对应关系如下与 README 及 API 参考 一致OperationOperation IDRisk描述getCmaTokencontentfulgraphql.api.getCmaTokenread获取已存储的 Contentful access token、space ID 与 environment IDgraphQlContentApiPersistedQuerycontentfulgraphql.api.graphQlContentApiPersistedQueryread使用 SHA-256 哈希对 Contentful GraphQL Content API 执行自动持久化查询APQgraphQlContentApiQuerycontentfulgraphql.api.graphQlContentApiQueryread针对配置的 space 与 environment 执行 GraphQL 查询所有操作的风险级别均为read只读端点元数据定义在 packages/contentfulgraphql/index.ts。调用方式统一为const tenant corsair.withTenant(acme); await tenant.contentfulgraphql.api.operation(input);getCmaToken读取租户凭据信息Operation IDcontentfulgraphql.api.getCmaToken该操作返回当前租户账户下存储的 Contentful 凭据信息用于确认连接状态与目标空间。await tenant.contentfulgraphql.api.getCmaToken({});输入空对象z.object({})见 packages/contentfulgraphql/endpoints/types.ts。输出名称类型必填描述space_idstring是Contentful Space IDenvironment_idstring否Contentful Environment ID未配置时省略底层实现packages/contentfulgraphql/endpoints/get-cma-token.ts并行读取ctx.keys.get_space_id()与ctx.keys.get_environment_id()environment 缺失时输出对象不含该字段并记录一条contentfulgraphql.getCmaToken完成事件日志。graphQlContentApiQuery常规 GraphQL 查询Operation IDcontentfulgraphql.api.graphQlContentApiQuery针对当前租户配置的 space 与 environment 执行 GraphQL 查询。await tenant.contentfulgraphql.api.graphQlContentApiQuery({ query: query GetPosts($limit: Int!) { postCollection(limit: $limit) { items { title } } } , variables: { limit: 10 }, operationName: GetPosts, });输入schema 见 packages/contentfulgraphql/endpoints/types.ts名称类型必填描述querystring是GraphQL 查询文本最小长度 1variablesobject否查询变量Recordstring, unknownoperationNamestring否操作名称查询包含多个操作时用于区分输出{ data: object }其中data为任意结构的 GraphQL 响应数据Recordstring, unknown。实现细节packages/contentfulgraphql/endpoints/graph-ql-content-api-query.ts端点先校验space_id已配置随后基于 space/environment 拼接请求路径向https://graphql.contentful.com发送POST请求请求体携带query、可选的variables与operationName并在完成后记录事件日志。graphQlContentApiPersistedQuery自动持久化查询APQOperation IDcontentfulgraphql.api.graphQlContentApiPersistedQuery自动持久化查询Automatic Persisted Query是 Contentful 支持的一种优化协议客户端先用查询文本的 SHA-256 哈希发起请求若服务端已注册该查询则直接返回结果省去每次传输完整查询文本的开销若服务端返回PersistedQueryNotFound客户端再携带完整查询文本重新请求完成注册。await tenant.contentfulgraphql.api.graphQlContentApiPersistedQuery({ sha256Hash: 9b1a…64 位十六进制 SHA-256, variables: { limit: 10 }, operationName: GetPosts, });输入schema 见 packages/contentfulgraphql/endpoints/types.ts名称类型必填描述querystring否GraphQL 查询文本与sha256Hash至少提供一个sha256Hashstring否查询文本的 SHA-256 哈希variablesobject否查询变量operationNamestring否操作名称输出{ data: object }与普通查询一致。两个关键源码事实值得注意哈希可自动推导端点实现packages/contentfulgraphql/endpoints/graph-ql-content-api-persisted-query.ts在未提供sha256Hash时会用sha256(input.query)自动计算哈希若两者都缺失则抛出Either query or sha256Hash must be provided。APQ 握手协议请求构造器packages/contentfulgraphql/client.ts先发送仅含哈希的请求体extensions.persistedQuery { version: 1, sha256Hash }若捕获到PERSISTED_QUERY_NOT_FOUND/PersistedQueryNotFound错误判定函数见 packages/contentfulgraphql/client.ts且提供了query则自动重发带完整查询文本的请求完成注册。sha256使用 Node 内置crypto.createHash实现packages/contentfulgraphql/client.ts。底层请求链路路径、限流与错误处理请求路径与地址客户端packages/contentfulgraphql/client.ts中固定 API 基址为https://graphql.contentful.com路径构建规则为/content/v1/spaces/{spaceId} /content/v1/spaces/{spaceId}/environments/{environmentId} // 配置了 environment 时buildContentfulGraphqlPath对 space 与 environment 均做encodeURIComponent编码packages/contentfulgraphql/client.ts请求统一使用POST、application/json; charsetutf-8并携带Authorization: Bearer apiKey头。限流与重试请求层内置 Contentful 限流适配packages/contentfulgraphql/client.ts配置项值enabledtruemaxRetries3initialRetryDelay1000msbackoffMultiplier2retryAfter头名X-Contentful-RateLimit-Reset即遇到限流时最多重试 3 次首次退避 1 秒之后按 2 倍指数增长并参考 Contentful 返回的X-Contentful-RateLimit-Reset头决定重试时机。错误处理makeContentfulGraphqlRequestpackages/contentfulgraphql/client.ts的错误归一逻辑GraphQL 响应体含errors时抛出携带extensions.code的ContentfulGraphqlAPIError响应缺少data时抛出No data returned from Contentful GraphQL API底层ApiError会被包装为ContentfulGraphqlAPIError并保留status、statusText、body含 GraphQL 校验错误详情与retryAfter字段。插件同时导出一套内置错误处理器且支持通过工厂函数errorHandlers选项覆盖或合并packages/contentfulgraphql/index.ts。通用错误处理范式可参考 错误处理。Webhooks 与本地数据库Webhooks插件不注册任何 Webhookwebhooks: {}且pluginWebhookMatcher恒返回false见 packages/contentfulgraphql/index.ts。README 中同样标注 “No webhooks”因此无需配置接收事件推送的 URL。本地数据库该插件是只读的 GraphQL 查询集成不定义任何数据库实体packages/contentfulgraphql/schema/database.ts 中仅有说明性注释未来若需缓存查询结果等持久化能力可在此添加 Zod 实体 schema。因此本插件不使用corsair.contentfulgraphql.db.entity.search(...)形式的本地同步查询对本地数据同步有需求的场景请参考 数据库操作 与 集成同步。测试与验证插件自带单元测试packages/contentfulgraphql/api.test.ts、packages/contentfulgraphql/schema.test.ts覆盖端点输入/输出 schema 校验逻辑。可在包目录下运行pnpm --filter corsair-dev/contentfulgraphql test以验证 schema 的必填约束如graphQlContentApiQuery的query最小长度 1、graphQlContentApiPersistedQuery的query/sha256Hash二选一 refine 规则均符合预期。结语corsair-dev/contentfulgraphql以极小的接入成本一个插件、一次注册、租户首次使用提示 API Key把 Contentful GraphQL Content API 的三种核心能力带进 Corsair凭据读取、常规查询与自动持久化查询。结合 API 参考 中完整的输入/输出类型与上文源码级剖析开发者可以放心地将该插件接入自己的 Agent 工作流并通过 MCP 适配层将contentfulgraphql.api.*操作暴露为 Agent 工具参见 MCP 适配器。插件遵循 Apache-2.0 开源协议发布。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Corsair 集成 Contentful GraphQL：从插件安装到查询执行的完整实战指南
Corsair 集成 Contentful GraphQL从插件安装到查询执行的完整实战指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本指南以corsair-dev/contentfulgraphql插件为核心讲解如何通过 Corsair 以统一的类型安全 API 访问 Contentful GraphQL Content API。读者将掌握插件安装与注册、API Key 认证、三个核心操作获取 CMA Token、普通 GraphQL 查询、自动持久化查询的调用方式与参数细节并通过源码级解析理解底层请求链路、限流与错误处理机制。插件概述Contentful 是一个以内容建模、内容交付与全渠道发布为核心的无头 CMSHeadless CMS其 GraphQL Content API 允许开发者以 GraphQL 方式拉取空间Space与环境Environment中的内容。Corsair 通过corsair-dev/contentfulgraphql插件将这一能力封装为类型安全的客户端操作让应用可以用“一个客户端、一组类型化 API 调用”的方式访问 Contentful而无需关心认证、路径拼接与请求细节。从插件声明packages/contentfulgraphql/index.ts可以看到该插件插件 ID 为contentfulgraphql默认认证方式为api_key暴露 3 个类型化 API 操作全部标记为read风险级别不注册任何 Webhook使用 Zod schema基于corsair/core的类型系统校验输入与输出。安装与注册安装插件包在已初始化 Corsair 的项目中通过包管理器安装插件pnpm add corsair-dev/contentfulgraphql包声明packages/contentfulgraphql/package.json显示其 peer 依赖为corsair 0.1.0与zod ^4.1.13插件通过corsair/core的类型与运行时设施实现。npm 用户可执行npm install corsair corsair-dev/contentfulgraphqlyarn/bun 用户同理只需将对应包管理器换成yarn add或bun add。在 Corsair 实例中注册插件将插件加入createCorsair的plugins数组即可完成注册import Database from better-sqlite3; import { createCorsair } from corsair; import { contentfulgraphql } from corsair-dev/contentfulgraphql; export const corsair createCorsair({ plugins: [ contentfulgraphql(), ], database: new Database(corsair.db), kek: process.env.CORSAIR_KEK!, hub: { projectApiKey: process.env.CORSAIR_API_KEY!, signingSecret: process.env.CORSAIR_SIGNING_SECRET!, }, });其中kekKey Encryption Key与hub配置项projectApiKey、signingSecret的具体获取方式参见 快速开始。多租户是默认行为插件工厂返回的实例以租户维度隔离数据业务代码中通过corsair.withTenant(id)圈定当前租户隔离机制详见 多租户。从源码看packages/contentfulgraphql/index.tscontentfulgraphql()工厂函数支持以下可选参数authType认证方式默认api_keykey直接提供 API Key用于绕开凭据存储层仅端点调用来源时生效hooks生命周期钩子errorHandlers自定义错误处理器会与内置errorHandlers合并permissions基于端点嵌套结构的权限配置。连接租户应用需要为用户租户建立 Contentful 凭据连接。通过corsair.manage.connect.createLink铸造一个 Connect 链接并引导用户浏览器访问Hub 承载该页面并把连接结果回传给应用流程详见 Connect / OAuthconst { connectUrl } await corsair.manage.connect.createLink({ plugin: contentfulgraphql, tenantId: acme, }); // redirect the users browser to connectUrl认证方式API Key插件认证采用API Key方式。在租户首次发起请求时Corsair 会提示该租户提供 API Key无需在注册阶段预先配置。认证配置在源码中被声明为packages/contentfulgraphql/index.tsexport const contentfulGraphqlAuthConfig { api_key: { account: [space_id, environment_id] as const, }, } as const satisfies PluginAuthConfig;这意味着每个租户账户下保存的凭据字段为space_idContentful Space ID必填environment_idContentful Environment ID可选缺省时指向 Space 的默认环境。keyBuilder在端点调用时先从租户密钥存储中读取api_key若缺失则抛出AuthMissingErrorpackages/contentfulgraphql/index.ts。API Key 认证的通用机制可参考 API Key 概念。核心操作Endpoints插件共暴露 3 个操作对应关系如下与 README 及 API 参考 一致OperationOperation IDRisk描述getCmaTokencontentfulgraphql.api.getCmaTokenread获取已存储的 Contentful access token、space ID 与 environment IDgraphQlContentApiPersistedQuerycontentfulgraphql.api.graphQlContentApiPersistedQueryread使用 SHA-256 哈希对 Contentful GraphQL Content API 执行自动持久化查询APQgraphQlContentApiQuerycontentfulgraphql.api.graphQlContentApiQueryread针对配置的 space 与 environment 执行 GraphQL 查询所有操作的风险级别均为read只读端点元数据定义在 packages/contentfulgraphql/index.ts。调用方式统一为const tenant corsair.withTenant(acme); await tenant.contentfulgraphql.api.operation(input);getCmaToken读取租户凭据信息Operation IDcontentfulgraphql.api.getCmaToken该操作返回当前租户账户下存储的 Contentful 凭据信息用于确认连接状态与目标空间。await tenant.contentfulgraphql.api.getCmaToken({});输入空对象z.object({})见 packages/contentfulgraphql/endpoints/types.ts。输出名称类型必填描述space_idstring是Contentful Space IDenvironment_idstring否Contentful Environment ID未配置时省略底层实现packages/contentfulgraphql/endpoints/get-cma-token.ts并行读取ctx.keys.get_space_id()与ctx.keys.get_environment_id()environment 缺失时输出对象不含该字段并记录一条contentfulgraphql.getCmaToken完成事件日志。graphQlContentApiQuery常规 GraphQL 查询Operation IDcontentfulgraphql.api.graphQlContentApiQuery针对当前租户配置的 space 与 environment 执行 GraphQL 查询。await tenant.contentfulgraphql.api.graphQlContentApiQuery({ query: query GetPosts($limit: Int!) { postCollection(limit: $limit) { items { title } } } , variables: { limit: 10 }, operationName: GetPosts, });输入schema 见 packages/contentfulgraphql/endpoints/types.ts名称类型必填描述querystring是GraphQL 查询文本最小长度 1variablesobject否查询变量Recordstring, unknownoperationNamestring否操作名称查询包含多个操作时用于区分输出{ data: object }其中data为任意结构的 GraphQL 响应数据Recordstring, unknown。实现细节packages/contentfulgraphql/endpoints/graph-ql-content-api-query.ts端点先校验space_id已配置随后基于 space/environment 拼接请求路径向https://graphql.contentful.com发送POST请求请求体携带query、可选的variables与operationName并在完成后记录事件日志。graphQlContentApiPersistedQuery自动持久化查询APQOperation IDcontentfulgraphql.api.graphQlContentApiPersistedQuery自动持久化查询Automatic Persisted Query是 Contentful 支持的一种优化协议客户端先用查询文本的 SHA-256 哈希发起请求若服务端已注册该查询则直接返回结果省去每次传输完整查询文本的开销若服务端返回PersistedQueryNotFound客户端再携带完整查询文本重新请求完成注册。await tenant.contentfulgraphql.api.graphQlContentApiPersistedQuery({ sha256Hash: 9b1a…64 位十六进制 SHA-256, variables: { limit: 10 }, operationName: GetPosts, });输入schema 见 packages/contentfulgraphql/endpoints/types.ts名称类型必填描述querystring否GraphQL 查询文本与sha256Hash至少提供一个sha256Hashstring否查询文本的 SHA-256 哈希variablesobject否查询变量operationNamestring否操作名称输出{ data: object }与普通查询一致。两个关键源码事实值得注意哈希可自动推导端点实现packages/contentfulgraphql/endpoints/graph-ql-content-api-persisted-query.ts在未提供sha256Hash时会用sha256(input.query)自动计算哈希若两者都缺失则抛出Either query or sha256Hash must be provided。APQ 握手协议请求构造器packages/contentfulgraphql/client.ts先发送仅含哈希的请求体extensions.persistedQuery { version: 1, sha256Hash }若捕获到PERSISTED_QUERY_NOT_FOUND/PersistedQueryNotFound错误判定函数见 packages/contentfulgraphql/client.ts且提供了query则自动重发带完整查询文本的请求完成注册。sha256使用 Node 内置crypto.createHash实现packages/contentfulgraphql/client.ts。底层请求链路路径、限流与错误处理请求路径与地址客户端packages/contentfulgraphql/client.ts中固定 API 基址为https://graphql.contentful.com路径构建规则为/content/v1/spaces/{spaceId} /content/v1/spaces/{spaceId}/environments/{environmentId} // 配置了 environment 时buildContentfulGraphqlPath对 space 与 environment 均做encodeURIComponent编码packages/contentfulgraphql/client.ts请求统一使用POST、application/json; charsetutf-8并携带Authorization: Bearer apiKey头。限流与重试请求层内置 Contentful 限流适配packages/contentfulgraphql/client.ts配置项值enabledtruemaxRetries3initialRetryDelay1000msbackoffMultiplier2retryAfter头名X-Contentful-RateLimit-Reset即遇到限流时最多重试 3 次首次退避 1 秒之后按 2 倍指数增长并参考 Contentful 返回的X-Contentful-RateLimit-Reset头决定重试时机。错误处理makeContentfulGraphqlRequestpackages/contentfulgraphql/client.ts的错误归一逻辑GraphQL 响应体含errors时抛出携带extensions.code的ContentfulGraphqlAPIError响应缺少data时抛出No data returned from Contentful GraphQL API底层ApiError会被包装为ContentfulGraphqlAPIError并保留status、statusText、body含 GraphQL 校验错误详情与retryAfter字段。插件同时导出一套内置错误处理器且支持通过工厂函数errorHandlers选项覆盖或合并packages/contentfulgraphql/index.ts。通用错误处理范式可参考 错误处理。Webhooks 与本地数据库Webhooks插件不注册任何 Webhookwebhooks: {}且pluginWebhookMatcher恒返回false见 packages/contentfulgraphql/index.ts。README 中同样标注 “No webhooks”因此无需配置接收事件推送的 URL。本地数据库该插件是只读的 GraphQL 查询集成不定义任何数据库实体packages/contentfulgraphql/schema/database.ts 中仅有说明性注释未来若需缓存查询结果等持久化能力可在此添加 Zod 实体 schema。因此本插件不使用corsair.contentfulgraphql.db.entity.search(...)形式的本地同步查询对本地数据同步有需求的场景请参考 数据库操作 与 集成同步。测试与验证插件自带单元测试packages/contentfulgraphql/api.test.ts、packages/contentfulgraphql/schema.test.ts覆盖端点输入/输出 schema 校验逻辑。可在包目录下运行pnpm --filter corsair-dev/contentfulgraphql test以验证 schema 的必填约束如graphQlContentApiQuery的query最小长度 1、graphQlContentApiPersistedQuery的query/sha256Hash二选一 refine 规则均符合预期。结语corsair-dev/contentfulgraphql以极小的接入成本一个插件、一次注册、租户首次使用提示 API Key把 Contentful GraphQL Content API 的三种核心能力带进 Corsair凭据读取、常规查询与自动持久化查询。结合 API 参考 中完整的输入/输出类型与上文源码级剖析开发者可以放心地将该插件接入自己的 Agent 工作流并通过 MCP 适配层将contentfulgraphql.api.*操作暴露为 Agent 工具参见 MCP 适配器。插件遵循 Apache-2.0 开源协议发布。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考