Twitter API 迁移计划

本文档概述了将 Twitter API SaaS 功能从 /Users/jwenlee/dev/code/aidir-fun/twitterapi 迁移到新 MkSaaS 框架的完整迁移策略。

执行摘要

源项目: Twitter API SaaS 服务 (Next.js 15.5.9) 目标框架: MkSaaS 模板 (当前版本) 迁移范围: 全栈 API 包装服务,包含订阅管理、速率限制和使用跟踪

需要解决的关键差异

• 支付提供商: LemonSqueezy (源) → Stripe (目标)
• 认证配置: 仅 GitHub (源) → Google + GitHub (目标)
• 数据库架构: 额外 7 个 API 专用表
• API 端点: 10 个 Twitter API 包装端点
• 文档: 10 个双语 MDX 文件

第一阶段: 数据库架构迁移

1.1 需要创建的新表

优先级: 关键 | 预估复杂度: 中等

在 src/db/schema.ts 中创建以下表:

API 密钥管理

apiKey {
  id: uuid (主键)
  userId: uuid (外键 → user.id)
  key: string (唯一, 索引)
  name: string
  enabled: boolean (默认: true)
  totalRequests: integer (默认: 0)
  lastUsedAt: timestamp
  createdAt: timestamp
  updatedAt: timestamp
}

订阅计划

apiSubscriptionPlan {
  id: uuid (主键)
  name: string
  description: text
  requestQuota: integer
  price: decimal
  interval: enum ('month', 'year', 'lifetime')
  features: jsonb
  active: boolean (默认: true)
  createdAt: timestamp
  updatedAt: timestamp
}

用户订阅

apiSubscription {
  id: uuid (主键)
  userId: uuid (外键 → user.id)
  planId: uuid (外键 → apiSubscriptionPlan.id)
  status: enum ('active', 'cancelled', 'expired')
  requestsUsed: integer (默认: 0)
  requestsLimit: integer
  currentPeriodStart: timestamp
  currentPeriodEnd: timestamp
  cancelAtPeriodEnd: boolean (默认: false)
  createdAt: timestamp
  updatedAt: timestamp
}

速率限制

apiRateLimit {
  id: uuid (主键)
  apiKeyId: uuid (外键 → apiKey.id)
  windowStart: timestamp
  windowType: enum ('minute', 'hour', 'day')
  requestCount: integer (默认: 0)
  createdAt: timestamp
  updatedAt: timestamp
}

请求日志

apiRequestLog {
  id: uuid (主键)
  apiKeyId: uuid (外键 → apiKey.id)
  endpoint: string
  method: string
  statusCode: integer
  responseTime: integer (毫秒)
  ipAddress: string
  userAgent: text
  createdAt: timestamp
}

响应缓存

apiCache {
  id: uuid (主键)
  cacheKey: string (唯一, 索引)
  endpoint: string
  params: jsonb
  response: jsonb
  expiresAt: timestamp
  createdAt: timestamp
}

使用分析

apiUsageLog {
  id: uuid (主键)
  userId: uuid (外键 → user.id)
  apiKeyId: uuid (外键 → apiKey.id)
  endpoint: string
  creditsUsed: integer
  requestParams: jsonb
  responseTime: integer
  success: boolean
  errorMessage: text
  createdAt: timestamp
}

1.2 迁移步骤

1. 创建架构定义

   • 在 src/db/schema.ts 中添加表定义
   • 定义关系和索引
   • 添加 TypeScript 类型

2. 生成迁移

   pnpm db:generate

3. 审查迁移 SQL

   • 检查 drizzle/ 目录中生成的 SQL
   • 验证索引和约束

4. 应用迁移

   pnpm db:migrate

5. 填充初始数据

   • 创建默认订阅计划
   • 设置速率限制配置

第二阶段: 环境配置

2.1 新环境变量

添加到 .env 和 env.example:

# Twitter API 配置
TWITTER_BEARER_TOKEN=your_token_here
TWITTER_CACHE_ENABLED=true
TWITTER_CACHE_TTL=300
TWITTER_RATE_LIMIT_ENABLED=true

