第1章：开篇 —— Encore.ts 定位、应用模型与 Rust 运行时

学任何框架之前先回答三个问题：它替你做了什么决定、凭什么能做到、代价是什么。本章建立 Encore.ts 的完整心智模型，后面所有章节都是这个模型的展开。

一、Encore.ts 是什么

官方的两句定位：

"Open source framework for building robust type-safe distributed systems with declarative infrastructure."

"Batteries included TypeScript framework for building distributed systems."

翻译成工程语言：Encore.ts 是一个 TypeScript 后端框架，它把传统上分离的两份资产——应用代码和基础设施配置——合并成同一份类型安全的声明：

// 这三行都是"代码"，但同时也是"基础设施声明"
const db = new SQLDatabase("orders", { migrations: "./migrations" });
const orderEvents = new Topic<OrderEvent>("order-events", { deliveryGuarantee: "at-least-once" });
const cleanup = new CronJob("cleanup", { every: "6h", endpoint: cleanupExpired });

写下这些声明后：本地 encore run 自动用 Docker 拉起 Postgres 和消息队列；部署到云上自动映射为 AWS RDS / SNS+SQS 或 GCP Cloud SQL / Pub/Sub；同时自动获得 API 文档、类型化客户端 SDK、分布式追踪 (distributed tracing) 和实时架构图。

它不是什么

二、根机制：应用模型 (Application Model)

Encore 一切自动化能力的来源是静态分析 (static analysis)：

"Encore works by using static analysis to understand your application."

CLI 内置的解析器（TypeScript 侧是用 Rust 写的 tsparser）在编译期扫描源码，识别以下声明并抽成一张依赖图，官方称之为应用模型：

• Services —— 每个含 encore.service.ts 的目录
• APIs —— 被 api(...) 包装的导出函数
• Databases —— new SQLDatabase(...)
• Pub/Sub —— new Topic(...) / new Subscription(...)
• Cron Jobs —— new CronJob(...)
• Object Storage —— new Bucket(...)
• Caching —— new CacheCluster(...)
• Secrets —— secret("Name")

这张图同时驱动五类产物：

                        Application Model
                               │
      ┌────────────┬───────────┼───────────┬────────────┐
      ▼            ▼           ▼           ▼            ▼
 类型安全的     基础设施开通   API 文档    分布式追踪    实时架构图
 Client SDK    (本地/云)     +Catalog                 (Encore Flow)

关键推论：

"Any deviation is caught as a compilation error."

**写法偏离约定是编译错误，不是运行时惊喜。**忘了 encore.service.ts、api() 的类型写错、引用了不存在的数据库——都活不过 encore run。这既是新手的"框架税"，也是团队协作和 AI 生成代码（第 17 章展开）的最大红利。

为什么别的框架做不到

"When every stack looks different, all tools have to be general purpose."

Express 生态里每个项目的 DB 层、消息层、配置层都不一样，工具只能做通用的、浅层的分析。Encore 的对策是强制收敛技术栈——框架、解析器、运行时由同一团队协同设计，所以应用模型可以做到 100% 准确。代价是丢掉"想怎么写就怎么写"的自由。

三、Rust 运行时：TypeScript 框架的反直觉底座

Encore.ts 最独特的架构决策：业务代码是 TypeScript，但 HTTP 处理、校验、数据库连接池全部在 Rust 层。

┌─────────────────────────────────────────────────────┐
│  你的 TypeScript 业务代码（不 import express/zod）    │
├─────────────────────────────────────────────────────┤
│  runtimes/js（NAPI bindings，Rust ↔ Node 桥）        │
├─────────────────────────────────────────────────────┤
│  runtimes/core（Rust，Tokio + Hyper）                │
│   ├── HTTP 路由 / 解析 / 校验 / 序列化                │
│   ├── DB 连接池                                      │
│   ├── Pub/Sub（NSQ / SNS+SQS / GCP Pub/Sub）         │
│   ├── 分布式追踪 / 指标 / 对象存储 / 缓存              │
│   └── API Gateway（嵌入 Cloudflare Pingora）         │
├─────────────────────────────────────────────────────┤
│  tsparser（Rust）→ 静态分析 → Application Model      │
└─────────────────────────────────────────────────────┘

