Birdor 商业计划书第三十三章：后端 API 与任务架构

本系列导航

• 上一篇：第三十二章：前端工具页架构
• 下一篇：第三十四章：AI 模型路由与成本控制
• 返回目录：Birdor 商业计划书目录

本章关键词

后端 API、任务队列、API token、用量统计、批处理、错误码、异步任务、服务边界、版本化 API。

适合阅读的人

• 正在设计 Birdor 后端架构的工程师。
• 需要规划 API 版本、认证、限流和计费系统的人。
• 想把工具站从纯前端扩展到 SaaS 后端的团队。

本章摘要

Birdor 后端的职责是承载不能或不应在浏览器完成的能力：账户、API token、AI 调用、长任务、批处理、计费、用量统计和审计。基础工具尽量本地执行，后端服务高价值和自动化场景。

后端架构要从 MVP 起就区分同步 API 和异步任务。短任务用同步 API，长日志、批量文件和 AI 长分析使用任务队列。API 设计必须版本化、契约化，因为 API 一旦发布就难以修改。

33.1 后端服务边界

33.1.1 后端负责

33.1.2 后端不负责（前端/本地处理）

后端不应该承担所有基础工具计算。能本地完成的能力优先本地执行，同时抽象为可复用模块供 API 使用。

33.2 API 设计规范

33.2.1 版本化路径

POST /v1/json/format
POST /v1/json/validate
POST /v1/jwt/decode
POST /v1/regex/generate
POST /v1/log/analyze
GET  /v1/usage
GET  /v1/billing

版本号在路径中（非 header），便于缓存和调试。

33.2.2 统一响应格式

{
  "request_id": "req_abc123",
  "success": true,
  "data": { ... },
  "error": null,
  "usage": {
    "credits_consumed": 25,
    "quota_remaining": 475,
    "cost_usd": 0.0025
  },
  "warnings": ["input_truncated"],
  "meta": {
    "version": "v1",
    "timestamp": "2025-08-08T10:00:00Z"
  }
}

33.2.3 统一错误码

33.3 同步与异步任务设计

33.3.1 同步 API（< 5 秒）

33.3.2 异步任务（> 5 秒）

33.3.3 异步任务状态机

[created] → [queued] → [processing] → [completed]
                ↓           ↓              ↓
             [cancelled] [failed]      [expired]

异步任务需要四类接口：

POST   /v1/tasks              # 创建任务
GET    /v1/tasks/:id          # 查询状态
GET    /v1/tasks/:id/result   # 获取结果
DELETE /v1/tasks/:id          # 取消任务

33.4 任务队列设计

33.4.1 任务表结构

CREATE TABLE tasks (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  workspace_id UUID,
  task_type VARCHAR(50) NOT NULL,  -- 'log_analyze', 'batch_process'
  status VARCHAR(20) NOT NULL,      -- 'created', 'queued', 'processing', 'completed', 'failed', 'cancelled'
  input_ref TEXT,                   -- 输入数据引用（S3/存储路径）
  output_ref TEXT,                  -- 输出结果引用
  error TEXT,                       -- 失败原因
  priority INT DEFAULT 0,           -- 优先级（Pro 用户更高）
  retry_count INT DEFAULT 0,
  max_retries INT DEFAULT 2,
  created_at TIMESTAMP DEFAULT NOW(),
  started_at TIMESTAMP,
  finished_at TIMESTAMP,
  expires_at TIMESTAMP              -- 结果过期时间
);

33.4.2 队列优先级

33.5 用量统计体系

所有 API 和 AI 调用都要记录用量：

{
  "usage_record": {
    "user_id": "usr_xxx",
    "api_token_id": "tok_yyy",
    "endpoint": "v1/log/analyze",
    "task_type": "ai_log",
    "model": "gpt-4o-mini",
    "input_tokens": 2048,
    "output_tokens": 1024,
    "credits_consumed": 50,
    "cost_usd": 0.005,
    "latency_ms": 2340,
    "success": true,
    "error_code": null,
    "timestamp": "2025-08-08T10:00:00Z"
  }
}

这些数据服务 Pro、API 计费和成本控制。

33.6 数据存储设计

历史记录应由用户明确开启或保存，不能默认保存敏感输入。

33.7 安全设计

33.8 开发落地清单

第一批后端任务：

• 用户和会话基础（OAuth + 邮箱）
• API token 创建、撤销、校验
• 统一错误响应格式
• JSON validate API 原型
• AI Regex 调用服务
• 用量记录表和查询接口
• 任务表和状态查询预留

不要第一天做完整 billing，但要记录足够用量数据，避免后续无法计费。

33.9 后端风险

33.10 验收标准

• API 有版本号（v1）。
• 所有错误返回统一结构。
• API token 可创建、可撤销、有 scope。
• 用量能按用户、按 token、按端点记录。
• 长任务有 task_id 和状态查询。
• AI 调用能记录 token 和成本。
• 敏感输入默认不保存。
• 有基础的 rate limit 和 quota 检查。

33.11 本章结论

Birdor 后端应服务高价值能力：账户、API、AI、任务、计费和观测。同步 API 和异步任务要从一开始分清，错误码和用量统计要统一。后端不需要第一天就完美，但必须有清晰的边界和可追踪性。

延伸阅读

• AI 时代全球开发者工具平台目录
• 第三十二章：前端工具页架构
• 第三十四章：AI 模型路由与成本控制
• 第三十六章：可观测性与 SRE 计划
• 第三十五章：隐私、安全与数据策略

FAQ