# 速率限制配置
RATE_LIMIT_MINUTE=60
RATE_LIMIT_HOUR=1000
RATE_LIMIT_DAY=10000

# API 配置
API_BASE_PATH=/api/twitter
API_KEY_PREFIX=tw_

2.2 配置更新

更新 src/config/website.tsx:

1. 添加 Twitter API 定价计划

   {
     id: 'free',
     name: '免费',
     price: { monthly: 0 },
     features: ['100 次 API 请求', '基础支持'],
     requestQuota: 100
   },
   {
     id: 'pro',
     name: '专业版',
     price: { monthly: 1, yearly: 10, lifetime: 10 },
     features: ['30 次请求/月', '优先支持'],
     requestQuota: 30
   }

2. 添加积分套餐

   goods: [
     { id: 'credits_10k', price: 100, credits: 10000 },
     { id: 'credits_1m', price: 9000, credits: 1000000 },
     { id: 'credits_2m', price: 16000, credits: 2000000 }
   ]

第三阶段: API 基础设施

3.1 核心服务

在 src/lib/api/ 中创建:

middleware.ts

• API 密钥认证
• 速率限制检查
• 配额验证
• 请求日志记录
• 错误处理

handler.ts

• 统一 API 请求处理器
• 使用 Zod 进行输入验证
• 响应格式化
• 错误标准化

rate-limit-service.ts

• 分钟/小时/天窗口跟踪
• 分布式速率限制
• 基于密钥的限制
• 基于 IP 的回退

subscription-service.ts

• 配额检查
• 使用跟踪
• 订阅验证
• 积分扣除

cache-service.ts

• 响应缓存
• TTL 管理
• 缓存失效
• 密钥生成

usage-log-service.ts

• 请求日志记录
• 分析数据收集
• 性能跟踪
• 错误日志记录

3.2 API 端点

在 src/app/api/twitter/ 中创建:

1. user-profile/route.ts

   • 通过用户名获取用户资料
   • 参数: screen_name
   • 返回: 用户资料数据

2. user-tweets/route.ts

   • 获取用户推文
   • 参数: user_id, cursor, count
   • 返回: 带分页的推文列表

3. user-tweets-replies/route.ts

   • 获取用户推文和回复
   • 参数: user_id, cursor, count
   • 返回: 组合推文列表

4. followers/route.ts

   • 获取用户粉丝
   • 参数: user_id, cursor, count
   • 返回: 粉丝列表

5. following/route.ts

   • 获取关注的用户
   • 参数: user_id, cursor, count
   • 返回: 关注列表

6. tweet-detail/route.ts

   • 获取推文详情
   • 参数: tweet_id
   • 返回: 带指标的推文详情

7. search/route.ts

   • 搜索推文
   • 参数: query, cursor, count
   • 返回: 搜索结果

8. community-tweets/route.ts

   • 获取社区推文
   • 参数: community_id, cursor, count
   • 返回: 社区推文列表

9. list-latest-tweets/route.ts

   • 获取列表最新推文
   • 参数: list_id, cursor, count
   • 返回: 列表推文

10. token-info/route.ts

    • 获取 API 令牌使用信息
    • 返回: 令牌统计

3.3 API 管理端点

在 src/app/api/apikeys/ 中创建:

1. route.ts - API 密钥的 CRUD 操作
2. usage/hours/route.ts - 最近 24 小时使用情况
3. usage/lastMonths/route.ts - 最近 3 个月使用情况
4. logs/route.ts - 带分页的请求日志
5. stats/route.ts - 使用统计

第四阶段: 用户界面组件

4.1 API 密钥管理

在 src/app/[locale]/(protected)/keys/ 中创建:

page.tsx

• 列出所有 API 密钥
• 创建新密钥对话框
• 重新生成密钥功能
• 启用/禁用切换
• 删除确认
• 使用示例 (header, query, curl)
• 实时测试界面

组件

• api-key-card.tsx - 单个密钥显示
• create-key-dialog.tsx - 密钥创建表单
• usage-examples.tsx - 代码示例
• test-api-interface.tsx - 测试 UI

4.2 API 使用日志

