📢 接口更新声明 · 2025 年 8 月 18日
Tanmer
发布于：2025-08-18
### API 更新文档 — `GET /api/v1/sites/:site_id/pages`
#### 变更内容
### 1. `full_path_in` 参数
* 当 **未传递其他排序参数**（`sort_by`）时，查询结果将 **按照传入的 `full_path_in` 顺序返回**。
* 示例：
```json
?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. 保证树形目录结构的完整性。
#### 示例
目录结构（含 position）：
```
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分钟` 。
---
#### 使用示例
```bash
# 开启缓存，并设置缓存唯一标识
FROM_CACHE=version20250818
# 设置 API 缓存过期时间为 300 秒（默认 7200 秒）
FROM_CACHE_TTL=300
```
返回的内容过期时间为：
```
FROM_CACHE_TTL + 600 秒
# 示例：300 + 600 = 900 秒
```
---
#### 清除缓存
通过修改 `FROM_CACHE` 的值即可刷新缓存，例如：
```bash
# 原先
FROM_CACHE=version20250818
# 刷新缓存
FROM_CACHE=version20250819
```
#### 4.1 缓存命中信息（响应 Header）
仅在 **`sites/:id/pages` 接口** 且开启缓存时，响应中会返回以下两个 Header：
* `X-Baklib-Cache` → `MISS` 或 `HIT`
* `Age` → 缓存存在时间（单位：秒）
示例：
```http
X-Baklib-Cache: HIT
Age: 120
```
说明：该请求命中缓存，缓存已存在 **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 过期时间优先级与计算
资源 URL 的最终过期时间按以下优先级确定：
1. 若设置 **`DAM_URL_TTL`**：
```
URL 过期时间 = DAM_URL_TTL
```
2. 否则，若同时设置 **`FROM_CACHE_TTL`** 和 **`DAM_URL_TTL_DELAY_AFTER_CACHE`**：
```
URL 过期时间 = FROM_CACHE_TTL + DAM_URL_TTL_DELAY_AFTER_CACHE
```
3. 否则，若仅设置 **`FROM_CACHE_TTL`**：
```
URL 过期时间 = FROM_CACHE_TTL + 600（10 分钟）
```
4. 仅开启缓存，未设置其他参数：
```
URL 过期时间 = 默认FROM_CACHE_TTL(2小时) + 600（10 分钟）
```
#### 5.2 使用示例
```bash
# 直接指定 URL 过期时间为 1800 秒（最高优先级）
DAM_URL_TTL=1800
# 缓存 300 秒，缓存过期后希望 URL 额外存活 600 秒
FROM_CACHE_TTL=300
DAM_URL_TTL_DELAY_AFTER_CACHE=600
# 实际 URL 过期时间 = 300 + 600 = 900 秒
```