性能数据

官方基准（150 并发，5 次取最优）：

"9x the throughput of Express.js with 80% less latency"

为什么快，以及比快更重要的事

1. 多线程异步事件循环（Tokio + Hyper）——HTTP 解析不占用 Node 的单线程；
2. 请求校验在 Rust 层执行——非法请求根本不进入 JavaScript，顺带缓解拒绝服务攻击 (DoS) 面；
3. API 网关直接嵌入运行时（Cloudflare Pingora）——鉴权处理器同进程执行，省掉独立代理的一跳网络与序列化；
4. 零 NPM 运行时依赖——业务代码不 import express / zod / pg / amqplib，安装快、攻击面小。

对开发者而言 Rust 完全透明：你写的仍是普通 TypeScript，性能、安全、校验下沉是"白拿"的。

四、五大原语总览

Encore 把后端开发的基础设施需求收敛为一组原语 (primitives)，全部以"包级变量声明"的形式表达。本教程为它们各设专章：

外加横切能力：校验（第 4 章）、鉴权（第 10 章）、流式 API（第 11 章）、中间件与可观测性（第 12 章）、密钥（第 8 章）。

原语声明的统一规则 所有原语必须是包级 (package-level) 变量，不能在函数体内创建——静态分析器要在编译期看见它们。这条规则贯穿全书，违反即编译错误。

五、开源与商业的边界

自托管路径完全可用：encore build docker 产出标准镜像（第 16 章）。付费才有的是平台便利，不是框架能力。

六、与同类技术对比

Encore 的甜区：多服务 + 多基础设施依赖的分布式后端。反过来，单文件小工具、纯静态站点用它是杀鸡用牛刀。

七、常见误区

1. 把 Encore.ts 当"更快的 Express"用，绕过原语直连资源（如自己 pg.connect）——失去整张追踪图和自动化开通。
2. 以为必须付费用 Encore Cloud——开源自托管是一等公民。
3. 担心 Rust 运行时需要学 Rust——完全不需要，业务层就是普通 TypeScript。
4. 在函数体内创建原语（new SQLDatabase 写在 handler 里）——静态分析器看不见，直接报错。
5. 以为静态分析约束是缺点——它正是自动文档、自动开通、AI 友好性的前提，需要整体权衡。

八、实践练习

1. 访问 https://encore.dev/docs/ts，浏览左侧目录，对照本章"五大原语总览"建立映射。
2. 阅读 Encore 研究摘要 第七章的对比表，写出你当前项目里"代码 + 基础设施"分离导致过的一次事故或返工。
3. 思考：你负责的机票预订后端如果用 Encore 重写，booking / payment / inventory 会声明哪些原语？画一张纸面依赖图。

九、总结

1. Encore.ts = 框架 + Rust 运行时 + 静态分析器的协同设计整体，应用代码就是基础设施声明。
2. 应用模型是根机制：一张编译期抽出的依赖图，同时驱动开通、文档、SDK、追踪、架构图。
3. 偏离约定是编译错误——确定性换自由度，是 Encore 一切价值与一切"框架税"的共同来源。
4. Rust 运行时对开发者透明，带来约 9 倍于 Express 的吞吐与请求校验下沉。
5. 开源自托管完整可用，Encore Cloud 是可选的托管控制面。

请继续阅读：第2章：环境搭建。

原始资料引用

• Encore.ts 官方文档首页
• Application Model
• Encore.ts Rust 运行时（官方博客）
• 9x faster than Express（官方博客）
• GitHub: encoredev/encore

Related Documents

• 教程总览
• Encore 研究摘要
• 第2章:环境搭建