Q: 后端需要一开始就微服务化吗？
A: 不需要。MVP 阶段单体服务足够。当某个模块（如 AI 服务）成为瓶颈时，再考虑拆分。过早微服务会增加运维复杂度。

Q: 为什么历史记录默认不保存？
A: 开发者工具处理的数据可能包含敏感信息（JWT、日志、配置）。默认保存会带来隐私风险和法律合规问题。用户明确选择保存后，才存储数据。

Q: 异步任务用什么队列？
A: MVP 可用 Redis + Bull（Node.js）或 Celery（Python）。生产环境可迁移到 Kafka、RabbitMQ 或托管服务（AWS SQS）。重点是任务状态可追踪，不是队列有多高级。

Q: API 版本怎么演进？
A: v1 保持向后兼容。重大变更时发布 v2，v1 至少维护 12 个月。不要频繁发新版本，API 稳定性是开发者信任的基础。

Q: 用量统计和数据存储成本高吗？
A: ClickHouse 或 TimescaleDB 处理时序数据成本很低。用量记录是 Birdor 的"经营数据"，值得投入。没有用量数据，后续计费、成本优化和用户体验都无从谈起。

33.21 数据库设计核心原则

Birdor 后端数据库设计遵循"少即是多"的极简原则，避免为假设的需求提前建表。

表设计扩展策略：当单表数据量超过 1000 万行时，优先考虑按时间范围分区（Partitioning），而非立即分库分表。分区对查询透明，迁移成本低。

33.22 缓存策略

缓存不是性能问题的补丁，而是架构设计的组成部分。Birdor 采用三级缓存体系：

缓存一致性的保证：写入数据库后同步删除缓存（Cache-Aside 模式），不采用 Write-Through 以避免写入延迟。AI 结果缓存需特别注意：不同模型版本须使用不同缓存 key 前缀，防止旧模型结果被错误复用。

33.23 容量测试策略

Birdor 后端容量测试不是一次性活动，而是持续验证系统边界的工程实践：

容量测试的准生产环境：使用与生产相同配置但规模减半的 Staging 集群，配合流量镜像（Traffic Mirroring）技术复现真实负载分布。

33.24 服务间通信模式

MVP 阶段 Birdor 采用单体架构，但随着模块复杂度增加，服务间通信模式需提前规划：

演进触发条件：当 AI Gateway 的调用量超过 API 总流量的 50% 时，将 AI 服务从单体中拆分为独立服务，通信模式保持 HTTP REST（内部）+ 异步事件（用量统计）。

33.25 数据一致性策略

不同业务场景对一致性的要求不同，Birdor 按场景选择适配策略：

一致性设计的底线原则：涉及资金（余额、配额、计费）必须强一致；涉及统计和日志可以最终一致。不要为了统一而统一，正确性优先于简洁性。

33.26 数据库扩展策略

Birdor 的核心数据表设计预留了水平扩展空间，但扩展应遵循"需要时才做"的原则。

分区策略示例：usage_records 表按月分区，查询最近 30 天数据时只需扫描 1-2 个分区，避免全表扫描。

33.27 缓存失效的精细化控制

缓存失效不当会导致数据不一致或缓存击穿。Birdor 的缓存失效策略：

缓存击穿的防护：对高并发查询的 key 使用互斥锁（Mutex），只允许一个请求穿透到数据库，其余请求等待缓存回填。

33.28 容量测试的自动化

容量测试应集成到 CI/CD 流水线中，成为每次重大发布的前置条件。

# .github/workflows/capacity-test.yml 示例
capacity-test:
  runs-on: ubuntu-latest
  steps:
    - name: Run k6 load test
      run: k6 run --vus 100 --duration 10m load-test.js
    - name: Check p95 latency
      run: |
        p95=$(cat results.json | jq '.metrics.http_req_duration.p95')
        if [ $(echo "$p95 > 200" | bc) -eq 1 ]; then
          echo "p95 latency $p95 exceeds budget"; exit 1
        fi
    - name: Check error rate
      run: |
        error_rate=$(cat results.json | jq '.metrics.http_req_failed.rate')
        if [ $(echo "$error_rate > 0.005" | bc) -eq 1 ]; then
          echo "Error rate $error_rate exceeds 0.5%"; exit 1
        fi

自动化容量测试的输出不仅是通过/失败，还包括详细的资源瓶颈分析报告，指导下一次扩容决策。

33.29 任务队列的监控与告警

任务队列是后端稳定性关键，必须有完善的监控体系。

队列监控的可视化：Grafana 面板展示队列深度趋势、各消费者处理速率和任务类型分布。队列深度的突然下降（非消费导致）可能是数据丢失信号，必须立即排查。

33.30 数据备份与恢复策略

Birdor 的数据是核心资产，备份策略必须与业务重要性匹配。

备份验证：每季度执行一次恢复演练，验证备份的完整性和恢复流程的可操作性。恢复演练的结果记录到灾难恢复手册中。

33.31 数据库连接池管理

连接池是数据库访问的关键资源，配置不当会导致性能瓶颈。

连接池监控：记录连接使用率、等待获取连接的时间和连接泄漏数量。连接使用率持续 > 80% 时应考虑扩容或优化查询。

33.32 后端性能监控

后端性能监控覆盖黄金指标和自定义业务指标。

33.33 后端开发的编码规范

编码规范是质量的基础保障。

33.34 API 文档自动生成

API 文档应与代码同步维护，避免文档与实现脱节。

自动生成的文档是后端开发者的契约承诺，也是前端和外部开发者集成的信任基础。