tRPC 架构
了解 tRPC 如何消除 API 模式重复定义。
tRPC 架构 是 CoddyKit 上的免费 TypeScript Academy 课时。 这是第 1 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 TypeScript Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 TypeScript Academy 课程共包含 4 节课。
端到端问题
在典型的网络应用中，服务器定义接口，客户端调用接口。保持两者的类型同步很困难：服务器上的字段一旦改变，客户端可能会在运行时静默地出错。tRPC通过直接共享类型解决了这一问题，无需代码生成。
// Server: returns { id: number; name: string }
// Client: must know that shape exactly
// Without sync: runtime errors when they drifttRPC 是什么
tRPC 是一个使用 TypeScript 构建完全类型化接口的库。服务器定义过程；客户端调用这些过程时就像调用本地函数一样，并且可以根据服务器代码推断出完整的自动补全和类型检查。
// Client call looks like a local function:
// const user = await client.user.byId.query(1);
// user is typed automatically from the server无需代码生成
与 GraphQL 或 OpenAPI 工作流不同，tRPC无需代码生成步骤。不需要编译模式文件，也不需要生成客户端。类型完全通过编译时的 TypeScript 推断从服务器流向客户端。
// No .graphql files, no generated SDK
// Just import a type from the server package路由器就是契约
tRPC 的核心是路由器。它是一棵由过程（查询和变更）组成的树。服务器上的路由器对象，尤其是从它推断出的类型，是与客户端共享的唯一事实来源。
// appRouter (server) defines every procedure
// type AppRouter = typeof appRouter is the contract类型如何共享
服务器仅导出其路由器的类型，而不导出实现。client 导入该类型，并据此为代理客户端标注类型。不会有服务器代码随应用发送到浏览器；只有类型会被发送，而类型会在构建时被擦除。
// server.ts
export type AppRouter = typeof appRouter;
// client.ts
import type { AppRouter } from '../server';query 与 mutation
过程主要分为两种。query读取数据，通常具有幂等性。mutation会更改数据。这种区分对应缓存和 HTTP 语义，也决定 client 调用它们的方式。
// client.user.list.query() -> read
// client.user.create.mutate(...) -> write运行时与类型
tRPC 有两个层面。在运行时，调用会通过适配器处理，以 JSON over HTTP 的形式传输。在编译时，共享的 AppRouter 类型会检查每一次调用。运行时层很薄；类型安全才是价值所在。
// Runtime: POST /trpc/user.byId body: {"input":1}
// Types: client.user.byId.query(1) is checked end to end为什么类型推断胜过代码生成
由于类型是自动推断的，因此无需记住同步步骤。编辑一个过程后，client 会立即反映这一变化；当调用不再匹配时，编辑器会在相应位置显示红色波浪线。反馈是即时的，并且直接存在于您的编辑器中。
// Add a required input field on the server
// -> every client call missing it becomes a type errortRPC 适用的位置
tRPC 非常适合全栈 TypeScript 单体仓库，即 client 和服务器共享代码库的项目，例如 Next.js 应用。它不适用于供其他语言调用的公开接口；对于这类接口，您仍然需要使用与语言无关的规范，例如 OpenAPI 或 GraphQL。
// Great: Next.js app, shared types, internal API
// Not ideal: public API for non-TS consumers整体概览
整体流程是：在 router 上定义过程，导出 router 类型，连接 HTTP 适配器，然后根据该类型创建类型化 client。每一次调用都会根据服务器契约进行检查，而且完全不需要生成代码。接下来的课程将逐一构建这些部分。
// Roadmap:
// 1. initTRPC + procedures + appRouter
// 2. export AppRouter, create typed client
// 3. context + middleware for auth相信编译器
需要转变的思维方式是：接口契约存在于由编译器强制执行的类型中，而不只是存在于文档或运行时验证中。只要能够通过编译，client 和服务器就达成了一致。这种保证就是“端到端类型安全”的含义。
// If client.ts compiles, it matches the current server.快速检查
测试您对 tRPC 架构的理解。
回顾
您已经学会了 tRPC 模型。
- router 就是契约；它的类型是唯一事实来源。
- 服务器仅导出
AppRouter类型，而不导出代码。 - query 读取数据，mutation 写入数据；运行时通过 JSON over HTTP 通信。
- 类型安全来自类型推断，无需代码生成步骤。
下一步：定义 router 和过程。
常见问题解答
「tRPC 架构」课时是免费的吗？
是的 — 「tRPC 架构」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 TypeScript Academy 课程的其余内容，请升级到 CoddyKit PRO。 TypeScript Academy 课程共包含 4 节课。
「tRPC 架构」这节课中我会学到什么？
了解 tRPC 如何消除 API 模式重复定义。 你通过在浏览器中直接运行的动手代码来练习 TypeScript Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 TypeScript Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 TypeScript Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 1 节课，共 4 节。
「tRPC 架构」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 TypeScript Academy 课中编写并运行代码吗？
能。每节 TypeScript Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- tRPC 架构
- 定义路由器与过程
- 客户端—服务器类型推断
- 中间件与上下文