ts-rest核心库中可选路径参数处理问题解析

在开发RESTful API客户端时，路径参数的处理是一个基础但关键的功能。ts-rest作为一个类型安全的API契约库，其核心模块@ts-rest/core在处理可选路径参数时存在一个值得注意的问题。

问题现象

当API路径中包含可选参数时（例如/applications/:id/:version?，其中version为可选参数），即使客户端调用时明确提供了可选参数的值，ts-rest客户端也不会将该参数插入到最终请求的URL中。这导致实际请求的URL与预期不符，例如：

// 契约定义
const contract = c.router({
  getApplication: {
    method: 'GET',
    path: `/applications/:id/:version?`,
    // ...其他配置
  },
})

// 客户端调用
await client.getApplication({
  params: {
    id: 'id1',
    version: 'version',  // 明确提供了version参数
  },
})

按照预期，应该生成/applications/id1/version的URL，但实际生成的却是/applications/id1/，丢失了version参数。

技术原理分析

这个问题源于insertParamsIntoPath函数的实现逻辑。该函数负责将参数值插入到路径模板中，其核心是通过正则表达式匹配路径中的参数占位符（如:id）并进行替换。

当前实现的正则表达式/:([^/]+)/g只能匹配普通的参数占位符，无法正确处理带有?标记的可选参数。当遇到:version?这样的可选参数时，正则表达式无法匹配，导致参数值无法被插入。

解决方案比较

原始解决方案

最初的解决方案提出了两步处理：

1. 先用现有正则替换参数
2. 再通过额外的replace去除路径中的?字符

这种方法虽然能解决问题，但不够优雅，且可能带来额外的性能开销。

优化方案

更优的解决方案是修改正则表达式本身，使其能够同时匹配普通参数和可选参数。改进后的正则表达式为/:([^/?]+)\??/g，它能够：

1. 匹配:param和:param?两种形式的参数
2. 通过\??匹配可选的问号
3. 保持原有的参数名捕获功能

这种方案更加简洁高效，无需额外的字符串处理步骤。

实现建议

对于开发者而言，如果遇到类似问题，可以采取以下步骤：

1. 检查路径参数定义是否正确使用了?标记
2. 确认客户端调用时是否提供了可选参数的值
3. 如果需要临时解决方案，可以考虑手动构建URL
4. 长期解决方案是等待官方修复或自行fork修改

总结

路径参数处理是API客户端库的核心功能之一。ts-rest虽然在类型安全方面做得很好，但在可选路径参数处理上存在不足。理解这一问题的根源和解决方案，有助于开发者更好地使用ts-rest或类似库，也能在遇到类似问题时快速定位和解决。

对于库的维护者来说，这类边界情况的处理往往决定了库的健壮性和用户体验，值得投入精力完善。