vtex-io-service-paths-and-cdn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VTEX IO service paths and CDN behavior

VTEX IO 服务路径与CDN行为

When this skill applies

该技能适用场景

Use this skill when you define or change service.json
routes for a VTEX IO backend and need the edge (CDN) to pass the right cookies and apply the right caching for that endpoint’s data.

Choosing between public, segment (
```
/_v/segment/...
```
), and private (
```
/_v/private/...
```
) path prefixes for a route
Setting Cache-Control
(and related headers) on HTTP responses so public cache behavior matches data scope (anonymous vs segment vs authenticated shopper)
Explaining why a route does not receive
```
vtex_session
```
or
```
vtex_segment
```
cookies
Troubleshooting CloudFront or edge behavior when cookies are missing (see official troubleshooting)

Do not use this skill for:

Application-level LRU caches, VBase, or stale-while-revalidate orchestration → use vtex-io-application-performance
GraphQL field-level
```
@cacheControl
```
only → use vtex-io-graphql-api alongside this skill

当你为VTEX IO后端定义或修改**

service.json

路由**，需要边缘节点（CDN）为对应端点的数据传递正确的Cookie并应用正确的缓存策略时，可使用本技能。

为路由选择public、segment（
```
/_v/segment/...
```
）、private（
```
/_v/private/...
```
）三类路径前缀
在HTTP响应中设置**
```
Cache-Control
```
（及相关头），确保public缓存行为与数据范围**（匿名用户、分群用户、已认证 shoppers）匹配
解释路由无法获取
```
vtex_session
```
或
```
vtex_segment
```
Cookie的原因
排查Cookie缺失时的CloudFront或边缘节点行为（参考官方故障排查指南）

本技能不适用于以下场景：

应用层LRU缓存、VBase、stale-while-revalidate编排 → 请使用vtex-io-application-performance技能
仅涉及GraphQL字段级
```
@cacheControl
```
配置 → 请搭配本技能使用vtex-io-graphql-api技能

Decision rules

决策规则

Paths are declared in service.json
under
```
routes
```
. The prefix you choose (
```
/yourPath
```
,
```
/_v/segment/yourPath
```
,
```
/_v/private/yourPath
```
) controls cookie forwarding and whether VTEX may cache the service response at the edge—see the Service path patterns table.
Public (
```
{yourPath}
```
): No guarantee the app receives request cookies. The edge may cache responses when possible. Use for non-user-specific data (e.g. static reference data that is safe to share across shoppers).
Segment (
```
/_v/segment/{yourPath}
```
): The app receives vtex_segment
. The edge caches per segment. Use when the response depends on segment (currency, region, sales channel, etc.) but not on authenticated identity.
Private (
```
/_v/private/{yourPath}
```
): The app receives vtex_segment
and vtex_session
. The edge does not cache the service response. Use for identity- or session-scoped data (orders, addresses, profile).
Cache-Control
on responses must align with classification: never signal CDN/shared cache for payloads that embed secrets, per-user data, or authorization decisions unless the contract is explicitly designed for that (e.g. immutable public assets). When in doubt, prefer private paths and no-store / private cache directives for shopper-specific JSON.
Read Sessions System overview for how cookies relate to paths and sessions.

路径在**
```
service.json
```
的
routes
字段下声明。你选择的前缀（
/yourPath
、
/_v/segment/yourPath
、
/_v/private/yourPath
）会控制Cookie转发规则和VTEX是否会在边缘节点缓存服务响应**——参考服务路径模式表格。
Public（
```
{yourPath}
```
）：不保证应用能收到请求Cookie。条件允许时边缘节点会缓存响应。适用于非用户专属数据（例如可安全在所有 shoppers 之间共享的静态参考数据）。
Segment（
```
/_v/segment/{yourPath}
```
）：应用可收到**
```
vtex_segment
```
。边缘节点按用户分群缓存。适用于响应依赖用户分群属性**（货币、地区、销售渠道等）但不依赖已认证身份的场景。
Private（
```
/_v/private/{yourPath}
```
）：应用可收到**
```
vtex_segment
```
和
```
vtex_session
```
。边缘节点不会缓存服务响应。适用于身份或会话范围**的数据（订单、地址、个人资料）。
响应中的**
```
Cache-Control
```
必须与路径分类匹配：除非明确设计为可公开缓存（例如不可变的公共静态资源），否则绝不能对包含密钥、用户专属数据、授权判断结果的 payload 标记CDN/共享缓存**。如果存在疑问，对于 shopper 专属的JSON接口，优先选择private路径和no-store / private缓存指令。
阅读会话系统概览了解Cookie与路径、会话的关联逻辑。

