---
url: /blog-ocean-world/unleash-the-magic-of-type-script-with-ts-rest.md
description: ts-rest 可以實現從伺服器到客戶端的全型別安全，可以有效降低前後端溝通血流成河的機率。(´,,•ω•,,)
---

![unleash-the-magic-of-type-script-with-ts-rest](/unleash-the-magic-of-type-script-with-ts-rest.webp){.cover}

# 前後端不再打架，讓 ts-rest 發揮 TypeScript 的魔法吧！（概念篇）

本文基於 TypeScript，如果沒有採用的小夥伴可以狠心離開惹。~(>\_<。)

或者一起湊個熱鬧。(´▽\`ʃ♡ƪ)

此文為概念篇，顧名思義就是來認識認識何謂 ts-rest。

## 甚麼是 ts-rest？

ts-rest 是基於 TypeScript 的 RESTful API 工具，主要目的在於實現從介面定義開始，涵蓋至伺服器、客戶端的全型別安全，而且無需額外、繁瑣的標註或生成過程。

風格類似 RPC，可以讓 API 呼叫更加直覺，配合 TSDoc 有更完整、詳盡的說明，可以大幅降低使用 API 的心智負擔。

### 優點

* 前後端溝通基於 TypeScript 合約，有完整的型別提示，可以避免很多錯誤
* 資料欄位與端點更明確，可以讓使用者更容易理解 API 功能
* 降低發布、變更導致 API 錯誤的風險

### 缺點

* 學習成本較高
* 需要遵守一定的規範
* 前後端需要有良好的溝通模式或管道

## 從前有個後端和前端

以下範例以 Vue、NestJS 為例，相關套件版本如下：

* @nestjs/core：`10.4.1`
* @ts-rest/core：`3.51.0`
* @ts-rest/nest：`3.51.0`
* zod：`3.23.8`

他們想要合力串接一個資料，叫做 CollectionData。

### 通用資料

前後端手牽手，先討論想要的格式。(*≧︶≦))(￣▽￣* )ゞ

第一步定義傳輸層的 schema，方式與 zod 相同。

[定義 Zod Object](https://zod.dev/?id=objects)

```ts
import { z } from 'zod'

export const collectionDataSchema = z.object({
  id: z.string(),
  /** 名稱 */
  name: z.string(),
  description: z.string(),
  remark: z.string(),
})
export interface CollectionData extends z.infer<
  typeof collectionDataSchema
> { }

// 用 type 也可以，取決於貴團隊的規範
// export type CollectionData = z.infer<typeof collectionDataSchema>
```

接著根據剛剛制定的 schema 和 API 功能定義合約：

[ts-rest：Define Contract](https://ts-rest.com/docs/core/)

```ts
import { AppRoute, initContract } from '@ts-rest/core'
import { z } from 'zod'
import { collectionDataSchema } from './schema'

// 建立 collection-data
export const createCollectionDataDtoSchema = collectionDataSchema.omit({
  id: true,
  timestamp: true,
}).partial({
  remark: true,
  description: true,
})

/**
 * 使用 satisfies 是為了 AppRoute 的欄位提示又可以保留具體內容定義。
 * 當然 as const 也行，只是輸入的過程不會有 AppRoute 欄位提示。
 * const create: AppRoute 會遺失詳細的內容定義，所以最後採用 satisfies。
 */
const create = {
  method: 'POST',
  path: '/v1/collection-data',
  body: createCollectionDataDtoSchema,
  responses: {
    201: collectionDataSchema,
  },
  summary: '建立 collection-data',
} satisfies AppRoute

export const collectionDataContract = initContract().router({
  create,
}, {
  pathPrefix: '/api',
  commonResponses: {
    500: z.object({
      message: z.string(),
    }),
  },
})
```

路人：「怎麼只有一個 create？ಠ\_ಠ」

鱈魚：「我懶。(ツ)」

路人：（抽刀）

鱈魚：「刀下留魚啊 (＃°Д°)，是因為內容太多怕大家會累啦，用心良苦欸。」

## 後端實作（NestJS）

依照官網步驟實作。

[ts-rest：Nest](https://ts-rest.com/docs/nest/)

以下是一個簡單的範例：

```ts
// ...

@Controller()
export class CollectionDataController {
  constructor(
    private readonly loggerService: LoggerService,
    private readonly collectionDataService: CollectionDataService,
  ) { }

  @TsRestHandler(collectionDataContract.create, {
    validateResponses: true
  })
  async create() {
    return tsRestHandler(collectionDataContract.create, async ({
      body: dto,
    }) => {
      const [error, data] = await to(this.collectionDataService.create(dto))
      if (error) {
        this.loggerService.error(`建立 CollectionData 錯誤 :`)
        this.loggerService.error(error)

        return {
          status: 500,
          body: {
            message: '建立 CollectionData 錯誤',
          },
        }
      }

      return {
        status: 201,
        body: data,
      }
    })
  }
}
```

::: tip
那個奇怪的 await to 是因為我用了[這個](./blog-program/await-to-js-keeps-your-promises-slick)，不是寫錯喔。(｡･∀･)ﾉﾞ
:::

開啟 validateResponses 的話，ts-rest 會嚴格驗證 API 響應資料格式是否正確，錯誤的話會直接噴 500，這就表示後端最好在 e2e 測試時，就該把可能情境測出來，只要測試有過，資料格式就不可能錯。

前後端就不用再為了資料有坑吵架了。( ‧ω‧)ノ╰(‧ω‧ )

## 前端實作（Vue）

前端用法有兩種，可以依照需求挑適合的用：

* [Fetch Client](https://ts-rest.com/docs/core/fetch)：用法和 axios、fetch 概念相同。
* [Vue Query](https://ts-rest.com/docs/vue-query)：其實就是 TanStack Query

可以漸進式導入，兩個同時用也沒問題。

個人推薦 Vue Query，雖然有點門檻，可是功能很強很好用。(๑•̀ㅂ•́)و✧

如果都不喜歡，也可以[自定義](https://ts-rest.com/docs/core/custom)。

### 驗證

前端如果呼叫 API 前想先驗證一次參數正確性。例如：驗證 collectionData API 的 body 資料是否正確。

只要取得 contract 中對應路徑的 zod schema 即可。

```ts
const createCollectionDataDto = collectionDataContract.create.body

createCollectionDataDto.parse({
  // ...
})
```

剩下就是 zod 的工作了。(oﾟvﾟ)ノ

[Zod：parse](https://zod.dev/?id=parse)

### 型別

型別則是使用 ts-rest 提供的 [Inferring Types 工具](https://ts-rest.com/docs/core/infer-types)。

例如回應型別可以使用 `ServerInferResponseBody` 推導：

```ts
type Data = ServerInferResponseBody<
  typeof collectionDataContract.create,
  201
>
```

![ServerInferResponseBody](/unleash-the-magic-of-type-script-with-ts-rest/ServerInferResponseBody.png)

ts-rest 還有很多內容，可以[來官網逛逛](https://ts-rest.com/docs/intro)。♪(^∇^\*)

## 所以前後端要怎麼共享合約？

鱈魚：「真是個好問題，當然是複製貼...ᕕ( ﾟ ∀。)ᕗ 」

路人：（拿起球棒）

鱈魚：「開玩笑的啦。∠( ᐛ 」∠)\_」

目前我自己已知不錯的方式有：

* 私有 npm
* monorepo

個人比較推薦使用 monorepo，我們公司也是如此，至於怎麼用 Google 有很多教學，這裡就不贅述囉。ԅ( ˘ω˘ԅ)

## 總結 🐟

* ts-rest 可以讓前後端串接更加嚴謹、自動化
* 介紹後端、前端實作
* 合約可以藉由私有 npm、monorepo 共享

以上恭喜你完全發揮 TypeScript 的魔法惹！ˋ( ° ▽、° )

從此前後端再也不用為資料不一致問題打架了。✧⁑｡٩(ˊᗜˋ\*)و✧⁕｡

甚麼？你說還有很多事情可以吵？╭(°A ,°\`)╮

那就超過本文的探討範圍惹，要打去練舞室打。ᕕ( ﾟ ∀。)ᕗ
