# 小红书搜索模块 ## 快速开始 ### Python API（推荐） ```python from script.search import search_xiaohongshu # 基本搜索 data = search_xiaohongshu("产品测试") # 使用数据 for note in data['notes']: print(f"{note['title']} - {note['like_count']} 赞") ``` ### 命令行工具 ```bash python script/search/xiaohongshu_search.py --keyword "产品测试" ``` --- ## API 文档 ### 函数签名 ```python data = search_xiaohongshu( keyword: str, # 必填：搜索关键词 content_type="不限", # 可选：不限、视频、图文 sort_type="综合", # 可选：综合、最新、最多点赞、最多评论 publish_time="不限", # 可选：不限、一天内、一周内、半年内 page=1, # 可选：页码（自动翻页） force=False # 可选：强制刷新 ) ``` ### 返回值 ```python { "search_params": { # 搜索参数 "keyword": "产品测试", "content_type": "视频", "sort_type": "最新", "publish_time": "一周内", "cursor": "", "page": 1, "timestamp": "20251113_133258" }, "has_more": True, # 是否有更多 "next_cursor": "...", # 下一页游标（内部使用） "notes": [...] # 笔记列表 } ``` ### 笔记字段 | 字段 | 说明 | |------|------| | channel_content_id | 笔记ID | | link | 笔记链接 | | title | 标题 | | desc | 摘要（搜索接口返回） | | body_text | 完整正文（需详情接口） | | channel_account_name | 作者名称 | | channel_account_id | 作者ID | | like_count | 点赞数 | | comment_count | 评论数 | | collect_count | 收藏数 | | shared_count | 分享数 | | images | 图片URL列表 | | video | 视频链接（需详情接口） | | content_type | 内容类型 | --- ## 使用示例 ### 1. 基本搜索 ```python from script.search import search_xiaohongshu data = search_xiaohongshu("产品测试") print(f"找到 {len(data['notes'])} 条笔记") for note in data['notes']: print(f"- {note['title']} ({note['like_count']} 赞)") ``` ### 2. 带参数搜索 ```python data = search_xiaohongshu( keyword="产品测试", content_type="视频", sort_type="最新", publish_time="一周内" ) ``` ### 3. 翻页（自动处理） ```python # 直接指定页码，自动处理 cursor page1 = search_xiaohongshu("产品测试", page=1) page2 = search_xiaohongshu("产品测试", page=2) page3 = search_xiaohongshu("产品测试", page=3) ``` ### 4. 强制刷新 ```python # 忽略缓存，重新请求 API data = search_xiaohongshu("产品测试", force=True) ``` ### 5. 批量搜索 ```python keywords = ["产品测试", "软件测试", "性能测试"] for keyword in keywords: data = search_xiaohongshu(keyword) print(f"{keyword}: {len(data['notes'])} 条笔记") ``` ### 6. 数据分析 ```python from script.search import search_xiaohongshu def analyze_topic(keyword): """分析话题热度""" data = search_xiaohongshu( keyword=keyword, sort_type="最新", publish_time="一周内" ) notes = data['notes'] total_likes = sum(n['like_count'] for n in notes) avg_likes = total_likes / len(notes) if notes else 0 print(f"关键词: {keyword}") print(f"笔记数: {len(notes)}") print(f"总点赞: {total_likes}") print(f"平均点赞: {avg_likes:.1f}") analyze_topic("产品测试") ``` --- ## 命令行使用 ### 基本搜索 ```bash python script/search/xiaohongshu_search.py --keyword "产品测试" ``` ### 带参数搜索 ```bash python script/search/xiaohongshu_search.py \ --keyword "产品测试" \ --content-type "视频" \ --sort-type "最新" \ --publish-time "一周内" ``` ### 强制刷新 ```bash python script/search/xiaohongshu_search.py --keyword "产品测试" --force ``` ### 禁用缓存 ```bash python script/search/xiaohongshu_search.py --keyword "产品测试" --no-cache ``` ### 完整参数 | 参数 | 默认值 | 说明 | |------|--------|------| | --keyword | 必填 | 搜索关键词 | | --content-type | "不限" | 内容类型：不限、视频、图文 | | --sort-type | "综合" | 排序：综合、最新、最多点赞、最多评论 | | --publish-time | "不限" | 时间：不限、一天内、一周内、半年内 | | --page | 1 | 页码 | | --cursor | "" | 翻页游标 | | --force | False | 强制刷新 | | --no-cache | False | 禁用缓存 | | --results-dir | data/search | 输出目录 | | --timeout | 30 | 超时时间（秒） | | --max-retries | 3 | 最大重试次数 | | --retry-delay | 2 | 重试延迟（秒） | --- ## 核心特性 ### 1. 自动缓存（默认开启） 相同的搜索参数会自动使用缓存： ```python # 第一次：请求 API data1 = search_xiaohongshu("产品测试") # 第二次：使用缓存 data2 = search_xiaohongshu("产品测试") # 瞬间返回 # 强制刷新 data3 = search_xiaohongshu("产品测试", force=True) ``` ### 2. 自动重试（失败重试 3 次） - 超时错误：自动重试 - 连接错误：自动重试 - 5xx 服务器错误：自动重试 - 4xx 客户端错误：不重试 指数退避策略：2秒 → 4秒 → 8秒 ### 3. 自动保存（后台完成） 搜索结果自动保存到 `data/search/xiaohongshu_search/` 目录结构： ``` data/search/xiaohongshu_search/ └── {关键词}/ ├── raw/ # 原始数据 │ └── {时间戳}_page{页码}_{参数}.json └── clean/ # 清洗数据 └── {时间戳}_page{页码}_{参数}.json ``` 文件名示例： - 默认参数：`20251113_133315_page1_不限_综合_不限.json` - 自定义参数：`20251113_133258_page1_视频_最新_一周内.json` ### 4. 自动翻页（内部处理 cursor） ```python # 无需手动管理 cursor page1 = search_xiaohongshu("产品测试", page=1) page2 = search_xiaohongshu("产品测试", page=2) # 自动获取 page1 的 cursor page3 = search_xiaohongshu("产品测试", page=3) # 自动获取 page2 的 cursor ``` ### 5. 关键词自动清理 特殊字符会自动处理，避免文件名冲突： ```python # 自动清理特殊字符 search_xiaohongshu("测试/产品:问题?") # → 文件夹名：测试_产品_问题_ ``` --- ## 数据格式 ### Clean 数据（推荐使用） ```json { "search_params": { "keyword": "产品测试", "content_type": "视频", "sort_type": "最新", "publish_time": "一周内", "cursor": "", "page": 1, "timestamp": "20251113_133258" }, "has_more": true, "next_cursor": "2@2fl1kgnh0gdx2oarsbpxc@...", "notes": [ { "channel_content_id": "6915588b00000000040143b5", "link": "https://www.xiaohongshu.com/explore/6915588b00000000040143b5", "title": "笔记标题", "desc": "笔记摘要...", "body_text": "", "channel_account_name": "作者名称", "channel_account_id": "5b1e2c0811be10762dee6859", "like_count": 2, "comment_count": 0, "collect_count": 1, "shared_count": 0, "images": ["https://..."], "video": "", "content_type": "video" } ] } ``` ### Raw 数据 完整的 API 响应，包含所有元数据和嵌套结构。 --- ## 注意事项 ### 关于 desc 和 body_text - **desc**：搜索接口返回的摘要（已截断） - **body_text**：完整正文（空，需调用详情接口 `get_xhs_detail_by_note_id` 获取） ### 关于 video - 搜索接口不返回视频链接 - 需要调用详情接口获取 ### 频率限制 - 建议每次搜索间隔 1-2 秒 - 避免短时间内大量请求 --- ## 常见问题 ### Q: 如何获取完整正文？ A: 搜索接口只返回摘要，完整正文需要调用详情接口： ```python # 1. 先搜索获取笔记列表 data = search_xiaohongshu("产品测试") # 2. 对感兴趣的笔记调用详情接口 note_id = data['notes'][0]['channel_content_id'] # 调用 get_xhs_detail_by_note_id(note_id) 获取完整正文 ``` ### Q: 缓存如何清理？ A: - 方式1：手动删除 `data/search/xiaohongshu_search/{关键词}/` 目录 - 方式2：使用 `force=True` 参数强制刷新 ### Q: 如何判断是否使用了缓存？ A: 看控制台输出： - 使用缓存：`✓ 使用缓存数据: ...` - 请求 API：`正在搜索关键词: ... (尝试 1/3)` ### Q: 翻页时 cursor 在哪里？ A: cursor 已自动处理，无需手动管理： ```python # ✅ 推荐：直接指定页码 page2 = search_xiaohongshu("产品测试", page=2) # ❌ 不需要：手动传 cursor # page2 = search_xiaohongshu("产品测试", cursor="...") ``` --- ## 技术细节 ### 内部默认配置 - **超时时间**：30 秒 - **最大重试**：3 次 - **重试延迟**：2 秒（指数增长） - **缓存开关**：默认开启 - **输出目录**：`data/search` ### 缓存机制 - 基于搜索参数生成缓存键（keyword + content_type + sort_type + publish_time + cursor） - 相同参数返回最新的缓存文件 - 按文件修改时间排序 ### 自动翻页原理 ```python # page=2 时自动执行： # 1. 读取 page=1 的缓存 # 2. 提取 next_cursor # 3. 使用 cursor 请求 page=2 ```