hongben-server/modules/fmode-tikhub-server/docs/usage.md

@fmode/tikhub-server 使用指南

本模块封装了 TikHub API 的调用，支持在 Node.js/Express 服务端直接集成 TikTok 数据采集能力。

1. 安装

确保已安装依赖：

npm install axios express
# 或者
bun install axios express

2. 快速开始

方式一：作为 Express 路由挂载 (推荐)

最简单的使用方式是将模块提供的路由直接挂载到您的 Express 应用中。

import express from 'express';
import { createTikHubRouter } from '../modules/fmode-tikhub-server/src/mod';

const app = express();

// 挂载路由到 /api/tikhub 路径下
// 默认使用内置的 API Key 和 Base URL
app.use('/api/tikhub', createTikHubRouter());

// 如果需要自定义配置 (例如更换 API Key)
/*
app.use('/api/tikhub', createTikHubRouter({
  apiKey: 'YOUR_CUSTOM_API_KEY',
  serverURL: 'https://api.tikhub.io/api/v1' // 可选
}));
*/

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

API 端点说明

挂载后，您可以通过以下端点访问：

功能	HTTP 方法	路径	参数 (Query)	示例
搜索用户	GET	/search	keyword (必填), cursor	/api/tikhub/search?keyword=cat
用户详情	GET	/users/:uniqueId	无	/api/tikhub/users/tiktok
用户作品	GET	/users/:secUid/posts	count, cursor	/api/tikhub/users/MS4wLjAB.../posts
视频评论	GET	/posts/:videoId/comments	count, cursor	/api/tikhub/posts/728.../comments

---

方式二：在代码中直接调用 (Service 模式)

如果您需要在自己的业务逻辑中调用 TikHub API（而不是直接暴露 HTTP 接口），可以使用 TikHubClient 和 TikHubUsersApi 类。

import { TikHubClient, TikHubUsersApi } from '../modules/fmode-tikhub-server/src/mod';

async function main() {
  // 1. 初始化客户端
  const client = new TikHubClient({
    // apiKey: '...' // 可选
  });

  // 2. 创建 API 实例
  const usersApi = new TikHubUsersApi(client);

  try {
    // 示例：搜索用户
    const searchResult = await usersApi.searchUsers({
      keyword: 'elon musk',
      cursor: 0
    });
    console.log('搜索结果:', searchResult);

    // 示例：获取用户详情
    const profile = await usersApi.getUserProfile({
      uniqueId: 'elonmusk' // TikTok handle
    });
    console.log('用户详情:', profile);

  } catch (error) {
    console.error('API 调用失败:', error);
  }
}

main();

3. 类型定义

模块导出了完整的 TypeScript 类型定义，方便开发使用。

import { 
  SearchUsersParams, 
  GetUserProfileParams, 
  TikHubResponse 
} from '../modules/fmode-tikhub-server/src/types';

4. 配置说明

TikHubConfig 接口支持以下选项：

• apiKey: (可选) TikHub API Key。如果不传，将使用模块内置的默认 Key。
• serverURL: (可选) TikHub API 基础地址。默认为 https://api.tikhub.io/api/v1。