# API-Spike-Xiaohongshu.md：小红书热榜到评论抓取链路验证

## 1. 文档信息

- 文档阶段：API Spike 验证
- 验证平台：小红书
- API 服务：TikHub API
- 验证目标：确认「小红书热榜 → 热点相关笔记 → 单篇笔记一级评论」链路可跑通
- 验证结论：链路已跑通，可作为 MVP 阶段小红书评论抓取方案

---

## 2. 最终跑通链路

MVP 阶段小红书抓取采用以下链路：

1. 获取小红书热榜。
2. 从热榜列表中读取真实热榜标题。
3. 使用热榜标题作为关键词搜索小红书笔记。
4. 从搜索结果中优先选择 `comments_count > 0` 的笔记。
5. 使用笔记 `note_id` 获取单篇笔记一级评论。

链路表达：

```text
fetch_hot_list
→ data.data.items[].title
→ search_notes(keyword = hot.title)
→ note.id
→ get_note_comments(note_id)
→ comments
```

---

## 3. 接口一：获取小红书热榜

### 3.1 接口信息

```http
GET https://api.tikhub.io/api/v1/xiaohongshu/web_v2/fetch_hot_list
```

### 3.2 MVP 请求参数

该接口 MVP 阶段不需要额外请求参数。

### 3.3 MVP 需要字段

真实热榜条目位于：

```text
data.data.items[]
```

热榜条目需要读取：

```text
id
title
score
rank_change
type
word_type
```

字段用途：

- `id`：热榜条目原始 ID，作为热点原始标识保存。
- `title`：热榜标题，用于后续关键词搜索笔记。
- `score`：热榜热度值。
- `rank_change`：排名变化。
- `type`：热榜条目类型。
- `word_type`：热榜标签，如「热」或「无」。

注意：

```text
data.data.title
```

是热榜模块标题，例如「搜索发现」，不应作为热榜条目使用。

---

## 4. 接口二：通过热榜标题搜索相关笔记

### 4.1 接口信息

```http
GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/search_notes
```

### 4.2 MVP 请求参数

```text
keyword=<热榜标题>
page=1
sort=general
note_type=0
```

参数含义：

- `keyword`：热榜标题，来自 `data.data.items[].title`。
- `page=1`：第一页搜索结果。
- `sort=general`：综合排序。
- `note_type=0`：不限笔记类型。

### 4.3 MVP 需要字段

搜索结果中的笔记信息位于：

```text
data.data.items[].note
```

笔记条目需要读取：

```text
id
title
desc
type
user
liked_count / nice_count
comments_count
collected_count
shared_count
timestamp / update_time
```

字段用途：

- `id`：笔记 ID，用于后续评论抓取。
- `title`：笔记标题。
- `desc`：笔记正文或摘要。
- `type`：笔记类型，如图文或视频。
- `user`：作者基础信息。
- `liked_count` 或 `nice_count`：点赞数。
- `comments_count`：评论数，用于优先选择有评论的笔记。
- `collected_count`：收藏数。
- `shared_count`：分享数。
- `timestamp` 或 `update_time`：发布时间或更新时间。

---

## 5. 接口三：获取单篇笔记一级评论

### 5.1 接口信息

```http
GET https://api.tikhub.io/api/v1/xiaohongshu/app_v2/get_note_comments
```

### 5.2 MVP 请求参数

```text
note_id=<笔记 id>
cursor=
index=0
pageArea=UNFOLDED
sort_strategy=latest_v2
```

参数含义：

- `note_id`：笔记 ID，来自搜索结果中的 `data.data.items[].note.id`。
- `cursor`：评论分页游标，第一页为空。
- `index=0`：第一页索引。
- `pageArea=UNFOLDED`：评论展开区域。
- `sort_strategy=latest_v2`：按最新评论排序。

### 5.3 MVP 需要字段

评论列表位于：

```text
data.data.comments[]
```

评论条目需要读取：

```text
id / comment_id
content / text
user_info / user
like_count
create_time
```

字段用途：

- `id` 或 `comment_id`：评论 ID，用于去重和关联。
- `content` 或 `text`：评论正文。
- `user_info` 或 `user`：评论作者基础信息。
- `like_count`：评论点赞数。
- `create_time`：评论发布时间。

---

## 6. 已验证样例

本次验证中，小红书链路已成功跑通以下样例：

```text
热榜标题：耗时三年拍下古诗词里的中国
搜索笔记：张岱笔下的江南夜色，一字入画
note_id：6a4319410000000217023ee7
评论 ID：6a433517000000001403b657
评论内容：都很美啊！[点赞R]
```

该样例证明：

1. 可以获取小红书真实热榜条目。
2. 可以基于热榜标题搜索到相关笔记。
3. 可以从笔记搜索结果中获取 `note_id`。
4. 可以基于 `note_id` 获取笔记一级评论。

---

## 7. MVP 开发结论

小红书侧 MVP 抓取链路采用：

```text
热榜接口
→ 热榜标题关键词搜索笔记
→ 笔记评论接口
```

开发阶段应注意：

1. 热榜真实条目应从 `data.data.items[]` 读取，不要使用外层模块标题。
2. 搜索结果不要无脑取第一条，应优先选择 `comments_count > 0` 的笔记。
3. 笔记评论接口返回空评论时不一定是接口失败，可能是该笔记本身无评论。
4. 外部 API 字段映射应保持可调整，并保留原始 JSON 响应用于排障。

MVP 阶段建议默认抓取规模：

```text
Top 5 热榜
× 每个热榜最多 5 篇笔记
× 每篇笔记最多 50 条一级评论
```

正式实现中应支持配置：

```text
hot_limit
note_limit_per_hot
comment_limit_per_note
```

---

## 8. 后续文档衔接

本 API Spike 结果用于支撑后续文档：

1. `FeatureSummary.md`：拆解小红书抓取相关功能模块。
2. `DevelopmentPlan.md`：设计后端服务、任务流程、数据模型和异常处理。
3. `TDD`：围绕字段映射、分页、空评论、去重和任务状态编写测试。
4. `Tasks`：拆分具体开发任务。