使用 tRPC 和 Deno 构建类型安全的 API

Deno 是一个一体化、零配置的工具链，用于编写 JavaScript 和 TypeScript，并且原生支持 Web 平台 API，这使得它成为快速构建后端和 API 的理想选择。为了使我们的 API 更易于维护，我们可以使用 tRPC，这是一个 TypeScript RPC（远程过程调用）框架，它允许你在没有模式声明或代码生成的情况下构建完全类型安全的 API。

在本教程中，我们将使用 tRPC 和 Deno 构建一个简单的类型安全 API，该 API 返回有关恐龙的信息。

你可以在这个 GitHub 仓库^[1] 中找到本教程的所有代码。

设置 tRPC

要在 Deno 中开始使用 tRPC，我们需要安装所需的依赖项。得益于 Deno 的 npm 兼容性，我们可以使用 tRPC 包的 npm 版本以及 Zod 进行输入验证：

deno install npm:@trpc/server@next npm:@trpc/client@next npm:zod jsr:@std/path

这将安装最新的 tRPC 服务器和客户端包，Zod 用于运行时类型验证，以及 Deno 标准库的 path 工具。这些包将允许我们在客户端和服务器代码之间构建一个类型安全的 API 层。

这将在项目根目录下创建一个 deno.json 文件来管理 npm 和 jsr 依赖项：

{

  "imports": {

    "@std/path": "jsr:@std/path@^1.0.6",

    "@trpc/client": "npm:@trpc/client@^11.0.0-rc.593",

    "@trpc/server": "npm:@trpc/server@^11.0.0-rc.593",

    "zod": "npm:zod@^3.23.8"

  }

}

设置 tRPC 服务器

构建我们的 tRPC 应用程序的第一步是设置服务器。我们将从初始化 tRPC 和创建基础路由器和过程构建器开始。这些将是我们定义 API 端点的基础。

创建一个 server/trpc.ts 文件：

// server/trpc.ts

import { initTRPC } from "@trpc/server";



/**

 * Initialization of tRPC backend

 * Should be done only once per backend!

 */

const t = initTRPC.create();



/**

 * Export reusable router and procedure helpers

 * that can be used throughout the router

 */

export const router = t.router;

export const publicProcedure = t.procedure;

这初始化了 tRPC 并导出了我们将用于定义 API 端点的路由器和过程构建器。publicProcedure 允许我们创建不需要身份验证的端点。

接下来，我们将创建一个简单的数据层来管理我们的恐龙数据。创建一个 server/db.ts 文件：

// server/db.ts

import { join } from "@std/path";



type Dino = { name: string; description: string };



const dataPath = join("data", "data.json");



async function readData(): Promise<Dino[]> {

  const data = await Deno.readTextFile(dataPath);

  return JSON.parse(data);

}



async function writeData(dinos: Dino[]): Promise<void> {

  await Deno.writeTextFile(dataPath, JSON.stringify(dinos, null, 2));

}



export const db = {

  dino: {

    findMany: () => readData(),

    findByName: async (name: string) => {

      const dinos = await readData();

      return dinos.find((dino) => dino.name === name);

    },

    create: async (data: { name: string; description: string }) => {

      const dinos = await readData();

      const newDino = { ...data };

      dinos.push(newDino);

      await writeData(dinos);

      return newDino;

    },

  },

};

这创建了一个简单的基于文件的数据库，它将恐龙数据读取和写入到一个 JSON 文件中。在生产环境中，你通常会使用一个合适的数据库，但这对我们的演示来说已经足够了。

⚠️️ 在本教程中，我们硬编码数据并使用基于文件的数据库。然而，你可以连接到各种数据库并使用 ORM，如 Drizzle 或 Prisma。

最后，我们需要提供实际的数据。让我们创建一个 ./data.json 文件，其中包含一些示例恐龙数据：

