hot_comment_radar/docs/API-Spike-Xiaohongshu.md

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

1. 文档信息

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

---

2. 最终跑通链路

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

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

链路表达：

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

---

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

3.1 接口信息

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

3.2 MVP 请求参数

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

3.3 MVP 需要字段

真实热榜条目位于：

data.data.items[]

热榜条目需要读取：

id
title
score
rank_change
type
word_type

字段用途：

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

注意：

data.data.title

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

---

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

4.1 接口信息

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

4.2 MVP 请求参数

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

参数含义：

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

4.3 MVP 需要字段

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

data.data.items[].note

笔记条目需要读取：

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 接口信息

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

5.2 MVP 请求参数

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 需要字段

评论列表位于：

data.data.comments[]

评论条目需要读取：

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. 已验证样例

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

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

该样例证明：

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

---

7. MVP 开发结论

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

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

开发阶段应注意：

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

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

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

正式实现中应支持配置：

hot_limit
note_limit_per_hot
comment_limit_per_note

---

8. 后续文档衔接

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

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