Waku项目中文件系统路由API根路径自定义方案探讨

在Waku框架中，文件系统路由(FS Router)是一个便捷的功能，它允许开发者通过文件系统结构自动生成路由。默认情况下，API路由会被映射到/api路径下，这在某些场景下可能会与现有系统产生冲突。

背景与问题

许多现代Web框架都采用了基于文件系统的路由机制，这种设计理念让开发者能够直观地通过目录结构来定义应用路由。Waku框架也采用了这种模式，其中API路由默认被放置在api目录下，对应的URL路径为/api。

然而，在实际开发中，我们经常会遇到需要自定义API根路径的情况。例如：

1. 项目已有遗留API系统运行在/api路径下
2. 需要为不同版本的API提供不同的基础路径(如/v1/api, /v2/api)
3. 需要将API路由与其他类型的路由区分开来

现有解决方案分析

Waku框架目前提供了两种处理路由的方式：

1. 文件系统路由(FS Router)：简单易用，但配置选项有限
2. 底层createPages API：灵活性强，但需要更多手动配置

在文件系统路由的实现中，API路径是硬编码的，这限制了框架的灵活性。开发者提出的改进建议主要包括：

1. 允许配置API根路径，而不仅仅是使用固定的/api
2. 考虑使用文件扩展名(如.api.ts)来标识API路由文件
3. 提供更灵活的配置选项来定义路由规则

技术实现考量

从技术实现角度来看，修改文件系统路由的API路径配置需要考虑以下因素：

1. 向后兼容性：现有项目升级时不应破坏已有路由
2. 配置简洁性：新增的配置选项应该直观易懂
3. 性能影响：路由解析逻辑不应因配置选项而显著变慢

Waku维护团队在讨论中提到，可以通过扩展unstable_fsRouter函数的参数来支持这一功能。例如新增一个apiDir参数，与现有的pages参数并列，这样既保持了API的简洁性，又提供了足够的灵活性。

最佳实践建议

对于需要自定义API路径的开发者，目前有以下几种可行的解决方案：

1. 直接使用createPages API：虽然需要更多代码，但提供了最大的灵活性
2. 复制并修改fs-router实现：可以基于现有实现进行定制化修改
3. 等待框架原生支持：关注Waku框架的更新，等待官方提供配置选项

在实现自定义路由时，建议考虑以下因素：

• 路由定义的清晰度和可维护性
• 与团队现有开发习惯的一致性
• 未来功能扩展的可能性

未来发展方向

随着Waku框架的成熟，文件系统路由功能很可能会增加更多配置选项。从社区讨论来看，开发者期望的改进方向包括：

1. 支持多级API路径配置
2. 提供更灵活的路由匹配规则
3. 改进路由文件的标识方式(如通过特定扩展名)

这些改进将使Waku框架在保持简单性的同时，能够适应更复杂的应用场景。