vtex-io-service-paths-and-cdn

VTEX IO 服务路径与 CDN 行为

适用场景

在为 VTEX IO 后端定义或更改 service.json 路由，并需要边缘（CDN）为该端点的数据传递正确的 Cookie和应用正确的缓存策略时，使用此技能。

• 为路由选择 public、segment（/_v/segment/...）和 private（/_v/private/...）路径前缀
• 在 HTTP 响应中设置 Cache-Control（及相关标头），使 public 缓存行为与数据范围（匿名、segment 或已认证购物者）相匹配
• 说明路由为何没有收到 vtex_session 或 vtex_segment Cookie
• 排查 CloudFront 或边缘行为导致 Cookie 缺失的问题（参见官方故障排查指南）

以下情况不要使用此技能：

• 应用级 LRU 缓存、VBase 或 stale-while-revalidate 编排 → 使用 vtex-io-application-performance
• 仅涉及 GraphQL 字段级 @cacheControl → 将此技能与 vtex-io-graphql-api 配合使用

决策规则

• 路径在 service.json 的 routes 下声明。所选前缀（/yourPath、/_v/segment/yourPath、/_v/private/yourPath）决定Cookie 转发以及 VTEX 是否可能在边缘缓存服务响应——请参见 服务路径模式 表格。
• Public（{yourPath}）：不保证应用能收到请求 Cookie。在可能的情况下，边缘可能会缓存响应。用于非用户专属数据（例如可供不同购物者共享的静态参考数据）。
• Segment（/_v/segment/{yourPath}）：应用会收到 vtex_segment。边缘会按 segment 缓存。用于响应取决于 segment（货币、地区、销售渠道等），但不取决于已认证身份的情况。
• Private（/_v/private/{yourPath}）：应用会收到 vtex_segment 和 vtex_session。边缘不会缓存服务响应。用于身份或会话范围内的数据（订单、地址、个人资料）。
• 响应中的 Cache-Control 必须与数据分类相符：对于包含机密信息、用户专属数据或授权决策的载荷，除非契约明确为此设计（例如不可变的公开资源），否则绝不要启用 CDN/共享缓存。如有疑问，优先使用 private 路径，并为购物者专属的 JSON 设置 no-store / private 缓存指令。
• 阅读 Sessions System 概览，了解 Cookie 与路径及会话的关系。

硬性约束

约束：不要使用 public 或按 segment 缓存的路径传递私有或与身份验证相关的载荷

返回已认证购物者数据、PII 或对授权敏感的 JSON 的路由，不得依赖 public 路径或边缘缓存响应，否则可能将一个用户的数据提供给另一个用户。

重要原因——边缘可能会在缺少你预期的会话上下文时缓存或路由；错误分类的数据可能泄露给其他用户或 segment。

识别方式——public 路径下的路由返回订单历史、地址、令牌或账户专属字段；或者 Cache-Control 表明此类载荷将长期公开缓存。

正确做法——为路由使用 /_v/private/...（或使用能接收 vtex_session 的模式），并设置适当的 Cache-Control（例如，为不可缓存的 JSON API 设置 private, no-store）。注意：路径前缀（/_v/private/）控制 CDN 和 Cookie 行为；"public": true 字段控制调用路由时是否需要 VTEX 身份验证令牌——两者互不相关。

{
  "routes": {
    "myOrders": {
      "path": "/_v/private/my-app/orders",
      "public": true
    }
  }
}

错误做法——将 GET /my-app/orders 暴露为 public 路径（不带 /_v/private/ 或 /_v/segment/ 前缀），并返回用户专属 JSON，同时假定服务始终能看到浏览器会话。

推荐模式

1. 在选择路径前，先对响应进行分类（匿名、分段、已认证）。
2. 根据 服务路径模式映射到 public / segment / private。
3. 在平台允许的情况下，明确设置响应标头：让 Cache-Control 与相同分类保持一致（公共不可变、私有或不存储）。
4. 记录必须出于安全或合规要求保持私有的路径，避免店面和 BFF 错误地对其进行链接缓存。

常见故障模式

• 假设公共路由上存在 Cookie — 服务在公共路径上无法可靠地收到 vtex_session；身份逻辑会间歇性失效。
• 在边缘缓存个性化 JSON — 对用户专属响应设置较长的 max-age，却没有使用私有路径和正确的缓存策略。
• 混合不同关注点 — 一个路由同时返回公共目录和私有账户数据；应拆分端点，或使用私有路径并进行服务器端身份验证检查。
• 忽略分段 — 随货币或分段变化的价格或促销内容通过公共路径提供，并被缓存到错误的分段。

审查清单

• 根据官方表格中的 Cookie 和缓存行为，每个路由的路径前缀（public / /_v/segment / /_v/private）是否合理？
• 对于购物者专属或身份验证响应，路由是否为私有（或受到其他保护），且不会被不当的边缘缓存？
• Cache-Control（及相关）标头是否与数据敏感性一致？
• 客户端发起的并行调用是否为每种负载类型使用了正确路径？

相关技能

• vtex-io-application-performance — 应用性能（LRU、VBase、AppSettings、并行获取、租户密钥）
• vtex-io-service-apps — service.json 和 Service 入口
• vtex-io-graphql-api — GraphQL 缓存和 @cacheControl
• headless-caching-strategy — 店面 / BFF 缓存

参考

• 服务路径模式 — 路径格式、Cookie、缓存、使用场景
• Sessions System 概览 — vtex_segment、vtex_session、会话行为
• App Development — VTEX IO 应用开发中心
• VTEX IO Engineering guidelines — 可扩展性和 IO 开发实践