[

  {

    "name": "Aardonyx",

    "description": "An early stage in the evolution of sauropods."

  },

  {

    "name": "Abelisaurus",

    "description": "\"Abel's lizard\" has been reconstructed from a single skull."

  },

  {

    "name": "Abrictosaurus",

    "description": "An early relative of Heterodontosaurus."

  },

  {

    "name": "Abrosaurus",

    "description": "A close Asian relative of Camarasaurus."

  },

  ...

]

现在，我们可以创建我们的主服务器文件，它定义了我们的 tRPC 路由器和过程。创建一个 server/index.ts 文件：

import { createHTTPServer } from "@trpc/server/adapters/standalone";

import { z } from "zod";

import { db } from "./db.ts";

import { publicProcedure, router } from "./trpc.ts";



const appRouter = router({

  dino: {

    list: publicProcedure.query(async () => {

      const dinos = await db.dino.findMany();

      return dinos;

    }),

    byName: publicProcedure.input(z.string()).query(async (opts) => {

      const { input } = opts;

      const dino = await db.dino.findByName(input);

      return dino;

    }),

    create: publicProcedure

      .input(z.object({ name: z.string(), description: z.string() }))

      .mutation(async (opts) => {

        const { input } = opts;

        const dino = await db.dino.create(input);

        return dino;

      }),

  },

  examples: {

    iterable: publicProcedure.query(async function* () {

      for (let i = 0; i < 3; i++) {

        await new Promise((resolve) => setTimeout(resolve, 500));

        yield i;

      }

    }),

  },

});



// Export type router type signature, this is used by the client.

export type AppRouter = typeof appRouter;



const server = createHTTPServer({

  router: appRouter,

});



server.listen(3000);

这设置了三个主要端点：

• dino.list：返回所有恐龙
• dino.byName：按名称返回特定恐龙
• dino.create：创建一个新的恐龙
• examples.iterable：演示 tRPC 对 async iterables 的支持

服务器配置为监听 3000 端口，并将处理所有 tRPC 请求。

虽然你现在可以运行服务器，但你将无法访问任何路由并返回数据。让我们来解决这个问题！

设置 tRPC 客户端

我们的服务器准备好了，我们可以创建一个客户端，它以完全类型安全的方式使用我们的 API。创建一个 client/index.ts 文件：

// client/index.ts

/**

 * This is the client-side code that uses the inferred types from the server

 */

import {

  createTRPCClient,

  splitLink,

  unstable_httpBatchStreamLink,

  unstable_httpSubscriptionLink,

} from "@trpc/client";

/**

 * We only import the `AppRouter` type from the server - this is not available at runtime

 */

import type { AppRouter } from "../server/index.ts";



// Initialize the tRPC client

const trpc = createTRPCClient<AppRouter>({

  links: [

    splitLink({

      condition: (op) => op.type === "subscription",

      true: unstable_httpSubscriptionLink({

        url: "http://localhost:3000",

      }),

      false: unstable_httpBatchStreamLink({

        url: "http://localhost:3000",

      }),

    }),

  ],

});



const dinos = await trpc.dino.list.query();

console.log("Dinos:", dinos);



const createdDino = await trpc.dino.create.mutate({

  name: "Denosaur",

  description:

    "A dinosaur that lives in the deno ecosystem. Eats Nodes for breakfast.",

});

console.log("Created dino:", createdDino);



const dino = await trpc.dino.byName.query("Denosaur");

console.log("Denosaur:", dino);



const iterable = await trpc.examples.iterable.query();



for await (const i of iterable) {

  console.log("Iterable:", i);

}

这段客户端代码展示了 tRPC 的几个关键特性：

