Fastify路由自动分组问题（CmdProtocol与CloudTask）

问题描述 #

使用Fastify的register()注册路由时，首字母相同的路由会被自动归至同一节点。路由注册代码如下：

import { LoginRouter } from "./Login.js";
import { NetProtocolRouter } from "./NetProtocol.js";
import { CmdProtocolRouter } from "./CmdProtocol.js";
import { CloudTaskRouter } from "./CloudTask.js";
import { BotTelegramRouter } from "./BotTelegram.js";
import { EventTrrigerRouter } from "./EventTrriger.js";

export default async function router(fastify, _options) {
    fastify.register(async (instance) => {
        await instance.register(LoginRouter, { prefix: "/login" });
        await instance.register(NetProtocolRouter, { prefix: "/netProtocol" });
        await instance.register(CmdProtocolRouter, { prefix: "/cmdProtocol" });
        await instance.register(EventTrrigerRouter, { prefix: "/eventTrriger" });
        await instance.register(BotTelegramRouter, { prefix: "/botTelegram" });
        await instance.register(CloudTaskRouter, { prefix: "/cloudTask" });
    }, { prefix: '/api' });
}

执行printRoutes()后，cmdProtocol与cloudTask被分组到同一个c节点下，而非独立路由。预期输出应为：

├── /api/
│   ├── login (POST)
│   ├── netProtocol (POST, GET, HEAD)
│   ├── cmdProtocol (POST)
│   ├── cloudTask/TallyingLotto (POST)
│   ├── eventTrriger/UpdateLotto (POST)
│   ├── botTelegram/telegram/webhook (POST)

已尝试以下方案但均未解决：

• 启用caseSensitive: true
• 单独注册路由
• 在路由文件中使用相对路径

问题解答 #

1. 自动分组的原因 #

Fastify内部通过**前缀树（Trie Tree）**结构组织路由，这是为了优化路由匹配性能而设计的机制。相同起始字符的路由前缀会被聚合到同一分支节点，减少路由匹配时的遍历次数，提升请求处理效率。printRoutes()的输出直接映射了这一内部结构，所以会出现首字母相同的路由被分组的情况。

2. 阻止分组的方法 #

Fastify官方没有提供直接关闭路由树聚合显示的配置项，但可以通过两种方式实现预期的扁平化输出：

• 自定义路由打印逻辑：通过fastify.routes获取所有路由的原始数据，自行遍历并格式化输出，完全脱离内置printRoutes()的分组逻辑。示例代码：

  function printCustomRoutes(fastify) {
    console.log('├── /api/');
    fastify.routes.forEach(route => {
      if (route.path.startsWith('/api/')) {
        const trimmedPath = route.path.replace('/api/', '');
        console.log(`│   ├── ${trimmedPath} (${route.methods.join(', ')})`);
      }
    });
  }
  // 在所有路由注册完成后调用
  printCustomRoutes(fastify);
  

• 调整路由前缀命名：若必须使用内置printRoutes()，可给首字母相同的路由前缀添加差异化起始字符（如将cloudTask改为/cCloudTask），但此方式会改变实际路由路径，仅适合测试或临时场景。

3. 是Bug还是预期优化？ #

这是Fastify的预期优化，并非Bug。路由前缀树是Fastify高性能路由匹配的核心基础，printRoutes()的输出目的是让开发者直观了解路由的底层存储结构，而非单纯展示扁平化的路由列表。

内容的提问来源于stack exchange，提问作者Dongpyo Lee