在 src/app/[locale]/(protected)/keys/logs/ 中创建:

page.tsx

• 请求日志表
• 按端点、状态、日期过滤
• 分页
• 导出功能
• 实时更新

4.3 仪表板增强

更新 src/app/[locale]/(protected)/dashboard/page.tsx:

添加以下部分:

• API 订阅状态
• 当前配额使用情况
• 请求计数 (24小时, 7天, 30天)
• 使用图表
• 快速访问 API 密钥

4.4 设置页面

更新 src/app/[locale]/(protected)/settings/:

billing/page.tsx

• 添加 API 订阅管理
• 积分套餐购买
• 使用历史

第五阶段: 文档迁移

5.1 API 文档结构

在 content/docs/api/ 中创建:

api/
├── meta.json
├── meta.zh.json
├── index.mdx
├── index.zh.mdx
├── authentication.mdx
├── authentication.zh.mdx
├── rate-limits.mdx
├── rate-limits.zh.mdx
├── endpoints/
│   ├── meta.json
│   ├── meta.zh.json
│   ├── user-profile.mdx
│   ├── user-profile.zh.mdx
│   ├── user-tweets.mdx
│   ├── user-tweets.zh.mdx
│   ├── user-tweets-replies.mdx
│   ├── user-tweets-replies.zh.mdx
│   ├── followers.mdx
│   ├── followers.zh.mdx
│   ├── following.mdx
│   ├── following.zh.mdx
│   ├── tweet-detail.mdx
│   ├── tweet-detail.zh.mdx
│   ├── search.mdx
│   ├── search.zh.mdx
│   ├── community-tweets.mdx
│   ├── community-tweets.zh.mdx
│   ├── list-latest-tweets.mdx
│   ├── list-latest-tweets.zh.mdx
│   └── token-info.mdx
│   └── token-info.zh.mdx
└── examples/
    ├── meta.json
    ├── meta.zh.json
    ├── javascript.mdx
    ├── javascript.zh.mdx
    ├── python.mdx
    ├── python.zh.mdx
    ├── curl.mdx
    └── curl.zh.mdx

5.2 文档内容

每个端点文档应包括:

• 描述和用例
• 认证要求
• 请求参数 (带类型和验证)
• 响应格式 (带示例)
• 错误代码和处理
• 速率限制信息
• 代码示例 (JavaScript, Python, cURL)
• 双语支持 (英文和中文)

5.3 导航更新

更新 content/docs/meta.json:

{
  "title": "文档",
  "pages": [
    "index",
    "api"
  ]
}

第六阶段: 服务器操作

6.1 API 密钥操作

在 src/actions/api-keys.ts 中创建:

- createApiKey(name: string)
- regenerateApiKey(keyId: string)
- toggleApiKey(keyId: string, enabled: boolean)
- deleteApiKey(keyId: string)
- getApiKeys()
- getApiKeyUsage(keyId: string)

6.2 订阅操作

在 src/actions/api-subscriptions.ts 中创建:

- getActiveSubscription()
- upgradeSubscription(planId: string)
- cancelSubscription()
- purchaseCreditPackage(packageId: string)
- getUsageStats(period: string)

第七阶段: 状态管理

7.1 Zustand 存储

在 src/stores/ 中创建:

api-keys-store.ts

interface ApiKeysStore {
  keys: ApiKey[]
  loading: boolean
  fetchKeys: () => Promise<void>
  createKey: (name: string) => Promise<void>
  deleteKey: (id: string) => Promise<void>
}

api-usage-store.ts

interface ApiUsageStore {
  usage: UsageData
  logs: RequestLog[]
  stats: UsageStats
  fetchUsage: (period: string) => Promise<void>
  fetchLogs: (filters: LogFilters) => Promise<void>
}

第八阶段: 国际化

8.1 翻译键

添加到 messages/en.json 和 messages/zh.json:

{
  "api": {
    "keys": {
      "title": "API 密钥",
      "create": "创建新密钥",
      "regenerate": "重新生成",
      "delete": "删除",
      "usage": "使用情况"
    },
    "subscription": {
      "title": "API 订阅",
      "quota": "请求配额",
      "used": "已使用",
      "remaining": "剩余"
    },
    "endpoints": {
      "userProfile": "用户资料",
      "userTweets": "用户推文",
      // ... 更多端点
    }
  }
}

