在Roda中，所有请求入口都集中在route块里，通过r.on、r.is、r.get等调用可以组合出非常灵活的分支结构。随着嵌套条件变多，代码缩进虽然能反映一部分层级，但对跨多个文件的复杂应用来说，想快速确认某个路径会经过哪些匹配节点仍然很费劲。RouteList::Tree插件会在应用启动阶段把完整的路由树打印到标准输出，每个分支的请求方法、路径片段和嵌套关系都被清晰标记出来。这个输出可以当作开发时的路由地图，也能辅助排查404、误匹配和中间件遗漏问题。它比单纯翻源码更直观，尤其适合接手已有项目时快速建立整体路由认知。
加载RouteList::Tree并查看基础输出
默认情况下Roda不会输出路由树，需要先加载插件。通常在应用类里直接调用plugin即可，也可以通过条件配置只在开发环境启用。下面是一个最小可运行示例，它定义了api/v1下的用户与文章接口。
require 'roda'
class App < Roda
plugin :route_list_tree
route do |r|
r.on 'api' do
r.on 'v1' do
r.get 'users' do
'user list'
end
r.on 'posts' do
r.get do
'post list'
end
r.post do
'create post'
end
end
end
end
end
end
应用加载后，RouteList::Tree会扫描整个route块，并把得到的分支关系打印出来。输出内容大致类似下面的缩进列表，其中GET、POST来自r.get和r.post，路径片段则按照声明顺序逐层拼装。
App |-- GET api/v1/users |-- POST api/v1/posts |-- GET api/v1/posts
这个输出看起来像平面路径列表，但实际上它保留了嵌套结构。当同一层级出现多个条件分支时，缩进会直接展示谁属于谁。比如users和posts都挂在api/v1之下，而posts内部又同时存在GET和POST两个末端叶子。这样不用来回跳转定义位置，也能明白一个请求从根节点到处理逻辑需要依次满足哪些条件。
与普通的RouteList插件相比，Tree版本更侧重结构而不是最终路径。普通RouteList往往会合并末端路由，但一旦遇到条件复杂的r.on嵌套，合并后的列表反而不容易看出分支来源。Tree插件保留声明时的层级，因此对理解路由组织方式更有帮助。
条件分支、通配符与动态段在树中的呈现
Roda路由不只是静态路径，还支持字符串、符号、正则、数组以及r.is的精确匹配。RouteList::Tree会把这些条件以不同形式显示出来，帮助区分静态片段和动态片段。例如给一个订单模块定义动态id和搜索入口时，树中会出现类型标记或参数化节点。
route do |r|
r.on 'orders' do
r.get do
r.on Integer do |id|
"show order #{id}"
end
end
r.on 'search' do
r.get do
'search orders'
end
end
end
end
读取树输出时，可以重点关注那些包含Integer、String或其他正则条件的节点。它们通常意味着该分支会捕获一类值，而不是只匹配固定文字。静态段和动态段在树中交错出现时，阅读顺序就是请求匹配顺序。如果想把r.root作为首页处理，也要在树里确认它是否出现在正确的父节点下面，否则很容易被更宽泛的r.on提前截走。
对于r.on ['users','members']这种数组匹配，树会列出多个候选路径，但它们共享同一个处理块。查看输出可以确认这些候选路径是否都挂载在预期位置。若某个数组元素写错而没有被路由树显示，也能立即在开发阶段发现，而不必等到请求报404。
有时同一个r.on下既有GET又有POST，树会按请求方法分别展示。这比读源码更容易发现遗漏，例如某个POST分支被外层GET条件包裹，导致POST请求永远无法进入。路由树把方法节点显式列出后，这类结构问题会暴露得很直接。
用环境变量控制打印时机
插件默认在应用加载后输出路由树，这在生产环境会带来噪音，甚至可能暴露内部接口结构。常见做法是只让它在开发环境或设置了专用环境变量时加载。下面这段配置就通过ENV判断是否启用插件。
if ENV['RODA_ROUTE_LIST_TREE'] == '1' plugin :route_list_tree end
这样默认启动不会打印路由树，只有显式设置变量才会触发。例如在终端执行：
RODA_ROUTE_LIST_TREE=1 bundle exec rackup
也可以结合RACK_ENV判断，只在development环境开启。把这段配置集中放在config.ru或初始化脚本里，比直接写在应用类顶部更灵活。需要注意，如果使用环境变量控制，变量要在应用加载前生效，否则类定义已经完成，条件判断就不会再次执行。
对于使用容器或部署平台的场景，可以在开发环境的配置中心设置RODA_ROUTE_LIST_TREE=1，生产环境保持未设置状态。这样路由树成为开发调试的临时入口，不会影响线上日志和启动性能。
利用路由树定位请求匹配问题
当线上或本地某个请求进入错误的处理块时，路由树是很好的第一手线索。例如下面的配置存在顺序问题，会把/admin/users错误地交给宽泛的通配分支处理。
route do |r|
r.on String do |section|
"public page for #{section}"
end
r.on 'admin' do
r.get 'users' do
'admin user page'
end
end
end
从路由树的打印顺序可以看出，String分支比admin分支更早出现，并且它会捕获任意单段路径。请求/admin/users时，Roda先进入String块，把admin当作section参数，后续的admin分支自然无法再匹配。修复方式是把更精确的admin分支放到通配分支之前。
route do |r|
r.on 'admin' do
r.get 'users' do
'admin user page'
end
end
r.on String do |section|
"public page for #{section}"
end
end
除了顺序问题，路由树还能帮助发现重复前缀。如果多个模块都写了r.on 'api'，树中会出现多个同级api节点，说明可以提取公共分支来减少重复。过深的嵌套也会在树中变得非常明显，此时可以考虑把部分子路由拆成插件或独立方法，让结构更扁平。调试时打印一次完整路由树，通常就能定位大多数路径匹配异常。
把RouteList::Tree当作日常开发工具而不是在线监控组件，是使用它的正确方式。它提供的是静态扫描结果，不依赖真实请求流量，因此在启动阶段就能发现结构性问题。结合环境变量控制、条件分支解读和顺序排查，这个小插件能显著降低Roda项目路由维护成本。
Roda路由树RouteList TreeRuby路由调试修改时间：2026-09-18 07:16:14