1. 从服务器路由器类型推断。客户端自动从服务器通过 AppRouter 类型导入继承所有类型定义。这意味着你将获得完整的类型支持和编译时类型检查，适用于你所有的 API 调用。如果你在服务器上修改了一个过程，TypeScript 将立即标记任何不兼容的客户端使用。
2. 进行查询和修改。示例演示了两种类型的 API 调用：用于无副作用获取数据的查询（list 和 byName）和用于修改服务器端状态的操作（create）。客户端自动知道每个过程的输入和输出类型，在整个请求周期中提供类型安全性。
3. 使用异步可迭代对象。examples.iterable 演示了 tRPC 对使用异步可迭代对象流式传输数据的支持。这个特性特别适合实时更新或分块处理大型数据集。

现在，让我们启动服务器来看看它在行动中的样子。在我们的 deno.json 配置文件中，让我们创建一个新属性 tasks，包含以下命令：

{

  "tasks": {

    "start": "deno -A server/index.ts",

    "client": "deno -A client/index.ts"

  }

}

我们可以使用 deno task 列出可用的任务：

deno task

Available tasks:

- start

    deno -A server/index.ts

- client

    deno -A client/index.ts

现在，我们可以使用 deno task start 启动服务器。之后，我们可以使用 deno task client 运行客户端。你应该看到像这样的输出：

deno task client

Dinos: [

  {

    name: "Aardonyx",

    description: "An early stage in the evolution of sauropods."

  },

  {

    name: "Abelisaurus",

    description: "Abel's lizard has been reconstructed from a single skull."

  },

  {

    name: "Abrictosaurus",

    description: "An early relative of Heterodontosaurus."

  },

  ...

]

Created dino: {

  name: "Denosaur",

  description: "A dinosaur that lives in the deno ecosystem. Eats Nodes for breakfast."

}

Denosaur: {

  name: "Denosaur",

  description: "A dinosaur that lives in the deno ecosystem. Eats Nodes for breakfast."

}

Iterable: 0

Iterable: 1

Iterable: 2

成功！运行 ./client/index.ts 展示了如何创建一个 tRPC 客户端并使用其 JavaScript API 与数据库交互。但是我们如何检查 tRPC 客户端是否正确地从数据库推断类型呢？让我们在 ./client/index.ts 中修改下面的代码片段，将 description 传递一个 number 而不是 string：

// ...

const createdDino = await trpc.dino.create.mutate({

  name: "Denosaur",

  description:

-   "A dinosaur that lives in the deno ecosystem. Eats Nodes for breakfast.",

+   100,

});

console.log("Created dino:", createdDino);

// ...

当我们重新运行客户端：

deno task client

...

error: Uncaught (in promise) TRPCClientError: [

  {

    "code": "invalid_type",

    "expected": "string",

    "received": "number",

    "path": [

      "description"

    ],

    "message": "Expected string, received number"

  }

]

    at Function.from (file:///Users/andyjiang/Library/Caches/deno/npm/registry.npmjs.org/@trpc/client/11.0.0-rc.608/dist/TRPCClientError.mjs:35:20)

    at file:///Users/andyjiang/Library/Caches/deno/npm/registry.npmjs.org/@trpc/client/11.0.0-rc.608/dist/links/httpBatchStreamLink.mjs:118:56

    at eventLoopTick (ext:core/01_core.js:175:7)

tRPC 成功抛出了一个 invalid_type 错误，因为它期望一个 string 而不是 number。

接下来是什么？

现在你对如何使用 Deno 和 tRPC 有了基本的了解，你可以：

1. 使用 Next.js 或 React 构建实际的前端
2. 使用 tRPC 中间件为你的 API 添加身份验证
3. 使用 tRPC 订阅实现实时功能
4. 为更复杂的数据结构添加输入验证
5. 与 PostgreSQL 等合适的数据库集成或使用 Drizzle 或 Prisma 等 ORM
6. 将你的应用程序部署到 Deno Deploy 或任何通过 Docker 的公共云

🦕 祝你在使用 Deno 和 tRPC 进行类型安全编码时愉快！参考资料[1]

源码: https://github.com/denoland/examples/tree/main/with-trpc

本文章转载微信公众号@前端与Deno