moai-lang-typescript

快速参考（30 秒）

TypeScript 5.9+ 开发专家——使用 React 19、Next.js 16 和类型安全 API 模式进行现代 TypeScript 开发。

自动触发：扩展名为 .ts、.tsx、.mts 或 .cts 的文件、TypeScript 配置、React 或 Next.js 项目

核心技术栈：

• TypeScript 5.9：延迟模块求值、装饰器、satisfies 运算符
• React 19：服务器组件、use Hook、Actions、并发功能
• Next.js 16：App Router、Server Actions、中间件、ISR/SSG/SSR
• 类型安全 API：tRPC 11、Zod 3.23、tanstack-query
• 测试：Vitest、React Testing Library、Playwright

快速命令：

使用 npx create-next-app 创建 Next.js 16 项目，并启用 latest、typescript、tailwind 和 app 标志。使用 npm install 安装类型安全 API 技术栈：trpc server、client、react-query、zod 和 tanstack react-query。使用 npm install D 标志安装测试技术栈：vitest、testing-library react 和 playwright test。

---

实现指南（5 分钟）

TypeScript 5.9 关键功能

使用 Satisfies 运算符进行类型检查而不扩大类型范围：

将 Colors 类型定义为 red、green 和 blue 字符串字面量的联合类型。创建 palette 对象，其中 red 为数字数组，green 为十六进制字符串，blue 为数字数组。对 Record<Colors, string | number[]> 使用 satisfies 运算符。现在，palette.red 可以使用 map 方法，因为它被推断为数字数组；palette.green 可以使用 toUpperCase，因为它被推断为字符串。

延迟模块求值：

使用 import defer 和星号，将重型模块路径导入为命名空间。在需要该模块的函数中访问命名空间属性，该模块会在首次使用时加载。

现代装饰器第 3 阶段：

创建一个 logged 函数装饰器，接收 target 函数和 ClassMethodDecoratorContext。返回一个函数，记录方法名称，然后使用 apply 调用 target。将 logged 装饰器应用于一个获取数据的类方法。

React 19 模式

App Router 中默认使用服务器组件：

对于 app/users/[id]/page.tsx 中的页面组件，将 PageProps 接口定义为包含 params 属性，该属性是一个含有 id 字符串的对象的 Promise。创建一个 async 默认函数，等待 params，查询数据库获取用户；如果未找到，则调用 notFound；最后返回包含用户名称的 main 元素。

使用 use Hook 解包 Promise 和 Context：

在标记了 use client 指令的客户端组件中，从 react 导入 use。创建一个接收 userPromise 属性的 UserProfile 组件，其类型为 Promise。使用 use Hook 传入该 Promise，使组件挂起直至 Promise 完成。返回包含用户名称的 div。

使用 Actions 和服务器函数处理表单：

在标记了 use server 指令的 server actions 文件中，导入 revalidatePath。使用 zod 创建 CreateUserSchema，验证 name 和 email。创建一个 async createUser 函数，接收 FormData，使用 schema 解析数据，在数据库中创建用户，并重新验证路径。

使用 useActionState 处理表单状态：

在客户端组件中，导入 useActionState。创建一个表单组件，从 useActionState（传入 createUser action）中解构出 state、action 和 isPending。返回一个表单，设置 action 属性；当处于 pending 状态时禁用输入框；按钮显示动态文本；并展示 state 中的错误消息。

Next.js 16 App Router

路由结构：

app 目录包含用于根布局的 layout.tsx、用于首页路由的 page.tsx、用于加载界面的 loading.tsx、用于错误边界的 error.tsx，以及用于 API 路由的 api/route.ts。users 等子目录包含用于列表的 page.tsx 和用于动态路由的 [id]/page.tsx。路由组使用括号，例如 (marketing)/about/page.tsx。

元数据 API：

导入 Metadata 类型。导出 metadata 对象，其中 title 是包含 default 和 template 的对象，description 是字符串。导出异步 generateMetadata 函数，该函数接收 params，等待 params，获取用户，并返回一个将 title 设为用户名的对象。

带验证的 Server Actions：

