Modern.js BFF 动态路由参数顺序问题解析

Modern.js 是一个现代化的全栈开发框架，其 BFF（Backend For Frontend）功能允许开发者在前后端之间构建中间层。在最新版本 2.67.8 中，框架将 Hono 作为 BFF 函数的默认运行时，取代了原先的 Express。

问题背景

开发者在实际使用中发现，当创建嵌套动态路由（如 api/lambda/registry/[remote]/[env]/index.ts）时，Hono 运行时无法正确解析请求路径。有趣的是，当切换回 Express 插件后，相同的路由却能正常工作。

经过深入排查，发现问题并非出在路由解析本身，而是参数传递顺序的差异。在 Express 运行时中，动态路由参数会按照文件路径中的顺序传递给处理函数；而在 Hono 运行时中，参数的顺序却是相反的。

技术分析

这种差异源于 Hono 和 Express 在处理路由参数时的不同实现方式：

1. Express 运行时：

   • 严格按照文件路径中定义的顺序传递参数
   • 例如 api/lambda/[level]/[id].ts 会先传递 level，再传递 id

2. Hono 运行时：

   • 不保证参数对象的属性顺序
   • 可能导致参数顺序与开发者预期不符

这种差异对于已经基于 Express 运行时开发的项目来说是一个潜在的破坏性变更，可能导致现有业务逻辑出错。

解决方案

Modern.js 团队迅速响应，通过以下方式解决了这个问题：

1. 修改了 Hono 运行时的参数处理逻辑
2. 确保参数顺序与文件路径定义保持一致
3. 发布了临时修复版本供开发者验证

开发者可以通过指定版本号 0.0.0-next-20250609122840 来验证修复效果，该修复已确认在正式版本中发布。

最佳实践建议

1. 版本升级注意事项：

   • 从 Express 迁移到 Hono 时，应检查所有动态路由的参数顺序
   • 考虑编写测试用例验证关键路由的参数传递

2. 错误排查技巧：

   • 遇到 404 响应时，首先检查运行时错误
   • 使用日志记录中间件输出请求参数

3. API 设计建议：

   • 对于关键业务接口，考虑使用命名参数而非位置参数
   • 在文档中明确标注参数顺序要求

Modern.js 团队对社区反馈的快速响应体现了框架的成熟度和开发者友好性。这个案例也提醒我们，在框架升级时，即使是看似微小的运行时变更，也可能对现有业务逻辑产生深远影响。