小红书笔记评论 API 接口深度解析（带全套 JSON 示例・技术实战版）
从接口路径到异常处理，再到结构化入库，本文对小红书评论 API 进行了全面拆解。无论你是从事舆情监控、竞品分析，还是仅需批量拉取评论做数据统计，这篇文章都能帮你节省大量试错时间。
一、接口基础说明
1. 接口基础信息
接口路径为
/api/v1/note/comment/list，这是小红书开放平台的标准评论接口。
请求方式为 POST，鉴权需在 Header 中添加
Authorization: Bearer access_token，采用 OAuth2.0 令牌鉴权机制。分页规则较为特殊——使用游标 cursor 分页，传统的页码 page 已不再支持。首次请求时 cursor 传入空字符串，后续页使用上一页返回的 cursor 值。
sort 参数支持
hot（按热度排序）或
time（按时间倒序），
page_size 单页可设置 1~50 条。官方 QPS 限制为 5 次/秒，调用频率过高将被限流。
下面是一个请求入参的 JSON 示例：
```json
{
"note_id": "649c46ab000000002702ad36",
"cursor": "",
"page_size": 20,
"sort": "hot",
"need_sub_comment": true
}
```
具体参数说明见下表：
| 参数 | 必填 | 说明 |
| note_id | 是 | 笔记唯一标识符（32 位字符串，可从笔记链接中提取） |
| cursor | 否 | 分页游标，空字符串表示第一页 |
| page_size | 否 | 每页评论数量，默认 20 条 |
| sort | 否 | hot 表示按热度排序，time 表示按时间倒序 |
| need_sub_comment | 否 | true 表示同时返回楼中楼子评论 |
二、接口原生返回完整 JSON（真实脱敏样例）
下面展示接口原生返回的 JSON 结构。其层级较深，子评论嵌套在内部，时间字段采用 Unix 时间戳，用户信息嵌入在评论对象中——若想直接存入数据库或进行数据分析，几乎不可行。
```json
{
"code": 200,
"msg": "success",
"request_id": "req_987654321abc",
"data": {
"note_id": "649c46ab000000002702ad36",
"total_comment": 1256,
"cursor": "crs_20260603_001",
"has_more": true,
"comments": [
{
"comment_id": "com_1122334455",
"content": "油皮亲妈！上脸清爽不闷痘，已经囤两瓶啦?",
"create_time": 1744289620,
"like_count": 326,
"reply_count": 18,
"is_top": true,
"user": {
"user_id": "u_589abc789",
"nickname": "油痘肌避雷君",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/abc123.jpg",
"is_creator": false
},
"sub_comments": [
{
"comment_id": "sub_998877",
"content": "想问多少钱入手的？",
"create_time": 1744290120,
"like_count": 12,
"reply_user_id": "u_589abc789",
"user": {
"user_id": "u_321def654",
"nickname": "奶茶不加冰",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/def456.jpg"
}
}
]
},
{
"comment_id": "com_5566778899",
"content": "@小丸子 敏感肌能用吗？",
"create_time": 1744291200,
"like_count": 45,
"reply_count": 0,
"is_top": false,
"user": {
"user_id": "u_789ghi123",
"nickname": "护肤小白日常",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/ghi789.jpg",
"is_creator": false
},
"sub_comments": []
}
]
}
}
```
顶层字段释义
-
code：200 表示请求成功；401 表示 token 已失效；403 表示权限不足；429 表示接口被限流
-
request_id：请求唯一标识，用于接口异常排查日志
-
data.total_comment：笔记全量评论总数
-
data.has_more：true 表示存在下一页数据，可继续游标翻页
三、原生 JSON 痛点
原生 JSON 存在以下几个明显的痛点：
- 时间字段为 Unix 时间戳，业务层需手动格式化为
yyyy-MM-dd HH:mm:ss；
- 主评论和子评论嵌套在一起，子评论归属关系不直观，解析时容易绕晕；
- 用户信息内嵌在 comment 对象里，字段分散，不利于分表存储（评论表 vs 用户表）；
- 置顶标识
is_top 零散在各条评论中，想批量筛选出所有置顶评论需要额外遍历；
- @关联用户没有结构化字段，@文本全混在 content 里，提取关键词得自己挖。
四、结构化解析后标准 JSON（落地入库模型）
针对上述问题，最直接的解决方案是对原生 JSON 进行结构化解析，将其拆分为扁平化格式。将主评论与子评论分离，时间格式统一，用户信息整合到独立对象中。这样生成的 JSON 可直接存入 MySQL 或 Elasticsearch，用于舆情分析、竞品评论统计等场景十分便捷。
```json
{
"note_id": "649c46ab000000002702ad36",
"total_comment": 1256,
"next_cursor": "crs_20260603_001",
"has_more": true,
"main_comments": [
{
"comment_id": "com_1122334455",
"comment_type": "main",
"content": "油皮亲妈！上脸清爽不闷痘，已经囤两瓶啦?",
"create_time_stamp": 1744289620,
"create_time": "2025-06-10 15:53:40",
"like_count": 326,
"reply_count": 18,
"is_top": true,
"user_info": {
"user_id": "u_589abc789",
"nickname": "油痘肌避雷君",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/abc123.jpg"
},
"sub_comments": [
{
"comment_id": "sub_998877",
"comment_type": "sub",
"parent_comment_id": "com_1122334455",
"content": "想问多少钱入手的？",
"create_time_stamp": 1744290120,
"create_time": "2025-06-10 16:02:00",
"like_count": 12,
"reply_target_uid": "u_589abc789",
"user_info": {
"user_id": "u_321def654",
"nickname": "奶茶不加冰",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/def456.jpg"
}
}
]
},
{
"comment_id": "com_5566778899",
"comment_type": "main",
"content": "@小丸子 敏感肌能用吗？",
"create_time_stamp": 1744291200,
"create_time": "2025-06-10 16:13:20",
"like_count": 45,
"reply_count": 0,
"is_top": false,
"user_info": {
"user_id": "u_789ghi123",
"nickname": "护肤小白日常",
"a vatar": "https://sns-a vatar-qc.xhscdn.com/a vatar/ghi789.jpg"
},
"sub_comments": []
}
]
}
```
五、核心解析实战要点
在实际解析过程中，有几个关键细节需要注意：
- **时间格式化**：将
create_time 时间戳统一转换为标准日期字符串，便于后续按天或按月统计评论数量。
- **父子评论绑定**：为子评论新增
parent_comment_id 字段，直接关联所属主评论的 ID，数据库内关联查询一步到位。
- **用户信息剥离**：将用户信息封装为
user_info 对象，方便后续与用户画像库关联。
- **空值容错**：
sub_comments 在没有回复时默认返回空数组，避免数组遍历时抛出空指针异常。
- **分页闭环**：每次请求保存返回的
cursor，循环遍历直到
has_more 为 false，即可拉取笔记下全部评论。
六、接口异常返回 JSON 示例（错误处理参考）
接口调用难免遇到异常情况，如 token 过期或限流是常见问题。以下两个示例展示了最常见的异常场景：
```json
{
"code": 401,
"msg": "access_token已过期，请重新授权",
"request_id": "req_err_123456",
"data": {}
}
```
```json
{
"code": 429,
"msg": "接口调用超限，限流冷却10s",
"request_id": "req_limit_789",
"data": {}
}
```
七、落地业务场景
解析后的评论数据可应用于多种实际业务场景：
- **品牌舆情监控**：抓取评论关键词，统计好评与差评占比，分析用户对产品的真实痛点。
- **竞品数据分析**：对标同品类笔记的评论量、互动率，测算竞品的种草热度。
- **用户问答收集**：筛选出带有价格、使用方法等常见问题的评论，整理成 FAQ 知识库。
八、精简 Python 解析代码（配套实战）
最后，提供一段可直接运行的 Python 解析代码，核心逻辑是对原生 JSON 进行扁平化转换，已添加注释，稍作修改即可使用。
```python
import time
def parse_xhs_comment(raw_json):
res = {}
resp_data = raw_json.get("data", {})
res["note_id"] = resp_data.get("note_id")
res["total_comment"] = resp_data.get("total_comment",0)
res["next_cursor"] = resp_data.get("cursor","")
res["has_more"] = resp_data.get("has_more",False)
main_list = []
#遍历主评论
for item in resp_data.get("comments",[]):
main = {
"comment_id":item["comment_id"],
"comment_type":"main",
"content":item["content"],
"create_time_stamp":item["create_time"],
"create_time":time.strftime("%Y-%m-%d %H:%M:%S",time.localtime(item["create_time"])),
"like_count":item["like_count"],
"reply_count":item["reply_count"],
"is_top":item["is_top"],
"user_info":item["user"],
"sub_comments":[]
}
#解析子评论
subs = []
for sub in item.get("sub_comments",[]):
sub_item = {
"comment_id":sub["comment_id"],
"comment_type":"sub",
"parent_comment_id":main["comment_id"],
"content":sub["content"],
"create_time_stamp":sub["create_time"],
"create_time":time.strftime("%Y-%m-%d %H:%M:%S",time.localtime(sub["create_time"])),
"like_count":sub["like_count"],
"reply_target_uid":sub.get("reply_user_id",""),
"user_info":sub["user"]
}
subs.append(sub_item)
main["sub_comments"] = subs
main_list.append(main)
res["main_comments"] = main_list
return res
