flutter-httpdns-override

1. 实验目标

这个 Flutter host 首版 Lab 不做真实在线 HTTPDNS 联网，而是提供一个真实存在、可跳转、可承载后续扩写的工程入口，帮助读者把下面几件事放进同一个心智模型：

HTTPDNS / 阿里 DNS 初始化放在哪一层
为什么需要预解析与 TTL 缓存
Dio / dart:io HttpClient 接入时，哪些逻辑应收口到 adapter / facade
IP 直连后为什么 Host / SNI / 证书校验不能跟着“变成 IP”
为什么必须保留系统 DNS 回退入口

2. 结构化示意与工程判断

2.1 一张最小调用链图

这张图想表达的不是“组件越多越好”，而是 HTTPDNS 接入天然跨多层：Flutter 页面只应该观察状态，不应该直接拼 IP；解析策略应集中在 facade；真正触发连接计划的，是请求层 adapter。

2.2 生活化类比

可以把 HTTPDNS 理解成“你先问一个更可信的导航台，哪条路当前更稳”，但你到达小区门口后，门牌号、门禁、住户身份校验规则并不会因为你换了路线就失效。

对应到技术上就是：

HTTPDNS 决定“先走哪条路（IP）”
Host 头像“你到门口报的房号”
TLS SNI / 证书校验像“保安核对你要找的住户信息”

如果你只顾着换路线，却把门牌号和身份校验全改坏了，请求照样进不去。

2.3 方案对比矩阵

方案	通俗比喻	底层原理	保证特性	吞吐性能	运行开销	适用场景
纯系统 DNS	直接问小区门口保安	依赖系统 resolver 与本地 DNS	实现简单，但污染/调度不可控	常规	最低	一般业务、无特殊网络治理要求
HTTPDNS + facade + 回退	先问可信导航台，再按门牌与门禁规则进楼	HTTPDNS 解析 + adapter 注入 + Host/SNI/TLS 保持域名	解析更可控，可观测，可回退	中高，取决于后端与连接层	中等	关键 API、弱网、特定运营商问题治理
只会 resolveDomain 的朴素接法	只知道导航给了个经纬度	查出 IP 后直接改 URL，缺少边界治理	易跑通 demo，但安全与稳定性不足	不稳定	表面低，实际排障高	不建议生产直接使用

3. Android / Flutter 实战场景与误配事故

3.1 实战场景

适合先用这个 Lab 建立判断的场景：

Android 端已有 HTTPDNS / 阿里 DNS 接入经验，Flutter 需要复用策略而不是重写一套业务判断
同一组 API 域名在部分运营商网络下解析质量差
想在 Flutter 层先搭出 facade / adapter / 状态展示骨架，再逐步桥接真实插件与原生网络栈

3.2 常见误配与事故注意事项

误把 HTTPDNS 当成“把 URL 换成 IP 就结束”
忘了保留 Host 头与 TLS 域名校验
解析失败后没有系统 DNS 回退，导致 HTTPDNS 自己变成单点
在 UI 页面里直接写解析与拼接逻辑，后续很难统一排障

3.3 排障思路

先看 facade 是否初始化成功。
再看预解析是否产出 TTL 与候选 IP。
再看 adapter 是否记录了“命中 HTTPDNS / 回退系统 DNS”的原因。
最后看业务请求是否把底层错误正确映射到 UI 状态。

4. 实验源码与运行验证

关键源码

源码文件：flutter_httpdns_override_demo_page.dart
路由入口：app_router.dart

关键参数 / 开关

bootstrapEnabled：模拟 HTTPDNS SDK 是否已初始化成功
preferHttpDns：请求是否优先尝试 HTTPDNS 命中结果
simulateTlsMismatch：模拟 IP 直连后 SNI / 证书边界错误
fallbackToSystemDns：模拟失败后是否允许回退原始域名请求

运行方式

bash

cd labs/flutter/host
flutter pub get
flutter run -d macos
# 或切到 android / ios 设备

启动后在首页进入 HTTPDNS / 阿里 DNS 工程化。

预期界面现象

text

1. 点击“初始化 HTTPDNS”后，状态区显示 bootstrap success。
2. 点击“预解析核心域名”后，列表展示 api.example.com 的候选 IP 与 TTL。
3. 点击“模拟 Dio 请求计划”后，日志打印当前命中 HTTPDNS 还是系统 DNS。
4. 打开“模拟 TLS/SNI 失配”后再次执行，请看到回退日志与边界提示。

5. 对应知识库文档

理论主文档：09. HTTPDNS / 阿里 DNS 移动端工程化：Android / Flutter 主线、Host/SNI/TLS 边界与回退策略

flutter-httpdns-override ​

1. 实验目标 ​

2. 结构化示意与工程判断 ​

2.1 一张最小调用链图 ​

2.2 生活化类比 ​

2.3 方案对比矩阵 ​

3. Android / Flutter 实战场景与误配事故 ​

3.1 实战场景 ​

3.2 常见误配与事故注意事项 ​

3.3 排障思路 ​

4. 实验源码与运行验证 ​

关键源码 ​

关键参数 / 开关 ​

运行方式 ​

预期界面现象 ​

5. 对应知识库文档 ​