Encore.ts 深度教程
基于 Encore.ts 官方文档、官方教程（REST API / Uptime Monitor）、官方博客（Rust 运行时、TypeScript AI、MCP Deep Dive）与 GitHub encoredev/skills 仓库整合编写的中文深度教程，只覆盖 Encore.ts（TypeScript 变体），不含 Encore.go。第 17–20 章为本教程重点：Encore 内置的 LLM Rules、Agent Skills、MCP Server 三件套详解与 AI 原生开发工作流，素材含本机真实项目 encore.ts.ticketBookingB2B 的落地经验。
本教程的定位
这不是对官方文档的逐页搬运，而是面向实践重新组织的中文教程：原语篇（第 3–12 章）以"声明 → 规则 → 实战模式 → 误区"展开，实战篇（第 13–14 章）完整中文化两个官方教程，AI 篇（第 17–20 章）把官方分散在文档与博客的 AI 能力整合为可落地的工作流。示例尽量采用机票/订单/支付业务场景。与 Encore 研究摘要 互补：摘要回答"是什么/为什么"，本教程回答"怎么做"。
Wiki 编译排除
本目录中的全部 Markdown 文档均带有 wiki_exclude: true，不会被 wiki-compile 扫描、提炼或写入概念库。
版本基准：encore CLI v1.57+（2026-08 最新 v1.58.x）。官方文档：https://encore.dev/docs/ts
一、学习目标
完成本教程后，你应该能够：
- 解释应用模型 (Application Model)、静态分析与 Rust 运行时如何支撑 Encore 的自动化能力。
- 用五大原语（Service/API、SQLDatabase、Pub/Sub、Cron、Bucket/Cache）声明式地构建分布式后端。
- 正确使用类型校验、鉴权三件套、流式 API、中间件与结构化日志。
- 独立完成 URL 短链与 Uptime 监控两个完整项目，并用 encore test 建立零 mock 的测试闭环。
- 用 encore gen client 打通前端类型链路；掌握自托管 Docker 与 Encore Cloud 两条部署路径。
- 配齐 LLM Rules + Agent Skills + MCP 三层 AI 上下文，按"发现→实现→自验→审查"的标准循环用 AI 开发 Encore 应用。
二、章节结构
| 章节 | 核心内容 | 难度 |
|---|
| 第1章：开篇 | 定位、应用模型、Rust 运行时、五大原语总览 | 入门 |
| 第2章：环境搭建 | 安装、app create、encore run、本地仪表盘、daemon | 入门 |
| 第3章：服务与 API | api() 全选项、四种签名、APIError 17 码、raw/static | 核心 |
| 第4章：请求校验 | 类型即校验、校验器、Query/Header/Cookie 参数来源 | 核心 |
| 第5章：数据库 | 迁移规则、查询全家族、事务、db CLI、knex/Drizzle | 核心 |
| 第6章：服务架构 | 拆分决策、目录模式、~encore/clients、元数据 | 核心 |
| 第7章：Pub/Sub | Topic/Subscription、投递语义、有序、DLQ、幂等 |
三、建议路线
- 第一次接触 Encore：第 1→2→3→4→5 章打底，然后直接做第 13 章实战一。
- 有后端框架经验、想快速评估：第 1 章 + 第 13、14 章实战 + 第 16 章部署，半天可完成。
- 准备在项目中用 AI 开发：第 17→18→19→20 章连读（前置要求：至少做过一个实战章），再回头按需补原语章。
- 做技术选型汇报：第 1 章 + 研究摘要（对比表与代价分析在摘要里）。
- 日常查手册：第 3–12 章按原语索引，各章末尾"常见误区"是排错快查表。
四、贯穿全书的心智模型
text
TypeScript 源码（业务代码 + 原语声明）
↓ 静态分析 (tsparser)
Application Model（服务/API/DB/Topic/Cron/Bucket/Secret 依赖图）
↓ 同时驱动
本地基础设施 ┃ 云端开通 ┃ API 文档 ┃ 客户端 SDK ┃ 分布式追踪 ┃ 架构图 ┃ MCP 工具
↓ 运行时
Rust 层（路由/校验/连接池/网关）→ 你的 TypeScript 处理函数
一切自动化的前提是"走原语"
绕过原语（直连 pg、手起 Redis 客户端、自拼 HTTP 调兄弟服务）的代码不进应用模型：没有自动开通、没有追踪、没有文档、MCP 看不见。用 Encore 的第一纪律：所有 I/O 走原语。
五、资料边界
本教程整合的原始来源：Encore.ts 官方文档（primitives / develop / observability / self-host / CLI 各节）、官方教程 Building a REST API 与 Building an Uptime Monitor（仅取 TypeScript 版）、官方博客（Rust Runtime、How AI Agents Want to Write TypeScript、MCP Server Deep Dive）、GitHub encoredev/skills 仓库，以及本机项目 encore.ts.ticketBookingB2B 的一手落地经验（1053 行官方规则快照、8 个已安装技能、Windows 中文用户名坑、api.static 构建期约束等）。早期抓取的官方页面归档见 Encore 资料索引（2026-04 抓取，AI/MCP 部分以本教程 2026-08 的核实为准）。
苏公网安备32011402012723号