跳转到正文

缓存页面上的个性化片段

从静态缓存提供的页面对所有人都相同。这正是缓存的目的,也带来了问题:页眉需要对已登录客户显示“嗨,Ada”,购物车图标则要显示三件商品。如果模板根据当前用户进行分支,缓存要么会把某位访客的问候语存下来并展示给所有人,要么就只能完全跳过该页面。

Blockstudio的动态岛将这两个需求分开处理。缓存的 HTML包含一个可安全缓存的占位符。页面加载后,一个小型运行时会在访客自己的请求中向 WordPress请求个性化片段,并将其替换进去。页面仍可缓存,只有片段是动态的。

本指南将构建两个岛:问候语和购物车数量,并介绍缓存页面包含的内容、片段请求的形式,以及端点如何判断访客身份。本指南与以静态WordPress提供HTML配套。

动态岛的工作方式

  1. 区块在标记元素中渲染占位符。标记中包含区块名称、允许列表中的属性,以及服务器生成的签名。
  2. 由于渲染后的页面包含标记,Blockstudio会注入岛运行时。没有岛的页面不会加载岛JavaScript。
  3. 运行时收集已就绪的标记,并向 /wp-json/blockstudio/v1/island/render发送一个批量 POST。
  4. 端点会验证每个签名,在访客的请求上下文中渲染区块,并返回片段。
  5. 运行时替换每个占位符并分发事件。

在区块编辑器中,区块会正常渲染,不使用占位符。

第 1 步:问候区块

创建区块,包含三个文件:

代码
blocks/
└── greeting/
    ├── block.json
    ├── placeholder.php
    └── index.php
JSON
{
  "apiVersion": 3,
  "name": "acme/greeting",
  "title": "Greeting",
  "category": "widgets",
  "icon": "admin-users",
  "description": "Account link that greets signed-in visitors.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "tag": "span",
      "attributes": ["guestLabel"],
      "cache": {
        "ttl": 300,
        "per": "user"
      }
    },
    "attributes": [
      { "id": "guestLabel", "type": "text", "label": "Guest label", "default": "Sign in" }
    ]
  }
}

mode: "dynamic"让它成为会发起片段请求的岛。 tag设置标记元素,因此该岛可以内嵌在导航栏中。attributes是随片段请求传递的区块属性允许列表;未列出的属性既不会发送,也不会签名。下文将进一步介绍 cache。

缓存页面中包含的就是这个占位符。它必须能安全地展示给每位访客,因此不能包含用户数据。“账户”链接适用于所有人:

PHP
<a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">Account</a>

主模板会渲染实际片段:

PHP
<?php
$user = wp_get_current_user();
?>
<?php if ( $user->exists() ) : ?>
  <a href="<?php echo esc_url( home_url( '/account/' ) ); ?>">
    <?php echo esc_html( sprintf( 'Hi, %s', $user->display_name ) ); ?>
  </a>
<?php else : ?>
  <a href="<?php echo esc_url( wp_login_url() ); ?>">
    <?php echo esc_html( $a['guestLabel'] ); ?>
  </a>
<?php endif; ?>

在此处根据当前用户进行分支没有问题:该模板只会在片段请求时运行,绝不会用于缓存页面。

将它放在页眉的渲染位置:

PHP
<?php echo bs_block( array( 'name' => 'acme/greeting' ) ); ?>

区块标签也可以使用:<bs:acme-greeting /> 或 <block name="acme/greeting" />。

第 2 步:缓存页面包含的内容

区块在服务器上渲染时,只会生成标记和占位符:

HTML
<span data-bs-island="acme/greeting" data-bs-island-mode="dynamic" data-bs-island-phase="placeholder" data-bs-island-props="{&quot;guestLabel&quot;:&quot;Sign in&quot;}" data-bs-island-signature="a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043" data-bs-island-loading="eager"><!--blockstudio/acme/greeting--><a href="https://example.com/account/">Account</a>
</span>

