Roda是一个轻量级但功能强大的Ruby Web框架，它的路由系统采用树形匹配机制，所有路由在内部组织成一棵路由树。当项目规模变大、路由数量增多时，开发者往往需要一份清晰的路由清单来了解整个应用的路由结构。Roda提供了route_list插件来生成路由列表，而其中负责美化输出的正是PrettyPrint模块，Indent类则专门处理树形缩进。理解这套机制，不仅能帮你更高效地调试路由，也能在需要自定义路由文档输出时得心应手。
Roda路由树的存储结构是怎么样的
要理解缩进打印，首先得知道路由信息是怎么存的。Roda的route_list插件在解析路由时，会从源码中提取路由定义信息，形成一条条包含HTTP动词、路径、源文件位置、行号以及缩进级别的记录。每条记录大致是一个结构体或哈希，核心字段包括 verb（请求方法）、path（路径模板）、identifier（唯一标识）以及 indent（缩进层级数）。
这里的indent字段是关键。Roda的树形路由（tree routing）中，子路由是嵌套在父路由块中的，源码的嵌套深度天然反映了路由的层级关系。route_list插件在静态分析路由代码时，会通过r.on、r.is等分支节点的嵌套深度来计算每条叶子路由的indent值。比如下面这段路由代码：
route do |r|
r.on "albums" do # 第一层分支
r.on Integer do |id| # 第二层分支
r.get "info" do # 第三层叶子路由
# ...
end
end
end
end
解析后，albums/:id/info这条完整路由的indent就是2或3（取决于分支是否计数），它比顶层的/albums要深。PrettyPrint模块输出的每一行都会根据这个indent值在行首填充相应数量的空格，从而在终端或文档中呈现出树形层级。
PrettyPrint与Indent模块的实现原理
PrettyPrint模块位于Roda插件体系中的RouteList子模块内，它本身建立在PrettyPrint标准库的风格之上。Indent类（或缩进处理逻辑，不同版本实现细节略有差异）的核心职责有两个：一是计算当前行应该有多少缩进，二是把缩进转换成实际的空白字符输出。
缩进计算的基本思路是维护一个计数器。每进入一个r.on或r.branch分支块，缩进级别加一；每离开一个分支块，级别减一。叶子路由（r.get、r.post、r.is等终止匹配的路由）在打印时使用当前的缩进级别，而分支节点本身的打印则使用进入前的级别，这样就能让父路由比子路由少一个缩进单位，形成清晰的包含关系。看一个简化的实现示意：
class IndentPrinter
def initialize(routes, indent_size = 2)
@routes = routes
@indent_size = indent_size
end
def render
@routes.map do |route|
"#{' ' * (route.indent * @indent_size)}#{route.verb.to_s.upcase.ljust(6)} #{route.path}"
end.join("\n")
end
end
上面的代码用缩进级别乘以每级缩进的空格数，得到行首空白。真实实现中还会处理verb为nil的情况（分支节点不绑定具体动词）、源码位置信息的对齐，以及PATH_INFO等特殊路由的标注。输出效果类似这样：
GET /albums
GET /albums/:id
GET /albums/:id/info
POST /albums/:id/comments
POST /albums
可以看到，子路由通过缩进明确表达了自己挂在哪个父路由之下，阅读起来一目了然。相比把所有路由平铺输出，树形缩进在路由数量达到几十上百条时优势尤其明显，排查路由冲突或者确认某个前缀下有哪些子路由都会快很多。
自定义缩进打印的实战技巧
默认输出虽然够用，但实际项目中经常有定制需求，比如导出Markdown文档、调整缩进宽度、只打印特定前缀的路由等。Roda本身支持通过route_list插件的选项做一定定制，也可以直接对生成的路由数组做后处理。下面是一个完整的自定义打印器示例，支持过滤和Markdown格式输出：
class MarkdownRoutePrinter
def initialize(routes, indent_size: 4, prefix: nil)
@routes = routes
@indent_size = indent_size
@prefix = prefix
end
def print
lines = filtered.map do |rt|
depth = ' ' * (rt.indent * @indent_size)
if rt.verb
"#{depth}- **#{rt.verb.to_s.upcase}** `#{rt.path}`"
else
"#{depth}- #{rt.path} (branch)"
end
end
lines.join("\n")
end
private
def filtered
return @routes unless @prefix
@routes.select { |rt| rt.path.start_with?(@prefix) }
end
end
# 使用方式：只打印 /api 前缀的路由，缩进用4个空格
puts MarkdownRoutePrinter.new(routes, indent_size: 4, prefix: "/api").print
这段代码做了三件事：按indent字段生成缩进空格、区分分支节点和叶子路由的展示样式、按路径前缀过滤。运行后可以直接把结果粘贴到项目的API文档里。如果你希望输出到终端时带颜色，还可以引入rainbow之类的gem，把verb染成不同颜色，GET用绿色、POST用黄色、DELETE用红色，进一步提升可读性。
另一个实用技巧是结合Rake任务自动化。在项目的Rakefile中注册一个routes任务，每次需要查看路由时执行rake routes即可，团队协作时大家看到的路由视图保持一致，避免各自手工查看产生偏差。
desc "打印应用的路由树" task :routes do require_relative "./app" routes = Roda::RodaRequest.route_list # 具体获取方式视项目结构而定 puts MarkdownRoutePrinter.new(routes).print end
最后提醒一点：缩进打印依赖路由源码的静态分析，对于通过元编程动态生成的路由，route_list可能无法准确捕捉。遇到这种情况，可以在生成路由时手动维护一份路由清单，或者在开发环境中通过中间件拦截请求路径来补充验证，确保文档与实际行为一致。