用途
该技能用于在 Adobe Commerce 应用前方接入 API Mesh:把 Commerce 自带的 GraphQL API 与本应用的运行时动作组合成一个 Mesh schema。它主要处理两件事:将运行时动作暴露为 Mesh 数据源,以及在既有 Commerce 类型上扩展由该数据源解析的新字段。
技能假定使用者已掌握 API Mesh 的通用知识(mesh.json 结构、handler 类型、transforms、hooks、secrets、CORS、声明式与编程式 resolver)。若不熟悉,应先阅读 Adobe 官方资料(见 References)再继续。官方资料未覆盖的是:通过 additionalResolvers(targetTypeName/sourceTypeName/requiredSelectionSet/sourceSelectionSet)扩展既有 Commerce 类型,以及将 aio-commerce-sdk 运行时动作包装为 Mesh 数据源。
前提条件
- 已安装 @adobe/aio-cli-plugin-api-mesh。
- 若要把运行时动作暴露为数据源,该动作需已构建部署,并具有真实可访问的 HTTPS 端点——指向未部署动作的数据源会以不明确的方式失败。
- 检查当前工作区是否已有 Mesh:运行 aio api-mesh:get。返回 "No mesh found" 则新建,否则是在编辑已有 mesh.json 并做更新。
主要步骤
步骤一:通过 introspection 确认 schema 结构
在编写 additionalTypeDefs 或 additionalResolvers 之前,先对要扩展的 Commerce(或其他)GraphQL 数据源做 introspection。不要凭记忆或相似命名约定假设类型/字段名——近似但不匹配的名称会让 Mesh 构建成功,但 resolver 永不触发。
示例命令: curl -s -X POST "<graphql-endpoint>" -H "Content-Type: application/json" -d '{"query":"{ __type(name: "<TargetType>") { fields { name } } }"}'
步骤二:搭建数据源
GraphQL 数据源示例: { "name": "Commerce", "handler": { "graphql": { "endpoint": "<commerce-graphql-endpoint>", "operationHeaders": { "Authorization": "{context.headers.authorization}" } } } }
对于包含 customer、cart 或 session 作用域字段的数据源,默认应包含 operationHeaders——API Mesh 不会自动转发调用方的 Authorization 头。省略它会导致所有需认证的查询失败,返回后端通用的 "not authorized" 错误,与无效 token 难以区分。
包装运行时动作时,编写一份仅描述其端点的小型静态 OpenAPI 文档,并用相对路径引用: { "name": "<SourceName>", "handler": { "openapi": { "source": "./mesh/<source>.json" } } }
OpenAPI 文档本身需要有足够的结构,让 Mesh 能从中生成 Query 字段。单端点运行时动作的最小示例如原文所示(包含 openapi 版本、info、servers、paths,其中 operationId 即 Query 字段名)。
operationId 会成为 Query 字段名——它必须与步骤三 resolver 中的 sourceFieldName 完全一致,否则 resolver 构建成功但永不触发。声明的响应 schema 必须与实际返回一致——Mesh 按声明解析,不会重塑数据。
步骤三:扩展类型并接线 resolver
additionalTypeDefs 与 additionalResolvers 的字段结构如原文所示,包括 targetTypeName、targetFieldName、sourceName、sourceTypeName、sourceFieldName、requiredSelectionSet、sourceArgs、sourceSelectionSet、result。
当从返回对象的数据源字段提取标量时,务必同时使用 sourceSelectionSet 与 result,不要只用 result。仅使用 result 会手工构建选择集而非经由 GraphQL 解析器,会在目标字段解析发生在列表内(如父级的 items[].<newField>)时报错 "No type was found for field node ... __typename"。直接对同一数据源字段发起根查询即使存在该缺陷也会成功,因此单靠该测试不足以证明 resolver 有效。
步骤四:部署与验证
若已知浏览器应用会调用该 Mesh,应在首次部署前就决定 responseConfig.CORS,避免二次部署。
responseConfig.CORS 至少有 origin 与 allowedHeaders 两个独立维度,二者都需正确;origin 正确不代表 allowedHeaders 完整。不要凭猜测或复制示例中的 ["Content-Type", "Authorization"] 来决定 allowedHeaders:应先阅读消费端 storefront 自身的配置,将所有实际指向该端点的 GraphQL 客户端发送的自定义头全部加入允许列表。在基于 aem-boilerplate-commerce 的 AEM/EDS storefront 中,头集合按 fetch 客户端在 config.json 的 headers 块中分作用域(如 headers.all 对应核心 commerce 客户端,headers.cs 对应单独的 Catalog Service 客户端)——应检查与要改为指向本 Mesh 的客户端相对应的作用域,而非文件中所有作用域。逐个从实时 CORS 错误中添加被拒头是多次往返的陷阱,每次修复只暴露下一个缺失头。
在扩大 allowedHeaders 加入 Store 等头之前,先检查它是否冗余:若 graphql 数据源已通过 operationHeaders 硬编码了等价值(如 "Store": "default"),Mesh 无需客户端发送该头,更精简的做法是从 storefront 的出站请求配置中移除该头,而非通过 CORS 暴露它。在某些 CORS 中间件中,完全省略 allowedHeaders 也是有效选项(头从请求中反射而非允许列表)——应查当前 handler 文档而非假定必须显式列出。
会话中首次调用 aio api-mesh:* 会打开交互式浏览器登录(Waiting for browser login...)。无浏览器访问权限的 agent 无法自行完成——应将打印出的登录 URI 交给人工并等待。
命令: aio api-mesh:create mesh.json -c # 首次 aio api-mesh:update mesh.json -c # 后续编辑
-c/--autoConfirmAction 会跳过交互式 "Are you sure you want to update the mesh: <id>?" 提示。该提示是变更他人或系统可能已依赖的 Mesh 前唯一的检查点——仅在你自己刚创建的工作区级 Mesh(如 CI 或一次性开发工作区)中使用 -c。更新已有、共享或已部署的 Mesh 时,应省略 -c 并由人工确认提示,或至少在运行前获得人工对 diff 的明确签核——应像对待其他线上基础设施变更一样对待,而非例行 CLI 调用。
provisioning 是异步的,应轮询而非假定完成: until aio api-mesh:status 2>&1 | grep -qi success; do sleep 20; done
验证分两层:先直接验证数据源的根字段,再在其真实嵌套/认证形态下验证字段(带真实调用凭证的列表嵌套查询,而非扁平根字段调用)。第一层通过不能证明第二层有效——上述缺陷在第一层不可见。
若消费应用会直接从浏览器调用该 Mesh(不仅是服务端到服务端),增加第三层:从该应用真实 origin 发起真实请求。前两层只证明服务端可达性——没有为该 origin 配置 responseConfig.CORS 的 Mesh 会通过前两层,但在浏览器调用时全部失败,不仅是新字段。
常见问题
- 即使 token 有效,认证查询仍报 "not authorized"——数据源的 graphql handler 缺少 operationHeaders。应检查 mesh.json,而非 token。
- 嵌套/列表字段报 "No type was found for field node ... __typename",但数据源在根级正常——resolver 使用了 result 而缺少 sourceSelectionSet。应补上。
- 浏览器控制台显示 "Request header field <X> is not allowed by Access-Control-Allow-Headers in preflight response",但服务端 curl/CLI 调用同一 Mesh 正常——这是 CORS allowedHeaders 缺口,不是 schema/resolver 缺陷;curl 与 aio api-mesh:status 完全跳过浏览器预检,无法捕获。应阅读 storefront 自身配置中调用该端点客户端发送的完整头集合,一次性修复所有头的 allowedHeaders,并先检查该头是否冗余再追加。
质量要求
- aio api-mesh:status 报告 success,且新字段在其真实嵌套/认证形态下正确解析,而不仅是数据源根字段。
- 若浏览器应用会调用该 Mesh,该应用能对其完成真实请求——不仅是 aio api-mesh:status 和 curl。
衔接
若数据源尚不存在为运行时动作,先调用 commerce-app-storage、commerce-app-webhooks 或 commerce-app-eventing 进行搭建与部署。
参考资料
- API Mesh prompting guide——Adobe 官方关于提示 agent 编写 Mesh 配置的指南;通用工作流与预期。
- api-mesh-starter-kit llm.txt——参考知识库,覆盖 mesh.json 结构、三种 handler 类型、transforms、hooks、secrets、context state、CORS 及 CLI 命令集。