h3 路由参数在 PUT 和 DELETE 方法中的使用注意事项

在 Node.js 生态中，h3 是一个轻量级的 HTTP 框架，以其简洁和高效著称。最近在使用过程中，开发者发现了一个关于路由参数解析的有趣现象，特别是在 PUT 和 DELETE 方法中。本文将深入分析这个问题及其解决方案。

问题现象

当开发者尝试在 h3 的路由处理器中定义带有参数的 PUT 或 DELETE 路由时，发现参数无法正确解析。例如，定义如下路由：

router.put('user/:user/pen/:id', handler)

在处理器中获取参数时，得到的不是预期的结构化参数对象，而是将所有路径部分合并为一个 _ 属性的对象：

{ _: 'user/1/pen/1' }

根本原因

经过深入排查，发现这个问题源于两个关键因素：

1. 缺少前导斜线：路由定义时没有在路径前添加 / 字符。h3 的路由解析器对路径格式有严格要求，缺少前导斜线会导致解析异常。

2. Radix3 路由器的限制：h3 当前版本使用的 Radix3 路由器在处理 HTTP 方法时存在固有局限性，特别是对 PUT 和 DELETE 方法的支持不够完善。

解决方案

添加前导斜线

最简单的解决方案是确保所有路由路径都以 / 开头：

router.put('/user/:user/pen/:id', handler)

这样修改后，参数就能正确解析为：

{
  user: '1',
  id: '2'
}

统一参数命名

对于不同 HTTP 方法使用相同路径但不同参数名的情况，Radix3 存在识别问题。建议在不同方法中使用相同的参数名：

router.get('/api/:id', handler)
router.delete('/api/:id', handler)

而不是：

router.get('/api/:get', handler)
router.delete('/api/:delete', handler)

未来改进

h3 团队已经意识到这个问题，并在即将发布的 v2 版本中进行了改进：

1. 采用了新的 rou3 路由器，原生支持 HTTP 方法匹配
2. 提供了更稳定和一致的路由参数解析行为
3. 消除了当前版本中的各种边缘情况

最佳实践建议

1. 始终在路由路径前添加 / 字符
2. 在不同 HTTP 方法的路由中使用一致的参数命名
3. 考虑升级到 h3 v2 以获得更完善的路由功能
4. 在复杂路由场景下进行充分测试

通过遵循这些建议，开发者可以避免大多数路由参数相关的问题，构建更健壮的 HTTP 服务。