当 VTEX IO 服务需要跨应用共享结构化配置时…

在 VTEX IO 中通过 configuration builder 让服务应用从独立配置应用接收结构化配置，并用 ctx.vtex.settings 读取注入值。

适用场景

解决思路

1. 将服务应用与配置应用视为两个独立职责：服务应用负责运行时（node、graphql 等），配置应用只负责提供配置值。
2. 在服务应用的 manifest.json 中声明 configuration builder，并定义 configuration/schema.json。
3. 配置应用不要声明 node 或 graphql builder，通常只保留 configuration builder。
4. 在配置应用的 manifest.json 的 configuration 字段中指向目标服务应用，并在 configuration/<service-app>/configuration.json 中提供具体值。
5. 当配置契约需要独立于消费它的应用、需要被多个应用或服务共享、或需要独立版本化时，使用配置应用。
6. 在服务应用中通过 node/service.json 的路由或事件上的 settingsType: "workspace"，或 GraphQL 中的 @settings 指令，显式暴露配置入口点。
7. 配置应用中 configuration/ 下的文件夹名和 configuration 字段的 key 必须与目标服务应用 ID 匹配，例如 vendor.shipping-service 对应 shipping-service。
8. configuration.json 的结构必须符合服务应用声明的 JSON Schema。
9. 在服务运行时中从 ctx.vtex.settings 读取接收到的配置，而不是自己发起 HTTP 请求去获取这些值。
10. 处理函数和解析器应将 ctx.vtex.settings 强制转换或校验以匹配配置 schema，并应用与 schema 一致的默认值。
11. 将配置应用视为通过 VTEX IO 上下文注入结构化运行时配置的方式，而不是任意运营数据存储的替代品。
12. 当配置仅属于单个应用并应直接在 Apps > App Settings 中编辑时使用 settingsSchema；当契约需要共享、版本化或与消费应用生命周期解耦时使用配置应用。
13. 如果通过配置应用配置的服务因权限问题无法解析 workspace 应用配置，应显式评估该场景下 manifest 是否需要 read-workspace-apps 策略，不要默认给无关服务添加该策略。
14. 对于服务配置契约，优先使用 additionalProperties: false 的封闭 schema，并在结构复杂时使用 definitions 加 $ref。
15. 服务应用必须通过 settingsType: "workspace" 或 @settings 显式声明配置可注入的位置，否则配置应用不会自动应用到所有服务入口点。
16. 配置应用和服务必须使用显式 schema 文件（configuration/schema.json 与匹配的 configuration.json），不要使用隐式或未文档化的载荷。
17. 当服务已暴露 settingsType 或 @settings 时，必须从 ctx.vtex.settings 消费注入值，不要额外创建自定义 HTTP 调用来获取相同配置。
18. 按首选模式建模：服务应用暴露配置解析位置、定义 configuration/schema.json；配置应用声明服务为 builder 并在 configuration.json 中提供值；服务通过 ctx.vtex.settings 读取注入配置。
19. 在 manifest.json 中声明 configuration builder，例如 "builders": { "node": "7.x", "configuration": "1.x" }。
20. 在 configuration/schema.json 中使用 draft-07 schema，并通过 definitions 和 $ref 定义配置结构，例如 ShippingConfiguration 包含 carrierApi 的 baseUrl、apiKey、timeoutMs 等字段。
21. 在配置应用的 manifest.json 中设置 "configuration": { "shipping-service": "1.x" }，并在 configuration/shipping-service/configuration.json 中提供符合 schema 的值。
22. 在 Node 服务中通过 ctx.vtex.settings 读取配置并应用默认值，例如 const timeoutMs = settings.carrierApi.timeoutMs ?? 3000。
23. 在 GraphQL 查询中使用 @settings(type: "workspace") 指令，并在解析器中通过 ctx.vtex.settings 读取配置。
24. 完成最小工作清单：服务应用声明 configuration builder、定义 configuration/schema.json、配置应用提供兼容的 configuration.json、需要配置的路由或事件声明 settingsType: "workspace"、评估是否需要 read-workspace-apps。
25. 避免常见失败模式：用 app settings 代替共享配置契约、创建无显式 schema 的配置应用、忘记 settingsType 或 @settings、已注入仍通过 HTTP 获取配置、把配置应用当作通用运营存储。
26. 按审查清单自检：是否真的需要配置应用而非 settingsSchema、服务是否显式 opt in、configuration/schema.json 与 configuration.json 是否匹配、是否从 ctx.vtex.settings 读取、是否刻意评估 read-workspace-apps、schema 是否封闭明确、配置契约是否与运营数据存储分离。

适用边界 · 注意事项

• 仅需应用本地配置并通过 settingsSchema 在 Apps > App Settings 中直接编辑时。
• Store Framework 通过 contentSchemas.json 管理的 block settings。
• 与配置无关的通用服务运行时接线，或超出配置所需权限的策略设计。