Hard constraints

硬性约束

Constraint: Do not use a public or segment-cached path for private or auth-scoped payloads

约束：私有或授权范围的payload不能使用public或segment缓存路径

Routes that return authenticated shopper data, PII, or authorization-sensitive JSON must not rely on public paths or edge-cached responses that could serve one user’s data to another.

Why this matters — The edge may cache or route without the session context you expect; misclassified data can leak across users or segments.

Detection — A route under a public path returns order history, addresses, tokens, or account-specific fields; or Cache-Control
suggests long-lived public caching for such payloads.

Correct — Use

/_v/private/...

for the route (or a pattern that receives

vtex_session

), and set appropriate

Cache-Control

(e.g.

private, no-store

for JSON APIs that are not cacheable). Note: the path prefix (

/_v/private/

) controls CDN and cookie behavior; the

"public": true

field controls whether VTEX auth tokens are required to call the route—these are orthogonal.

json

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

Wrong — Exposing

GET /my-app/orders

as a public path (no

/_v/private/

/_v/segment/

prefix) and returning per-user JSON while assuming the browser session is always visible to the service.

返回已认证shopper数据、个人可识别信息（PII）、授权敏感JSON的路由，绝对不能依赖public路径或边缘缓存响应，否则可能出现一个用户的数据被返回给其他用户的情况。

重要性——边缘节点可能在你预期之外的会话上下文下进行缓存或路由；分类错误的数据可能在用户或分群之间泄露。

检测方式——public路径下的路由返回订单历史、地址、令牌、账户专属字段；或是这类payload的

Cache-Control

设置了长周期的public缓存。

正确示例——为路由使用

/_v/private/...

前缀（或其他可接收

vtex_session

的路径模式），并设置合适的

Cache-Control

（例如不可缓存的JSON接口设置为

private, no-store

）。注意：路径前缀

/_v/private/

控制CDN和Cookie行为；

"public": true

字段控制调用路由是否需要VTEX auth令牌——二者是相互独立的配置。

json

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

错误示例——将

GET /my-app/orders

暴露为public路径（没有

/_v/private/

或

/_v/segment/

前缀），同时返回用户专属JSON，并且默认服务总能获取到浏览器会话信息。

Preferred pattern

Common failure modes

常见故障模式

Assuming cookies on public routes — Services do not reliably receive
```
vtex_session
```
on public paths; identity logic fails intermittently.
Caching personalized JSON at the edge — Long
```
max-age
```
on user-specific responses without
```
private
```
path + correct cache policy.
Mixing concerns — One route returns both public catalog and private account data; split endpoints or use private + server-side auth checks.
Ignoring segment — Price or promo that varies by currency or segment is served on a public path and cached for the wrong segment.

假设public路由能获取Cookie——public路径下的服务不能稳定收到
```
vtex_session
```
，身份逻辑会间歇性失效。
在边缘节点缓存个性化JSON——用户专属的响应设置了很长的
```
max-age
```
，但没有搭配private路径和正确的缓存策略。
职责混合——同一个路由同时返回public商品目录和私有账户数据；应当拆分端点，或是使用private路径+服务端授权校验。
忽略用户分群属性——根据货币或用户分群变化的价格/促销接口使用了public路径，导致错误分群的缓存被返回。

Review checklist

审核检查清单

Is each route’s path prefix (
```
public
```
/
```
/_v/segment
```
/
```
/_v/private
```
) justified by cookie and Caching behavior in the official table?
For shopper-specific or auth responses, is the route private (or otherwise protected) and not edge-cacheable inappropriately?
Do Cache-Control
(and related) headers match data sensitivity?
Are parallel calls from the client using the correct path for each payload type?

每个路由的路径前缀（public /
```
/_v/segment
```
/
```
/_v/private
```
）都符合官方表格中Cookie和缓存行为的对应规则？
对于shopper专属或授权相关的响应，路由是private（或有其他保护机制），不会被边缘节点不当缓存？
```
Cache-Control
```
（及相关）头与数据敏感度匹配？
客户端发起的并行请求对每类payload都使用了正确的路径？

Related skills

Reference

参考资料

Service path patterns — Path formats, cookies, caching, use cases
Sessions System overview —
```
vtex_segment
```
,
```
vtex_session
```
, session behavior
App Development — VTEX IO app development hub
VTEX IO Engineering guidelines — Scalability and IO development practices

服务路径模式 —— 路径格式、Cookie、缓存、使用场景
会话系统概览 ——
```
vtex_segment
```
、
```
vtex_session
```
、会话行为
应用开发 —— VTEX IO应用开发中心
VTEX IO工程指南 —— 可扩展性与IO开发实践