ts-rest 项目教程

ts-rest 项目教程

ts-rest RPC-like client, contract, and server implementation for a pure REST API 项目地址: https://gitcode.com/gh_mirrors/ts/ts-rest

1. 项目介绍

ts-rest 是一个用于纯 REST API 的 RPC 风格的客户端、合约和服务器实现。它提供了一种简单的方式来定义 API 合约，这些合约可以在应用程序中同时被消费和实现，从而实现端到端的类型安全，而无需代码生成。

主要特点

• 端到端类型安全：通过定义合约，确保客户端和服务器之间的类型安全。
• RPC 风格的客户端 API：提供类似于 RPC 的客户端接口，简化 API 调用。
• 小包大小：轻量级实现，减少包大小。
• 无代码生成：无需代码生成，直接使用 TypeScript 类型。
• Zod 支持：支持 Zod 进行运行时验证。
• 全可选的 OpenAPI 集成：提供完整的 OpenAPI 集成选项。

2. 项目快速启动

安装

首先，确保你已经安装了 Node.js 和 npm。然后，通过以下命令安装 ts-rest：

npm install @ts-rest/core @ts-rest/client @ts-rest/server

定义合约

在项目中定义一个共享的 API 合约：

import { c } from '@ts-rest/core';
import { z } from 'zod';

const contract = c.router({
  getPosts: {
    method: 'GET',
    path: '/posts',
    query: z.object({
      skip: z.number(),
      take: z.number(),
    }),
    responses: {
      200: c.type<Post[]>(),
    },
    headers: z.object({
      'x-pagination-page': z.coerce.number().optional(),
    }),
  },
});

实现服务器端

在服务器端实现合约：

import { s } from '@ts-rest/server';
import { prisma } from './prisma';

const router = s.router(contract, {
  getPosts: async ({ query: { skip, take } }) => {
    const posts = await prisma.post.findMany({
      skip,
      take,
    });
    return {
      status: 200,
      body: posts,
    };
  },
});

客户端调用

在客户端使用 RPC 风格的接口调用 API：

import { client } from '@ts-rest/client';

const apiClient = client(contract, { baseUrl: 'http://localhost:3000' });

const result = await apiClient.getPosts({
  headers: { 'x-pagination-page': 1 },
  query: { skip: 0, take: 10 },
});

console.log(result);

3. 应用案例和最佳实践

应用案例

• 博客系统：使用 ts-rest 定义博客系统的 API 合约，确保前后端类型安全。
• 电商系统：在电商系统中，使用 ts-rest 定义商品、订单等模块的 API 合约，简化 API 调用。

最佳实践

• 合约优先：始终从合约开始设计，确保前后端一致性。
• 类型安全：充分利用 TypeScript 的类型系统，减少运行时错误。
• Zod 验证：使用 Zod 进行运行时验证，确保数据的有效性。

4. 典型生态项目

• Prisma：一个现代化的数据库工具，与 ts-rest 结合使用，可以简化数据库操作。
• Next.js：一个 React 框架，与 ts-rest 结合使用，可以快速构建全栈应用。
• Fastify：一个高性能的 Node.js 框架，与 ts-rest 结合使用，可以提升 API 性能。

通过以上步骤，你可以快速上手 ts-rest，并将其应用于实际项目中。

ts-rest RPC-like client, contract, and server implementation for a pure REST API 项目地址: https://gitcode.com/gh_mirrors/ts/ts-rest