在服务端调用外部 API 并管理缓存

页面可以在服务端取站点之外的数据：第三方 API、你自己的服务、平台的公开接口。渲染结果会进 HTML 缓存，而缓存只在收到 publish 事件时失效。站点自己的数据（CMS、表单、数据表）取数时会自动登记依赖，外部数据不会——所以外部数据必须由页面自己声明依赖，否则页面会一直显示第一次渲染时的内容。

取数放在哪里

在服务端调用外部 API

fetch 在服务端渲染期间是全局可用的，用法与浏览器一致。返回的 props 会被序列化进 HTML 交给页面组件。

// /page/templates.tsx
export async function getServerSideProps(ctx) {
  const res = await fetch('https://api.example.com/v1/items?limit=12')

  // 外部服务挂了不应该让整个页面 500，给一个能渲染的兜底。
  if (!res.ok) return { props: { items: [] } }

  const data = await res.json()
  return { props: { items: data.list ?? [] } }
}

export default function Templates({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </ul>
  )
}

抛出异常会让页面渲染失败。外部依赖务必判断响应状态并准备降级内容。

声明缓存依赖

在 getServerSideProps 里调用 ctx.cacheDepends(key)，告诉渲染端「这个页面依赖名为 key 的外部数据」。key 是你自己定义的字符串，只要发布时用同一个即可。

export async function getServerSideProps(ctx) {
  ctx.cacheDepends('templates')

  const res = await fetch('https://api.example.com/v1/items?limit=12')
  if (!res.ok) return { props: { items: [] } }
  return { props: { items: (await res.json()).list ?? [] } }
}

• 可以一次声明多个：ctx.cacheDepends('templates', 'template-tags')，也可以分多次调用，重复的 key 会自动去重。
• 实际记录到缓存里的是 custom/{site_id}/templates。站点命名空间由渲染端按当前站点补上，页面写不出别的站点的 key。
• 只要在 getServerSideProps 执行期间调用即可，放在 fetch 之前或之后都行。
• 不声明的后果：这个页面只会在站点发布、页面改动这类既有事件下失效，外部数据再怎么变都不会重新渲染。

作废缓存

外部数据变更之后，调用发布接口把声明了该 key 的页面缓存作废。下一个访问者会触发重新渲染并拿到新数据。

POST /api/p/project/{project_id}/site/{site_id}/render_cache/publish
Authorization: Bearer <token>
Content-Type: application/json

{ "keys": ["templates"] }

返回实际被作废的依赖 key：

{ "published": ["custom/{site_id}/templates"] }

作废是「删除」而不是「重算」：缓存条目直接失效，重新渲染的成本由下一个访问者承担。需要预热就在发布之后自己请求一次页面。

完整例子

一个从外部接口取列表、支持按分类筛选的页面。注意 key 与筛选条件无关：同一份数据源的所有分页和筛选组合共用一个 key，一次发布全部作废。

// /page/templates.tsx
const API = 'https://api.example.com/v1/templates'

export async function getServerSideProps(ctx) {
  ctx.cacheDepends('templates')

  const category = ctx.query.category ?? ''
  const url = category ? `${API}?category=${encodeURIComponent(category)}` : API

  const res = await fetch(url)
  if (!res.ok) return { props: { items: [], category } }

  const data = await res.json()
  return { props: { items: data.list ?? [], category } }
}

外部数据变更后：

await fetch(
  `https://creght.cn/api/p/project/${projectId}/site/${siteId}/render_cache/publish`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ keys: ['templates'] }),
  },
)

缓存边界

• 缓存按站点、域名、路径和查询串区分。?category=a 与 ?category=b 是两条缓存，但它们声明的是同一个 key，一次发布会一起作废。
• 在 getServerSideProps 里读 Cookie，页面会按读到的 Cookie 名分变体缓存；写 Cookie 则整页不进缓存，此时声明依赖没有意义。
• 预览模式不走缓存，调试时看到的永远是最新数据。要验证缓存行为请用正式域名访问。
• props 会原样序列化进 HTML，浏览器可见。只放页面要渲染的字段，不要把上游接口的完整响应直接透传出去。

检查清单

• 外部接口的调用写在 getServerSideProps 里，需要密钥或写入的改走 Func。
• 响应状态判断和降级内容都写了，外部服务不可用时页面仍能渲染。
• 每一份外部数据都有对应的 ctx.cacheDepends(key)。
• 数据变更方会调用发布接口，key 与页面里写的完全一致。
• props 里没有密钥、内部 ID 和用不到的上游字段。