技术选型总览

要点

• 整个知识体系的技术选型围绕一个核心原则：尽量用 Cloudflare 生态 + Web Standards
• 运行时选 Cloudflare Workers，框架选 Hono，数据库选 D1 + KV + R2
• AI 能力优先用 Workers AI，不够再补 OpenAI / Anthropic
• 所有选型都优先考虑边缘部署兼容性、冷启动速度和维护成本
• 技术选型不是"最好的"，而是"在这个场景下最合适的"

内容

1. 选型原则

在给出具体选型之前，先说清楚选择的判断标准。本知识体系的选型遵循以下原则：

1.1 边缘优先

所有核心组件必须能在边缘运行时（Cloudflare Workers）正常运行。

这意味着：

• 不能用依赖 Node.js 内置模块（fs、path、child_process）的包
• 不能用需要原生编译的 npm 包（如 sharp、bcrypt）
• 包体积要尽量小（Workers 免费版限制 gzip 后 3MB）

1.2 Web Standards 优先

优先使用基于 Web 标准 API 的工具和库。

• 请求/响应用标准 Request / Response
• 加密用 Web Crypto API（crypto.subtle）
• 流处理用标准 ReadableStream

这样做的好处是：代码在不同运行时之间迁移的成本最低。

1.3 生态统一

尽量使用同一生态的产品，减少集成成本。

Cloudflare 的产品线（Workers、D1、KV、R2、Vectorize、Queues、Durable Objects）之间有天然集成优势：

• 同一控制台管理
• 内网调用零延迟
• 统一的鉴权和计费
• 文档和示例相互衔接

1.4 够用就好

不为"可能用到"的功能提前引入复杂度。

• 不需要 ORM 的全部高级特性？用 Drizzle 的轻量模式
• 不需要复杂状态管理？用 KV 就够了
• 不需要多区域部署？先只部署到一个区域

2. 核心技术栈一览

3. 为什么选 Cloudflare Workers 作为主运行时

这是很多人会问的问题。Node.js 不香吗？为什么非要用 Workers？

先说结论：不是 Workers 最好，而是 Workers 和 Hono + AI 的组合最匹配。

Workers 的劣势（无文件系统、无原生模块）在 AI 编排场景里影响不大，因为 AI 后端主要工作是"调 API + 组织数据"，不是"处理本地文件"。

Workers 的优势（边缘部署、免费额度、零运维）在 AI 场景里收益很大，因为 AI 响应延迟本来就长，网络层能省则省。

4. 为什么数据库选 D1 + KV + R2 三件套

很多后端开发者习惯用一个 PostgreSQL 解决所有问题。但在边缘场景下，这种思路需要调整。

4.1 为什么要分三种存储

这三种存储各有优势：

• D1 支持 SQL 查询、JOIN、事务，但写入性能不如 KV
• KV 读取延迟极低（边缘缓存），但不支持复杂查询
• R2 适合存大文件，零出口流量费，但不适合频繁的小数据读写

4.2 什么时候该用哪个

用户注册 → 写入 D1（users 表）
登录会话 → 写入 KV（session:{token} → userId）
上传文档 → 写入 R2（原始文件）+ D1（文档元数据）
文档 Embedding → 写入 Vectorize（向量）+ D1（关联元数据）
限流计数 → 写入 KV（rate:{userId}:{minute} → count）
对话历史 → 写入 D1（messages 表）

4.3 如果你不想用 Cloudflare

本知识体系的选型深度绑定 Cloudflare 生态，主要是为了教学一致性。如果你要用其他平台，以下是等价替换方案：

替换时注意检查边缘兼容性——不是所有替代方案都能在 Workers 上跑。

5. AI 能力选型策略

AI 模型的选型需要平衡三个因素：能力、成本、延迟。

5.1 推荐策略

首选：Cloudflare Workers AI
  ├─ 优点：免费额度、边缘推理、零额外网络延迟
  ├─ 缺点：模型选择有限、能力不如顶级商用模型
  └─ 适合：学习、原型、对模型能力要求不高的场景

备选：OpenAI API
  ├─ 优点：模型能力最强、生态最广、文档最全
  ├─ 缺点：需要美国区域调用、有延迟
  └─ 适合：生产环境、需要顶级模型能力的场景

备选：Anthropic API
  ├─ 优点：Claude 系列模型，长上下文优势，代码能力强
  ├─ 缺点：和 OpenAI 类似的区域限制
  └─ 适合：长文档处理、代码生成、复杂推理场景

5.2 多模型架构

实际项目中，建议从一开始就设计多模型架构：

// 统一的模型调用接口，底层可以切换不同供应商
interface ChatModel {
  chat(messages: Message[], options?: ChatOptions): Promise<Response>
  stream(messages: Message[], options?: ChatOptions): AsyncIterable<string>
}
 
// 不同供应商的实现
class WorkersAIModel implements ChatModel { ... }
class OpenAIModel implements ChatModel { ... }
class AnthropicModel implements ChatModel { ... }
 
// 路由层根据场景选择
function getModelForTask(task: string): ChatModel {
  if (task === 'simple') return new WorkersAIModel()
  if (task === 'complex') return new OpenAIModel()
  return new AnthropicModel()
}

这种设计在分组 12（AI API 服务封装）会详细展开。

6. 版本锁定

为了避免你在学习过程中遇到版本不一致的问题，以下是本知识体系基于的版本：

7. 工具链总览

除了核心技术栈，以下是开发过程中会用到的工具：

# 开发
wrangler dev          # 本地开发 + 热重载
wrangler deploy       # 部署到 Workers
wrangler tail         # 实时日志
 
# 测试
vitest                # 单元测试
playwright test       # E2E 测试
 
# 代码质量
biome check           # Lint + 格式化
tsc --noEmit          # 类型检查
 
# 数据库
wrangler d1 execute   # D1 SQL 执行
drizzle-kit push      # 数据库迁移
 
# HTTP 测试
curl / httpie         # 命令行请求
bruno                 # GUI API 测试

8. 总结

本知识体系的技术选型围绕四个原则：边缘优先、Web Standards 优先、生态统一、够用就好。

核心技术栈：

• 运行时：Cloudflare Workers
• 框架：Hono + TypeScript
• 存储：D1（关系数据）+ KV（缓存）+ R2（文件）+ Vectorize（向量）
• AI：Workers AI（首选）+ OpenAI / Anthropic（备选）
• 工具链：wrangler + Drizzle + Zod + Vitest

这套选型不是"理论上最好的"，而是在"边缘部署 + AI 编排 + 教学一致性"这个特定场景下的务实选择。

进入 01 分组，开始建立 Web 服务基础——理解 HTTP、运行时和边缘计算的核心概念。