VTEX IO 后端应用集成 VTEX 服务或外部 API…

在 VTEX IO 后端应用中通过 @vtex/api 和 @vtex/clients 的客户端体系调用 VTEX 服务或外部 API，而不是使用原始 HTTP 库。

适用场景

解决思路

1. 优先使用 @vtex/api 或 @vtex/clients 中已覆盖目标 VTEX 服务的原生客户端（如 catalog、checkout、logistics、OMS），仅当没有合适的原生客户端或工厂时才编写自定义客户端。
2. ExternalClient 主要用于非 VTEX 的外部 API；当存在原生客户端、JanusClient 或其他文档化的更高层 VTEX 客户端时，避免用它调用 VTEX 托管的端点（如 *.myvtex.com 或 *.vtexcommercestable.com.br）。
3. Janus 是 VTEX 核心商务 API 网关；仅当需要通过 Janus 调用 VTEX Core Commerce API 且 @vtex/clients 中没有合适的原生客户端时才使用 JanusClient。
4. InfraClient 仅在有明确文档指导的高级 VTEX IO 基础设施服务集成中使用；在合作伙伴应用中优先使用 masterData、vbase 等更高层客户端和工厂，而不是直接扩展 InfraClient。
5. 在 node/clients/index.ts 中通过继承 IOClients 的 Clients 类注册每个自定义或原生客户端。
6. 通过 ctx.clients 消费集成，绝不在中间件、resolver 或事件处理器中直接实例化客户端类。
7. 让客户端专注于传输、请求选项、端点路径和少量响应整形；将业务规则、授权决策和编排放在客户端之外。
8. 构建自定义客户端时，始终依赖 VTEX IO 传入的 IOContext（如 account、workspace 和可用的认证令牌），而不是硬编码账号名、工作区或环境相关的 VTEX URL。
9. 在运行时客户端配置中配置共享的 InstanceOptions，仅当某个集成有明确不同的需求时才使用客户端级覆盖。
10. 在重要的客户端调用上使用 metric 选项，使集成可在客户端层被追踪和监控，而不仅在处理器层。
11. 将错误规范化保持在客户端边界附近，但避免隐藏对可观测性和调试重要的相关 HTTP 状态码或传输失败。
12. 集成外部服务时，确认应用契约中声明了所需的出站策略，但将详细的策略建模留给 auth 或 app-contract 相关技能。
13. 在罕见的迁移或遗留场景中，ExternalClient 可临时用于 VTEX 托管端点，但应视为例外；长期目标应是迁移到原生客户端或正确的文档化 VTEX 客户端抽象，以保持路由、认证和可观测性一致。
14. 客户端选择指南：ExternalClient 用于调用非 VTEX 外部 API，避免用于已有原生客户端或基于 Janus 抽象的 VTEX 托管 API；JanusClient 用于调用尚未被 @vtex/clients 包装的 VTEX Core Commerce API，避免用于已有原生客户端的 VTEX 服务（如 Catalog、Checkout、Logistics、OMS）；InfraClient 仅在有明确文档指导时实现高级基础设施风格客户端，避免用于合作伙伴应用中的一般 VTEX 或外部 API。
15. InstanceOptions 启发式：从小的、明确的客户端默认值开始，如 retries: 2 和 1000 到 3000 毫秒之间的请求 timeout。
16. 对幂等操作使用小的有限重试值，如 1 到 3。
17. 除非上游 API 明确记录了安全的幂等行为，否则避免对非幂等操作自动重试。
18. 不要用高重试次数掩盖上游不稳定；清晰地暴露重复失败并在业务层有意处理。
19. 优先使用客户端级 headers 和 metrics，而不是在处理器中分散定义 header。
20. 仅当重复读取合理且响应可安全复用时，才使用内存或磁盘缓存选项。
21. 将认证设置放在客户端构造函数或工厂配置中，不要在处理器中重复。
22. 硬约束：VTEX IO 后端应用的所有服务间 HTTP 调用必须通过 @vtex/api 或 @vtex/clients 客户端；不要使用 axios、fetch、got 或 node-fetch 等原始库进行服务集成。
23. 硬约束：客户端必须注册在继承 IOClients 的 Clients 类中，中间件、resolver 或事件处理器必须通过 ctx.clients 访问它们；不要在处理器中直接 new MyClient(...)。
24. 硬约束：每个集成必须使用与其边界匹配的最窄客户端类型；不要在所有集成中默认使用 ExternalClient 或 JanusClient，当存在更具体的客户端类型或原生包时。
25. 推荐文件布局：node/clients/index.ts、node/clients/catalog.ts、node/clients/partnerApi.ts、node/middlewares/getData.ts、node/index.ts。
26. 在一个地方注册原生和自定义客户端：在 Clients 类中通过 getOrSet 暴露 catalog、partnerApi 等。
27. 创建自定义客户端时使用显式路由和选项：在构造函数中调用 super 传入基础 URL、context 和包含 retries、timeout、headers 的选项，并通过 this.http.get 等方法调用路由，附带 metric。
28. 在运行时通过 ClientsConfig 配置共享客户端选项：implementation 设为 Clients，options.default 中设置 retries 和 timeout。
29. 在处理器中通过 ctx.clients 使用客户端，例如 ctx.clients.partnerApi.getOrder(...)。
30. 如果客户端文件过大，按有界集成域拆分，并保持 node/clients/index.ts 为小型注册表。
31. 常见失败模式：在后端处理器中使用 axios、fetch 等原始 HTTP 库；在处理器中直接实例化客户端而不在 IOClients 中注册；当已有原生 VTEX 客户端或更具体的应用客户端时选择 ExternalClient；将业务规则、验证或编排放入客户端而不是保持为传输包装；在处理器中分散 headers、认证设置和重试设置而不是集中在客户端或共享客户端配置中；忘记在自定义客户端中声明外部集成所需的出站访问策略。
32. 审查清单：每个集成是否使用正确的 VTEX IO 客户端抽象？是否优先使用 @vtex/api 或 @vtex/clients 中的原生客户端？客户端是否注册在 IOClients 中并通过 ctx.clients 消费？后端集成代码中是否没有原始 HTTP 库？重试、超时、headers 和 metrics 是否配置在客户端层而不是分散在处理器中？业务规则是否保持在客户端层之外？

适用边界 · 注意事项

• 不适用于决定 manifest.json 中的应用契约。
• 不适用于结构化 node/index.ts 或调整 service.json。
• 不适用于设计 GraphQL schema 或 resolver 契约、建模路由授权或安全权限、构建店面或管理前端集成。