分别以匿名访客和已登录用户的身份渲染一次,得到的两段字符串会逐字节相同。这正是启用了 serveLoggedIn 的静态预渲染所要求的特性:无论是谁触发渲染,存储的文档都相同,其中不会包含任何个人信息。

第 3 步:片段请求

运行时会在一个请求中发送所有已就绪的岛:

JSON
{
    "islands": [
        {
            "clientId": "a1",
            "name": "acme/greeting",
            "attributes": {
                "guestLabel": "Sign in"
            },
            "signature": "a7311ba9f6abf3c993edfdd7d49d2fa23bfa068f715b96637c35ef30de8b2043"
        }
    ]
}

响应以 clientId 为键。对于已登录访客:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/account/\">\n    Hi, Ada  </a>\n"
}

验证失败的条目会返回错误代码,而不是 HTML,且不会影响批次中的其余条目。这里,第二个条目在没有相应签名的情况下更改了 guestLabel,第三个条目则指定了一个并非动态岛的区块:

JSON
{
    "a1": "<!--blockstudio/acme/greeting-->  <a href=\"https://example.com/wp-login.php\">\n    Sign in  </a>\n",
    "a2": {
        "error": "blockstudio_island_invalid_signature"
    },
    "a3": {
        "error": "blockstudio_island_not_allowed"
    }
}

每个响应都会携带 Cache-Control: no-store, no-cache, must-revalidate, max-age=0、 Pragma: no-cache 和 X-Robots-Tag: noindex。端点位于 /wp-json 下,静态预渲染总会绕过该路径,因此无论是源站缓存,还是遵循源站标头的 CDN,都不会存储片段。

访客身份的判断方式

运行时会使用 credentials: 'same-origin' 发送请求,因此浏览器会附带 WordPress 登录 Cookie。WordPress REST API 通常不会在没有随机数的情况下接受 Cookie 身份验证,而缓存页面中无法包含随机数。岛端点会自行处理这一问题:对于同源浏览器请求,它会验证 logged_in Cookie,并在渲染前恢复该用户身份。

同源性根据 Sec-Fetch-Site 标头判断;如果请求中带有 Origin 标头,则会将其与 home_url() 对比。来自其他源的请求即使携带该 Cookie,也会以匿名身份进行渲染,因此来自其他网站的请求绝不会渲染访客的个性化片段。实际情况如下:

请求 渲染身份
携带有效登录 Cookie 的同源 fetch 请求 已登录用户
携带相同 Cookie 的跨源请求 匿名
不携带 Cookie 匿名

这是哪个页面?

当片段需要其所属页面的身份信息时,请将 "context": true 添加到 blockstudio.island。随后,标记会在属性之外,对查询页面的文章 ID 和文章类型进行签名。在片段中,$block['postId']、$block['postType']、get_the_ID() 和 get_queried_object_id() 都指向该页面。在查询循环中,这仍指外层被查询的页面,而不是循环项。

页面上下文为可选项,也会作为片段缓存键的一部分。即使片段已缓存,端点也会再次检查访问权限,因此签名标记不会暴露后来已设为私密或受密码保护的页面。配置和安全详情请参阅 页面上下文。不会重放任意 URL 或查询参数。

第 4 步:自动刷新的购物车数量

第二个岛展示了另一种占位符样式和两个运行时选项。模板不使用单独的占位符文件,而是检查 $isIslandPlaceholder:

JSON
{
  "apiVersion": 3,
  "name": "acme/cart-count",
  "title": "Cart Count",
  "category": "widgets",
  "icon": "cart",
  "description": "Number of items in the visitor's cart.",
  "blockstudio": {
    "island": {
      "mode": "dynamic",
      "loading": "visible",
      "event": "acme:cart-updated"
    },
    "attributes": []
  }
}
PHP
<?php
$count = (int) apply_filters( 'acme/cart_count', 0 );
?>
<?php if ( $isIslandPlaceholder ) : ?>
  <a href="/cart/" class="cart-count">Cart</a>