在服务端文件中，导入 zod、revalidatePath 和 redirect。定义包含 id、name 和 email 验证规则的 UpdateUserSchema。创建接收 prevState 和 formData 的异步 updateUser 函数。使用 safeParse 解析；若验证失败，则返回错误；更新数据库后，重新验证路径并重定向。

使用 tRPC 构建类型安全的 API

服务端设置：

从 trpc server 导入 initTRPC 和 TRPCError。通过调用 initTRPC.context 并传入 Context 类型，然后调用 create 来创建 t。从 t 导出 router、publicProcedure 和 protectedProcedure。protectedProcedure 使用中间件检查会话用户；若不存在，则抛出 UNAUTHORIZED 错误。

路由器定义：

导入 zod。使用 router 函数创建 userRouter。使用 publicProcedure 定义 getById 过程，其输入架构要求 id 为 UUID 字符串，查询逻辑则按 ID 查找用户。使用 protectedProcedure 定义 create 过程，其输入架构包含 name 和 email，变更逻辑则创建用户。

客户端用法：

在客户端组件中，创建 UserList 函数，使用 trpc.user.list.useQuery 并传入 page 参数。解构出 data 和 isLoading。使用 trpc.user.create.useMutation 创建变更。返回加载状态或用户列表。

Zod 架构模式

复杂验证：

创建 UserSchema，使用 z.object 包含以下字段：作为 UUID 字符串的 id、具有最小和最大长度限制的 name、符合电子邮件格式的 email、取值为 admin、user 和 guest 的枚举 role，以及使用 coerce.date 的 createdAt。应用 strict 方法。从架构推断出 User 类型。创建 CreateUserSchema，省略 id 和 createdAt，扩展 password 和 confirmPassword 字段，并添加 refine，以自定义消息和路径验证两次密码是否匹配。

状态管理

使用 Zustand 管理客户端状态：

从 zustand 和 middleware 导入 create。定义 AuthState 接口，其中包含类型为 User 或 null 的 user、login 方法和 logout 方法。创建 useAuthStore，使用 create 函数，并套用 devtools 和 persist 中间件。将初始 user 设为 null，login 设置 user，logout 将 user 设为 null。persist 使用 auth-storage 作为名称。

使用 Jotai 管理原子状态：

从 jotai 和 jotai/utils 导入 atom 和 atomWithStorage。创建初始值为 0 的 countAtom。创建派生原子 doubleCountAtom，读取 countAtom 并将其乘以 2。使用 atomWithStorage 创建 themeAtom，在存储中持久化 light 或 dark 主题。

---

高级模式

如需全面的文档，包括高级 TypeScript 模式、性能优化、测试策略和部署配置，请参阅：

• reference.md：完整的 API 参考、Context7 库映射和高级类型模式
• examples.md：可用于生产环境的代码示例、全栈模式和测试模板

Context7 集成

对于 TypeScript 文档，请使用 microsoft/TypeScript，并选择 decorators satisfies 主题。对于 React 19，请使用 facebook/react，并选择 server-components use-hook。对于 Next.js 16，请使用 vercel/next.js，并选择 app-router server-actions。对于 tRPC，请使用 trpc/trpc，并选择 procedures middleware。对于 Zod，请使用 colinhacks/zod，并选择 schema validation。

---

配合良好的工具

• moai-domain-frontend：用于 UI 组件和样式模式
• moai-domain-backend：用于 API 设计和数据库集成
• moai-library-shadcn：用于组件库集成
• moai-workflow-testing：用于测试策略和模式
• moai-foundation-quality：用于代码质量标准
• moai-essentials-debug：用于调试 TypeScript 应用

---

快速故障排除

TypeScript 错误：

运行 npx tsc 并使用 noEmit 标志，仅执行类型检查。运行 npx tsc 并使用 generateTrace 标志和输出目录，生成性能跟踪。

React 和 Next.js 问题：

运行 npm run build 检查构建错误。运行 npx next lint 执行 ESLint 检查。删除 .next 目录，然后运行 npm run dev 清除缓存。

类型安全模式：

创建一个接收 never 类型参数的 assertNever 函数，在遇到意外值时抛出错误，并在穷尽式 switch 语句中使用。创建一个名为 isUser 的类型守卫函数，检查值是否为包含 id 属性的对象，并返回类型谓词。

---

最后更新：2026-01-11 状态：活跃（v1.1.0）