ts-rest项目中路径参数(pathParams)的使用详解

ts-rest是一个强大的TypeScript REST API契约库，它通过类型安全的方式定义API接口。在实际开发中，路径参数(pathParams)是一个常见需求，但很多开发者对其具体实现方式存在疑问。本文将详细介绍如何在ts-rest中正确使用路径参数。

路径参数的基本概念

路径参数是URL中动态变化的部分，通常用于标识特定资源。例如，在/users/:id这个路径中，:id就是一个路径参数，表示用户的唯一标识符。

ts-rest中的路径参数实现

在ts-rest中，路径参数通过pathParams属性定义，它接受一个Zod模式(schema)对象。这个模式对象定义了路径参数的类型和验证规则。

基本字符串参数

最常见的路径参数是字符串类型，例如用户ID：

export const contract = c.router({
  getUser: {
    method: 'GET',
    path: '/users/:id',
    pathParams: z.object({
      id: z.string()
    }),
    // 其他配置...
  }
})

在这个例子中，我们定义了一个获取用户信息的接口，其中:id参数被定义为字符串类型。

数值类型参数

有时我们需要路径参数是数值类型，这时可以使用Zod的coerce方法：

export const contract = c.router({
  getUser: {
    method: 'GET',
    path: '/users/:id',
    pathParams: z.object({
      id: z.coerce.number()
    }),
    // 其他配置...
  }
})

z.coerce.number()会将传入的字符串参数自动转换为数字类型，这在处理URL参数时非常有用，因为URL中的所有参数本质上都是字符串。

路径参数的最佳实践

1. 类型明确：始终为路径参数指定明确的类型，不要依赖隐式转换。

2. 参数验证：利用Zod的强大验证功能，可以添加额外的验证规则，例如长度限制、格式验证等。

3. 文档清晰：在API文档中明确说明路径参数的类型和格式要求。

4. 错误处理：考虑路径参数验证失败时的错误处理策略，提供有意义的错误信息。

高级用法

对于更复杂的场景，可以结合Zod的其他功能：

pathParams: z.object({
  id: z.string().uuid(), // 验证UUID格式
  version: z.coerce.number().int().positive() // 正整数
})

这种严格的验证可以确保API接收到符合预期的参数，减少后续处理中的错误。

总结

ts-rest通过结合Zod模式验证，为路径参数提供了类型安全和验证功能。无论是简单的字符串参数还是需要特定格式的复杂参数，都能通过适当的配置实现。开发者应该充分利用这些功能，构建更健壮、更易维护的API接口。

记住，良好的参数定义不仅是技术实现，也是API设计的重要组成部分，直接影响API的易用性和稳定性。