Agent X-Ray
RuntimeNotesAbout
Notes/代码工程/Encore/README

Encore.ts 深度教程

约 4 分钟 · 更新于 2026-09-02

基于 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

一、学习目标

完成本教程后，你应该能够：

  1. 解释应用模型 (Application Model)、静态分析与 Rust 运行时如何支撑 Encore 的自动化能力。
  2. 用五大原语（Service/API、SQLDatabase、Pub/Sub、Cron、Bucket/Cache）声明式地构建分布式后端。
  3. 正确使用类型校验、鉴权三件套、流式 API、中间件与结构化日志。
  4. 独立完成 URL 短链与 Uptime 监控两个完整项目，并用 encore test 建立零 mock 的测试闭环。
  5. 用 encore gen client 打通前端类型链路；掌握自托管 Docker 与 Encore Cloud 两条部署路径。
  6. 配齐 LLM Rules + Agent Skills + MCP 三层 AI 上下文，按"发现→实现→自验→审查"的标准循环用 AI 开发 Encore 应用。

二、章节结构

章节核心内容难度
第1章：开篇定位、应用模型、Rust 运行时、五大原语总览入门
第2章：环境搭建安装、app create、encore run、本地仪表盘、daemon入门
第3章：服务与 APIapi() 全选项、四种签名、APIError 17 码、raw/static核心
第4章：请求校验类型即校验、校验器、Query/Header/Cookie 参数来源核心
第5章：数据库迁移规则、查询全家族、事务、db CLI、knex/Drizzle核心
第6章：服务架构拆分决策、目录模式、~encore/clients、元数据核心
第7章：Pub/SubTopic/Subscription、投递语义、有序、DLQ、幂等进阶
第8章：定时任务与密钥CronJob 约束、扫表模式、secret() 与环境解析基础
第9章：对象存储与缓存Bucket 全操作、签名 URL、权限引用、类型安全键空间进阶
第10章：鉴权三件套、两张行为表、JWT/APIKey/Cookie、测试 mock核心
第11章：流式 APIstreamIn/Out/InOut、握手、广播模式、客户端消费进阶
第12章：横切能力middleware target、CORS、结构化日志、零埋点追踪进阶
第13章：实战一URL 短链：官方 REST API 教程完整中文版实战
第14章：实战二Uptime 监控：3 服务 2 库 1 Cron 1 主题完整走通实战
第15章：测试与前端encore test 哲学、五组测试模式、gen client、CORS工程
第16章：部署build docker、infra-config、BYOC、CLI 全景速查工程
第17章：AI 原生（一）选择爆炸、-87% 代码、三道防线、三件套总览重点
第18章：AI 原生（二）llm-rules init、规则文件解剖、15 个技能、SKILL.md 机制重点
第19章：AI 原生（三）MCP 19 工具九类、接入配置、四大工作流、安全边界重点
第20章：AI 原生（四）三层上下文、标准开发循环、反模式、团队落地清单重点

三、建议路线

  • 第一次接触 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 的核实为准）。

本章目录
一、学习目标二、章节结构三、建议路线四、贯穿全书的心智模型五、资料边界Related Documents
苏ICP备2025204887号-2