第九阶段: 测试策略

9.1 单元测试

为以下内容创建测试:

• 速率限制逻辑
• 配额计算
• 缓存密钥生成
• API 密钥验证
• 订阅状态检查

9.2 集成测试

测试:

• API 端点响应
• 认证流程
• 速率限制执行
• 配额扣除
• 缓存命中/未命中场景

9.3 端到端测试

测试用户流程:

• 创建 API 密钥 → 发起请求 → 查看日志
• 购买订阅 → 使用配额 → 升级
• 超出速率限制 → 错误处理

第十阶段: 部署检查清单

10.1 部署前

• 所有数据库迁移已应用
• 环境变量已配置
• API 端点已测试
• 文档已审查
• 速率限制已配置
• 缓存设置已优化
• 错误处理已验证
• 日志记录已配置

10.2 部署步骤

1. 数据库迁移

   pnpm db:migrate

2. 填充初始数据

   pnpm db:seed

3. 构建应用

   pnpm build

4. 运行测试

   pnpm test

5. 部署

   pnpm deploy

10.3 部署后

• 验证 API 端点可访问
• 测试认证流程
• 监控速率限制
• 检查日志功能
• 验证缓存性能
• 测试订阅流程
• 监控错误率

第十一阶段: 迁移时间表

第 1 周: 基础

• 数据库架构设计和迁移
• 环境配置
• 核心服务架构

第 2 周: API 实现

• 实现所有 10 个 Twitter API 端点
• 创建 API 管理端点
• 构建中间件和服务

第 3 周: 用户界面

• API 密钥管理页面
• 仪表板增强
• 使用日志界面

第 4 周: 文档和测试

• 迁移所有文档
• 编写测试
• 集成测试

第 5 周: 完善和部署

• 错误修复
• 性能优化
• 部署

风险评估

高风险

• 数据库迁移: 具有关系的复杂架构

  • 缓解措施: 在预发布环境中进行彻底测试

• 速率限制: 分布式系统挑战

  • 缓解措施: 使用经过验证的速率限制库

中等风险

• API 兼容性: 保持向后兼容性

  • 缓解措施: 版本化 API 端点

• 缓存失效: 过期数据问题

  • 缓解措施: 保守的 TTL 设置

低风险

• UI 组件: 需求明确
• 文档: 直接迁移

成功标准

• 所有 10 个 API 端点功能正常
• API 密钥管理正常工作
• 速率限制正确执行
• 订阅系统已集成
• 使用跟踪准确
• 文档完整 (双语)
• 仪表板显示实时数据
• 所有测试通过
• 达到性能基准
• 迁移期间零数据丢失

回滚计划

如果出现关键问题:

1. 数据库回滚

   pnpm db:rollback

2. 代码回滚

   • 恢复到之前的 git 提交
   • 重新部署稳定版本

3. 数据恢复

   • 从备份恢复
   • 验证数据完整性

支持和维护

监控

• API 响应时间
• 错误率
• 速率限制命中
• 缓存命中率
• 配额使用模式

警报

• API 停机
• 高错误率
• 速率限制滥用
• 配额耗尽
• 数据库问题

文档更新

• 保持 API 文档与代码同步
• 端点更改时更新示例
• 维护变更日志

附录

A. 文件映射

B. 需要添加的依赖

{
  "dependencies": {
    "@upstash/ratelimit": "^1.0.0",
    "ioredis": "^5.3.0"
  }
}

C. 配置文件

• 为新表更新 drizzle.config.ts
• 如需要更新 biome.json
• 如需要更新 tsconfig.json 路径

结论

此迁移计划为将 Twitter API 功能迁移到新框架提供了全面的路线图。按顺序遵循各个阶段,在每个阶段进行彻底测试,并在整个过程中与利益相关者保持清晰的沟通。

预估总工作量: 4-5 周 团队规模: 1-2 名开发人员 优先级: 高 复杂度: 中高