266 lines
5.5 KiB
Markdown
266 lines
5.5 KiB
Markdown
# 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`：拆分具体开发任务。
|