dnsglobe代码架构解析:ratatui、crossterm与hickory-resolver如何协作构建终端TUI
dnsglobe代码架构解析:ratatui、crossterm与hickory-resolver如何协作构建终端TUI
dnsglobe 是一个用 Rust 编写的终端 DNS 传播检查器(Global DNS propagation checker),它并行查询全球 34 个公共 DNS 解析器,并在一幅终端世界地图上实时呈现 DNS 记录的传播进度。本文将深入解析它的代码架构,看看 ratatui、crossterm 与 hickory-resolver 这三大核心组件,是如何在 tokio 事件循环的驱动下协作成一套流畅的 TUI 应用。
一、30 秒认识 dnsglobe:终端里的 DNS 传播观测台
用过 dnschecker.org 这类网页版 DNS 检查工具吗?dnsglobe 把同样的事搬进了终端:输入域名、回车,它立刻向遍布北美、欧洲、亚洲、南半球的 34 个公共解析器(Google Public DNS、Cloudflare、Quad9、OpenDNS 等)发起查询,比较各家答案,并把结果画在一张世界地图上 🌍。
它还有两个网页版没有的杀手特性:
- 监听模式(watch mode):每 30 秒自动轮询,直到记录传播到 100% 的解析器为止;
- 自适应地图:终端够宽时显示平面世界地图,窄终端自动切换成旋转的 3D 地球,两者之间还有平滑的变形动画。
要理解它为什么能做得这么丝滑,答案就藏在三个核心依赖里(见 Cargo.toml):
| 组件 | 版本 | 角色 |
|---|---|---|
| hickory-resolver | 0.26 | DNS 查询引擎:真正把请求发到 34 个解析器 |
| crossterm | 0.29 | 终端事件层:捕获键盘输入、管理 raw 模式 |
| ratatui | 0.30 | 终端渲染层:表格、进度条、世界地图的绘制 |
再加上 tokio 异步运行时和 clap 命令行解析,整个应用的骨架就搭起来了。
二、整体架构:9 个模块各司其职
打开 src/ 目录,你会看到一个刻意保持扁平的模块划分——每个 .rs 文件只负责一件事。项目在 AGENTS.md 中给出了官方的模块地图:
| 文件 | 职责 |
|---|---|
| src/main.rs | CLI 解析(clap)、主事件循环、按键处理、--once 脚本模式 |
| src/app.rs | 核心状态机 App:输入编辑、答案分组、TTL 判定(纯逻辑,无 I/O) |
| src/ui.rs | 所有渲染:地图、表格、进度条、页脚 |
| src/dns.rs | DNS 查询与错误映射(hickory-resolver 的封装层) |
| src/resolvers.rs | 内置的 34 个解析器清单(含地图坐标) |
| src/globe.rs | 正交投影的地球算法与地图面板几何 |
| src/world_data.rs | 海岸线矢量数据(5125 个坐标点) |
| src/sites.rs | Anycast 节点识别(NSID / id.server 探测) |
| src/theme.rs | 主题色角色与 TOML 颜色解析 |
| src/config.rs | 加载 ~/.config/dnsglobe/config.toml 配置文件 |
这套设计遵循一条清晰的铁律(AGENTS.md 原文):逻辑放 app.rs(可测试、无 I/O),渲染放 ui.rs(只读状态)。按键处理在 main.rs 里只调用一行的 App 方法,绝不在事件循环里直接改状态。这种"状态与视图分离"是 TUI 架构中最值得借鉴的一点。
核心状态全部集中在 App 结构体中(src/app.rs):当前域名与光标位置、每个解析器一行的状态 rows、主题视图模式、地图/地球的变形动画状态 globe、排序方式等。App 不持有任何渲染对象,也不发起任何网络请求——它就是一个可以被单元测试反复摆弄的纯数据容器。
三、hickory-resolver 实战:把查询直接打到 34 个解析器
dnsglobe 测的是"每个解析器自己看到的当前答案",而不是本机缓存的结果。所以它刻意不走系统 resolver 配置,而是为每个目标解析器单独构造一个 TokioResolver(src/dns.rs),关键配置很有讲究:
cache_size = 0:关闭客户端缓存,确保拿到解析器自己的视角;attempts = 1+ 3 秒超时:单个解析器超时不拖累整轮;- UDP + TCP 双通道:大 TXT 集、长 MX 列表触发截断时自动走 TCP 回退;
edns0 = true:允许大于 512 字节的 UDP 应答。
当需要 EDNS Client Subnet(--ecs 参数,模拟特定客户端网络的 GeoDNS 答案)时,hickory 的高层 API 没有"按查询附加 EDNS 选项"的钩子,于是代码切换到原始报文路径(src/dns.rs):手工构造 Message、UDP 发包、校验 ID、处理截断回退 TCP——同一套 hickory 的协议类型,从"高级 API"降级到"协议级控制",这正是选择 hickory-resolver 而非纯 std::net 手写 DNS 的好处。
另一个巧思是 NSID 探测(src/sites.rs):每个解析器启动时先被问一句"你是谁家的哪个节点",利用 RFC 5001 的 NSID EDNS 选项,Anycast 服务商会回报 gpdns-yul、res721.qyul1 这类标识,代码从中解析出 IATA 机场码(YUL、YYZ……),让地图上的圆点移到真正为你应答的那个 POP,而不是运营商标称的位置。
四、crossterm 实战:让终端响应每一次按键
终端 TUI 的第一步是"接管"终端:ratatui::init() 进入 raw 模式(禁用回显、直接输出),退出时 ratatui::restore() 恢复现场。而键盘事件的入口在 crossterm 的 EventStream(src/main.rs)——它把终端输入变成一个异步流,任何按键都会变成一个 Event::Key。
dnsglobe 对 crossterm 的用法有三个值得注意的细节:
- Kitty 键盘协议(src/main.rs):在支持 iTerm2、kitty、WezTerm 等现代终端上,主动请求
DISAMBIGUATE_ESCAPE_CODES能力,这样Cmd+←/→(SUPER 修饰键)和Option修饰的按键才能被准确识别——这是实现类 readline 光标移动(按.分段跳词)的前提; - 区分按键按下与释放:事件循环只处理
KeyEventKind::Press,避免 macOS 上按键长按导致的重复事件; - 跨平台回退:macOS 的
Cmd只在 kitty 协议下可见,所以每个快捷键都保留了Ctrl+字母或Home/End这样的通用回退路径(src/main.rs 的handle_key里能看到完整的兼容矩阵)。
按键处理函数 handle_key 本身就是一个很棒的架构示范:它只做"翻译"——把按键映射成一次 App 方法调用(app.cycle_record_type(true)、app.toggle_globe()……),所有状态变更都封装在 App 内部,事件循环自己几乎不含业务逻辑。
五、ratatui 实战:在终端里画出世界地图
渲染全部集中在 src/ui.rs 的 draw 函数中,入口是 ratatui 的 Frame——每帧画布。布局采用嵌套的 Layout:外层垂直切分为 header(输入区)/ body(主体)/ footer(快捷键提示),body 内部再按宽度决定水平切出左侧表格区和右侧地图区。
几个用 ratatui 组件实现的亮点:
- 传播进度条用
LineGauge:查询中显示 spinner +checking… 12/34,结束后变成彩色百分比条(src/ui.rs); - 34 行结果表格用
Table:左缘一个判定符号(✓ ≠ ! ↻ ∅ ✗),右侧是解析器名、位置、IP、Ping、TTL 与过期倒计时;窄终端时列会自适应降级,保证 80 列也能放下完整 IP(src/ui.rs); - 世界地图/旋转地球用
Canvas组件绘制,数据来自 src/world_data.rs 中的 5125 个海岸线坐标点;src/globe.rs 实现了正交投影的数学(球半径、轴倾角、每 100ms 前进 1° 的自转),以及平面地图↔地球之间面板尺寸与投影的插值变形。地图上的每个解析器是一个随状态变色的圆点:绿色=答案一致、洋红=答案不同、红色=错误、黄色=查询中。
配色则统一由 src/theme.rs 管理:UI 里不写死任何颜色,而是引用 accent / agree / differ / error / pending 等语义化角色,用户在 TOML 配置里覆盖单个角色即可全局生效——这同样是"状态与表现解耦"的体现。
六、三大组件协作:从一次按键到一帧新画面
把三块拼起来,整个应用就是一个经典的 select 事件循环(src/main.rs),每圈做四件事:
- 先画一帧:
terminal.draw(|frame| ui::draw(frame, &mut app))——ratatui 拿到最新App状态,重绘整个终端; - 再等事件:用
tokio::select!同时等待四个异步来源——- crossterm 的键盘事件流 → 调
handle_key更新App; - 查询结果通道
rx.recv()→ 调app.apply(outcome)把某个解析器的答案写进rows,并顺手把已到达的结果一次性排空(drain),保证一次重绘覆盖所有结果; - Anycast 站点发现通道 → 更新地图上圆点的位置;
- 100ms 的 tick → 驱动 spinner 动画,或在监听模式下到期触发下一轮轮询;
- crossterm 的键盘事件流 → 调
- 任一分支醒来,回到第 1 步,天然实现了"状态一变就重绘";
- 检查
app.should_quit,Esc或Ctrl+C后退出循环并恢复终端。
异步查询的发起在 spawn_round(src/main.rs):为一轮查询里的每个解析器各 spawn 一个 tokio 任务,任务里调用 dns::query(内部就是 hickory-resolver 的一次 lookup),完成后把结果 send 回主循环的 mpsc 通道。主循环因此永远不需要 await 任何网络调用,UI 线程永不阻塞。
还有一个精巧的并发细节——generation 计数器:每次发起新查询、增删解析器都会让 App.generation 自增,迟到的旧结果到达时 apply 会因代次不符直接丢弃(src/app.rs)。这样"上一轮还没回包、用户已经换了域名"的竞态就被一个 u64 优雅解决了。
七、值得抄作业的 4 个架构亮点 📝
- 三层职责单一:
main.rs管事件流、app.rs管状态逻辑(可脱离终端和网络做单元测试)、ui.rs只读状态做绘制。改按键不动渲染,改算法不动布局。 - 通道而非回调传结果:worker 任务通过
mpsc::unbounded_channel把QueryOutcome发回主循环,rx由主循环持有,天然避免了"渲染线程里等网络"的死锁风险。 - 状态先行、渲染随后:
App里连地图变形的动画进度(globe.t())都是状态——渲染只是状态的纯函数,这让"终端宽了自动切地图、窄了变地球"这类响应式行为可以完全由逻辑层决定(src/app.rs)。 - 配置在 raw 模式前校验:
config::load()和域名校验都发生在进入 raw 终端之前(src/main.rs),配置文件写错了,错误信息能正常打印而不是糊在 TUI 里。
八、如何跑起来看看源码效果
如果你手上有 Rust 1.85+ 工具链,可以直接从源码构建(仓库地址:https://gitcode.com/gh_mirrors/dn/dnsglobe ):
git clone https://gitcode.com/gh_mirrors/dn/dnsglobe
cd dnsglobe
cargo run -- example.com # TUI 模式,输入域名后回车开始监听
cargo run -- example.com --once # 纯文本模式,适合脚本,无需 TTY
配合 --ecs 203.0.113.0/24 还能查看特定客户端网络视角下的 GeoDNS 答案,--view map|globe|auto 可强制地图样式。
结语
dnsglobe 用最少的模块数,演示了一个结构教科书级的 Rust TUI:hickory-resolver 负责"问全球",crossterm 负责"听输入",ratatui 负责"画出来",tokio 的 select 循环把它们拧成一根绳。如果你想给自己的项目加一个终端界面,或者想学习"状态机 + 事件流 + 纯函数渲染"这套组合拳,这个不到 4000 行代码的仓库(src/)绝对值得逐文件读完 🌐
