📢 接口更新声明 · 2025 年 8 月 18日

API 更新文档 — GET /api/v1/sites/:site_id/pages

变更内容

1. full_path_in 参数

• 当 未传递其他排序参数（sort_by）时，查询结果将 按照传入的 full_path_in 顺序返回。
• 示例：

  ?full_path_in=a/b/c, a/d/e
  

  返回结果的顺序将与传入的 full_path_in 顺序一致。

2. 新增排序参数：sort_by=position_tree

• 新增支持 目录结构顺序 排序。
• 使用方式：

  ?sort_by=position_tree
  

• 排序规则
  1. 页面顺序由 父页面链路（祖先路径 + 自身 position） 决定；
  2. 父页面在前 → 其子页面一定整体排在前面；
  3. 同一父页面下，子页面按自身 position 排序；
  4. 保证树形目录结构的完整性。

示例

A (pos=1)
 ├─ A1 (pos=2)
 └─ A2 (pos=3)
B (pos=2)
 ├─ B1 (pos=1)
 │   ├─ B1a (pos=1)
 │   └─ B1b (pos=2)
 └─ B2 (pos=2)

A, A1, A2, B, B1, B1a, B1b, B2

• 虽然 B1 (pos=1) 小于 A1 (pos=2)，但由于 B 在 A 后面，B1 也必须排在 A 之后；
• B1a / B1b 的排序，受制于父页面 B1 的顺序。

3. 全文检索（keywords 参数）说明

• 当使用 keywords 参数进行全文检索时：
  • 不再执行 full_path_in 排序或 position_tree 排序。
  • 查询结果只会按照 搜索相关度（pg_rank 值） 排序，确保最相关的结果优先。

4. API 缓存说明

HTTP Header参数

• FROM_CACHE
  • 用于开启缓存，并设置缓存的唯一标识。
  • 如果不设置，API 将不启用缓存。
  • 修改这个值，即可刷新缓存，旧的缓存依然存在，过期自动清除。
• FROM_CACHE_TTL
  • 设置 API 缓存过期时间（单位：秒）。
  • 默认值为 7200 秒（2 小时）。
  • API 缓存时间是 FROM_CACHE_TTL + 10分钟 。

使用示例

# 开启缓存，并设置缓存唯一标识
FROM_CACHE=version20250818

# 设置 API 缓存过期时间为 300 秒（默认 7200 秒）
FROM_CACHE_TTL=300

FROM_CACHE_TTL + 600 秒
# 示例：300 + 600 = 900 秒

清除缓存

# 原先
FROM_CACHE=version20250818

# 刷新缓存
FROM_CACHE=version20250819

• X-Baklib-Cache → MISS 或 HIT
• Age → 缓存存在时间（单位：秒）

X-Baklib-Cache: HIT
Age: 120

5 资源 URL 过期时间控制（请求 Header）

• DAM_URL_TTL：资源 URL 的生存时间（秒），最高优先级。
• DAM_URL_TTL_DELAY_AFTER_CACHE：资源 URL 在缓存过期后的额外生存时间（秒）。
• DAM_URL_TTL_DELAY_AFTER_CACHE 依赖 FROM_CACHE_TTL，只有在设置了 FROM_CACHE_TTL 的情况下才会生效。

5.1 过期时间优先级与计算

1. 若设置 DAM_URL_TTL：

5.2 使用示例

# 直接指定 URL 过期时间为 1800 秒（最高优先级）
DAM_URL_TTL=1800

# 缓存 300 秒，缓存过期后希望 URL 额外存活 600 秒
FROM_CACHE_TTL=300
DAM_URL_TTL_DELAY_AFTER_CACHE=600
# 实际 URL 过期时间 = 300 + 600 = 900 秒