hongben-server/modules/fmode-tikhub-server/docs

fmode-tikhub-server 模块说明

1. 模块概述

fmode-tikhub-server 是一个独立的后端集成模块，旨在为项目提供 TikTok 数据采集与交互能力。它封装了 TikHub 第三方 API，通过标准化的 RESTful 接口对外提供服务，屏蔽了底层 API Key 管理、签名机制和请求细节。

核心作用

1. API 代理与封装：将 TikHub 的原始 API 封装为本地服务接口，前端无需直接与第三方服务交互，避免了 API Key 泄露风险。
2. 统一鉴权：内置了 API Key 和 Token 管理，确保请求的合法性。
3. 简化调用：提供了语义化的接口（如 /search, /users/:id），比原始 API 更易于理解和使用。
4. 易于集成：设计为 Express 中间件/路由模块，可插拔式地集成到任何 Node.js/Express 主应用中。

---

2. 接口能力

模块当前开放了以下核心能力：

• 用户搜索 (/search): 根据关键词搜索 TikTok 用户。
• 用户详情 (/users/:uniqueId): 获取指定用户的详细 Profile 信息。
• 作品列表 (/users/:secUid/posts): 分页获取用户的视频作品。
• 评论采集 (/posts/:videoId/comments): 获取指定视频的评论数据。

---

3. 前端集成指南

3.1 前置条件

在主应用的前端调用此模块前，请确保：

1. 后端服务已启动：主应用（如 server.ts）必须已启动，并且已挂载了本模块的路由。
   • 默认挂载路径：/api/tikhub
   • 检查方法：访问 http://localhost:10003/api/tikhub/search?keyword=test 应返回 JSON 数据。
2. 网络连通性：前端环境（浏览器或 App）能够访问到后端服务的端口（默认 10003）。

3.2 调用注意事项

1. Base URL 配置：

   • 前端请求的 Base URL 应指向主应用的地址，例如 http://localhost:10003/api/tikhub（开发环境）或 https://api.yourdomain.com/api/tikhub（生产环境）。
   • 不要直接请求 api.tikhub.io，否则会跨域且暴露 API Key。

2. 参数传递：

   • 所有接口均为 GET 请求。
   • 参数通常通过 Query String（如 ?keyword=abc）或 URL Path（如 /users/elonmusk）传递。
   • 分页参数 cursor 初始传 0，后续请求使用上一次接口返回的 cursor 值。

3. 跨域 (CORS)：

   • 如果前端与后端部署在不同域名/端口，后端主应用必须配置 CORS 中间件允许前端域名的访问。

3.3 示例代码 (Frontend Service)

建议在前端项目中封装一个 Service 层：

// services/tiktok.service.ts

// 根据环境动态配置 API 地址
const API_ROOT = import.meta.env.VITE_API_URL || 'http://localhost:10003';
const TIKHUB_BASE = `${API_ROOT}/api/tikhub`;

export const TikTokService = {
  // 搜索用户
  async search(keyword: string) {
    const res = await fetch(`${TIKHUB_BASE}/search?keyword=${encodeURIComponent(keyword)}`);
    return await res.json();
  },

  // 获取详情
  async getProfile(uniqueId: string) {
    const res = await fetch(`${TIKHUB_BASE}/users/${uniqueId}`);
    return await res.json();
  }
};

---

4. 维护与扩展

• API Key 更换：如果 Key 失效，请在 src/client.ts 中更新 API_KEY 常量，或在初始化路由时传入新 Key。
• 新增接口：如需支持更多 TikHub 功能，请参考 src/api/users.ts 扩展新的方法，并在 src/routes.ts 中添加对应路由。