<?php else : ?>
  <a href="/cart/" class="cart-count">
    Cart <span class="cart-count__badge"><?php echo esc_html( (string) $count ); ?></span>
  </a>
<?php endif; ?>

所有模板语言都有相同的标志:isIsland、 isIslandPlaceholder、isIslandFragment 和 islandPhase("normal"、 "hydrate"、"placeholder" 或 "fragment")。这里,数量来自一个由你的电商代码填充的 acme/cart_count 筛选器;当它返回 3 时,端点会返回:

JSON
{"c1":"<!--blockstudio/acme/cart-count-->  <a href=\"/cart/\" class=\"cart-count\">\n    Cart <span class=\"cart-count__badge\">3</span>\n  </a>\n"}

loading: "visible"会使用 IntersectionObserver,直到标记进入视口后才发起请求。相邻出现的可见岛仍会合并到一个请求中。event用于指定重新获取岛内容的窗口事件,因此调用加入购物车后,你的脚本只需发出通知:

JavaScript
window.dispatchEvent(new Event('acme:cart-updated'));

在前端代码中作出响应

事件会从标记处向上冒泡,因此在 document 上添加一个监听器即可覆盖所有岛屿。event.detail.name 保存区块名称:

JavaScript
document.addEventListener('blockstudio:island:rendered', (event) => {
  if (event.detail.name !== 'acme/cart-count') return;
  event.target.querySelector('.cart-count__badge')?.classList.add('is-fresh');
});

document.addEventListener('blockstudio:island:error', (event) => {
  console.warn('Island failed', event.detail.name, event.detail.error);
});

交换后,运行时会先分发 blockstudio:island:rendered,再分发 blockstudio:island:hydrate。失败时,占位符会保留在原位,并触发 blockstudio:island:error。已水合的岛屿("island": "hydrate")会完全跳过请求:页面中已有完整的 HTML,它们只会收到 hydrate 事件,适用于选项卡等可安全缓存的交互式区块。

片段缓存

默认情况下,每次请求都会渲染片段。上面的问候语启用了短期缓存:

JSON
{
  "cache": {
    "ttl": 300,
    "per": "user"
  }
}

per: "user" 会按 WordPress 用户 ID 区分缓存片段,并且匿名请求绝不会以此方式缓存,因此两个匿名访客不会共用原本属于某个用户的条目。per: "global" 会为相同的区块和属性共用一个片段,适用于实时但不涉及个人信息的内容,例如库存量。ttl 默认为 60 秒,cache: true 是一个 60 秒的全局缓存。

安全模型

该端点是公开的,但它并非通用区块渲染器。只有满足以下所有条件时,它才会渲染一个条目:

  • 区块已注册、为动态区块,并且 island.mode 设置为 dynamic
  • 签名与区块名称以及经过筛选后保留的属性相匹配:仅限同时存在于区块架构和岛屿允许列表中的键

签名是对规范化后的区块名称和属性计算得到的 HMAC-SHA256,使用提供服务的网站的 auth 盐值作为密钥。签名会在该网站上渲染时创建,绝不会预先写入主题。因此有两个结果:在预发布环境中渲染的文档带有预发布环境的签名,所以应在提供这些文档的网站上渲染。轮换 WordPress 盐值会使存储文档中的所有签名失效,因此盐值轮换后应清除静态预渲染内容。

单个请求最多可接受 50 个岛屿;超过后会返回 HTTP 413。使用 blockstudio/islands/max_per_request 更改此限制。对于需要采用不同方案的主机,可使用签名钩子(blockstudio/islands/signature_payload、blockstudio/islands/signature、blockstudio/islands/verify_signature)。

不适合使用岛屿的情况

片段不在初始 HTML 中,因此爬虫看不到它们。请将与 SEO 相关的内容保留在常规渲染中。动态岛屿适合用于页面框架加载后才出现的内容:账户链接、购物车状态、推荐内容和受权限控制的控件。如果整个页面都涉及个人信息,例如账户仪表板,请改为在 dynamicPaths 中列出其路径,并实时渲染。

后续步骤