multi-platform-media-manage/server/python/PAGING_LOGIC.md

小红书作品自动分页逻辑说明

页数计算逻辑

1. 页数统计变量

在 get_all_works 方法中，有两个关键的计数变量：

• iters: 总请求次数（包括失败的请求）

  • 初始值：0
  • 每次循环：iters += 1
  • 最大限制：800 次（max_iters = 800）

• page_count: 成功获取到的页数（只统计有作品的页面）

  • 初始值：0
  • 只有当 notes 不为空时：page_count += 1
  • 这是实际成功获取到的页数，不是总页数

2. 总页数计算

总页数可以通过以下方式计算：

总页数 = ceil(总作品数 / 每页大小)

其中：

• 总作品数 (total): 从 API 返回的声明总数，可能来自：

  • tags 中的 special.note_time_desc 的 notes_count
  • tags 中其他 tag 的 notes_count 最大值
  • data.total 或 data.total_count
  • data.page.total 或 data.page.totalCount
    

• 每页大小 (api_page_size): 固定为 20

3. 分页流程

开始循环 (最多 800 次)
  ↓
iters += 1 (总请求次数)
  ↓
调用 API: fetch_notes_page(cursor)
  ↓
检查响应是否成功
  ├─ 失败 → 如果是第一次请求，切换到滚动模式
  └─ 成功 → 继续
      ↓
检查 notes 是否为空
  ├─ 为空 → 停止分页
  └─ 不为空 → page_count += 1 (成功页数+1)
      ↓
解析作品并去重
  ↓
检查是否获取完所有作品
  ├─ 累计作品数 >= 总数 → 停止分页
  └─ 继续 → 更新 cursor，继续下一页

4. 分页统计输出

在分页完成后，会输出以下统计信息：

分页统计: 总请求次数={iters}, 成功获取页数={page_count}, 累计作品数={len(works)}, 声明总数={total}

示例：

• 总请求次数：20（包括所有请求，即使某些请求返回空）
• 成功获取页数：18（只有返回作品的页面才计数）
• 累计作品数：360（实际获取到的作品总数）
• 声明总数：368（API 声明的总作品数）

5. 页数计算示例

假设账号有 368 个作品：

总作品数 = 368
每页大小 = 20
理论总页数 = ceil(368 / 20) = 19 页

实际执行：
- 第 1-18 页：每页 20 个作品，共 360 个
- 第 19 页：8 个作品
- page_count = 19（成功获取的页数）
- iters = 19（总请求次数，如果都成功的话）

日志输出位置

Python 服务日志

Python 服务的日志通过 print(..., flush=True) 输出到控制台（标准输出）。

要查看完整的分页日志，需要：

1. 确保 Python 服务正在运行

   cd server/python
   python app.py
   

   1. 查看 Python 服务的控制台输出
   2. 日志会实时输出到运行 Python 服务的终端窗口

   3. 所有 print 语句都会立即输出（因为使用了 flush=True）

   4. 关键日志标识

   5. ========== 开始自动分页获取作品 ==========: 分页开始

   6. 第 {iters} 次请求 (cursor={cursor}): 每次请求

   7. ✅ 第 {page_count} 页获取成功: 成功获取的页

   8. 📊 分页统计: 分页完成后的统计信息

   Node.js 日志

   Node.js 端的日志会输出到：

   • 控制台（开发环境）
   • 日志文件（生产环境）：
   • server/logs/combined.log - 所有日志
   • server/logs/error.log - 错误日志

   调试建议

   如果 Python API 返回 0 个作品，可能的原因：

   1. Cookie 格式问题
   2. 检查 Node.js 传递给 Python 的 Cookie 格式是否正确

   3. Python 期望 JSON 格式的 Cookie 数组

   4. 登录状态失效

   5. 检查账号的 Cookie 是否过期

   6. 查看 Python 日志中是否有 "Cookie 已过期" 的错误

   7. API 调用失败

   8. 查看 Python 日志中的错误信息

   9. 检查网络连接和 API 响应

   10. 页面加载问题

   11. 检查是否成功访问笔记管理页面

   12. 查看是否有导航超时的错误

   查看日志的方法

   方法 1: 直接查看 Python 服务控制台

   运行 Python 服务的终端窗口会显示所有日志。

   方法 2: 重定向日志到文件

   python app.py > python.log 2>&1
   

然后查看 python.log 文件。

方法 3: 使用测试脚本

运行测试脚本时，Python 服务的日志会输出到运行 Python 服务的终端窗口：

# 终端 1: 运行 Python 服务
cd server/python
python app.py

# 终端 2: 运行测试脚本
cd server
pnpm exec tsx src/scripts/test-xhs-works-sync.ts 35

Python 服务的日志会在终端 1 中显示。