feat: add explicit IPv4/IPv6 selection to NAT diagnostics

Author: halifox

README.md

@@ -26,12 +26,13 @@
 
 这个项目是一个用于 **NAT 行为检测与 STUN 诊断** 的 Flutter 应用，当前界面采用 Fluent UI 风格，适合在桌面环境下作为网络测试小工具使用。它可以帮助你观察当前网络是否经过 NAT、NAT 的映射与过滤策略、服务端能力、映射存活时间估算，以及一些更偏工程诊断用途的扩展指标。
 
-相较于只返回一个“能不能通”的简单测试工具，这个项目更偏向“**把网络行为拆开来看**”。你既可以直接选择公开 STUN 服务快速执行测试，也可以手动调整本地绑定地址、端口、超时、重传、分片填充等参数，观察不同网络环境下的响应差异。
+相较于只返回一个“能不能通”的简单测试工具，这个项目更偏向“**把网络行为拆开来看**”。你既可以直接选择公开 STUN 服务快速执行测试，也可以手动调整本地绑定地址、端口、地址族、超时、重传、分片填充等参数，观察不同网络环境下的响应差异。
 
 ## 功能亮点
 
 - 支持填写或选择目标 STUN 服务 URI，快速发起 NAT 探测。
 - 支持自定义本地绑定 IP 与端口，便于多网卡或特定出口场景验证。
+- 支持显式选择 `自动 / IPv4 / IPv6` 地址族，便于固定目标解析结果与 socket 地址族。
 - 支持检测网络可达性、是否存在 NAT、公网映射地址与服务端端点。
 - 支持分析 NAT 映射行为、过滤行为以及传统 NAT 类型归类。
 - 支持估算 Binding Lifetime，辅助判断映射在空闲状态下可维持多久。

lib/pages/nat_diagnostics_page.dart

@@ -1,14 +1,31 @@
+import 'dart:io';
+
 import 'package:fluent_ui/fluent_ui.dart';
 import 'package:flutter_hooks/flutter_hooks.dart';
 import 'package:nat_tester/value_formatters.dart';
 import 'package:nat_tester/widgets/editable_combo_action_tile.dart';
 import 'package:nat_tester/widgets/expander_section.dart';
 import 'package:nat_tester/widgets/number_field_tile.dart';
 import 'package:nat_tester/widgets/read_only_value_tile.dart';
+import 'package:nat_tester/widgets/select_field_tile.dart';
 import 'package:nat_tester/widgets/switch_tile.dart';
 import 'package:nat_tester/widgets/text_field_tile.dart';
 import 'package:stun/stun.dart';
 
+enum _AddressFamilyOption {
+  auto(null, '自动 (Auto)'),
+  ipv4(InternetAddressType.IPv4, 'IPv4'),
+  ipv6(InternetAddressType.IPv6, 'IPv6');
+
+  const _AddressFamilyOption(this.type, this.label);
+
+  final InternetAddressType? type;
+  final String label;
+
+  @override
+  String toString() => label;
+}
+
 class NatDiagnosticsPage extends HookWidget {
   static const int _maxLogEntries = 200;
 
@@ -18,6 +35,7 @@ class NatDiagnosticsPage extends HookWidget {
   Widget build(BuildContext context) {
     final serverUri = useState<String>('stun:stun.hot-chilli.net:3478');
     final localIp = useState<String>('');
+    final addressFamily = useState<_AddressFamilyOption>(_AddressFamilyOption.auto);
     final localPort = useState<int>(0);
     final initialRtoMs = useState<int>(200);
     final maxRetransmissions = useState<int>(2);
@@ -102,6 +120,7 @@ class NatDiagnosticsPage extends HookWidget {
                                 localIp: localIp.value.isEmpty
                                     ? null
                                     : localIp.value,
+                                addressType: addressFamily.value.type,
                                 localPort: localPort.value,
                                 initialRto: Duration(
                                   milliseconds: initialRtoMs.value,
@@ -161,6 +180,17 @@ class NatDiagnosticsPage extends HookWidget {
                           localIp.value = value;
                         },
                       ),
+                      SelectFieldTile<_AddressFamilyOption>(
+                        icon: FluentIcons.internet_sharing,
+                        title: '地址族选择 (Address Family)',
+                        description:
+                            '自动模式会跟随目标解析结果；选择 IPv4 或 IPv6 后，只使用对应地址族的 STUN 端点与 UDP socket。',
+                        options: _AddressFamilyOption.values,
+                        value: addressFamily.value,
+                        onChanged: (_AddressFamilyOption value) {
+                          addressFamily.value = value;
+                        },
+                      ),
                       NumberFieldTile(
                         icon: FluentIcons.plug_connected,
                         title: '本地绑定端口 (Local Bind Port)',
@@ -465,3 +495,4 @@ String _formatLogEntry(StunLogEvent event) {
   final String level = event.level.name.toUpperCase();
   return '[$timestamp] [$level] ${event.format()}';
 }
+

pubspec.lock

@@ -641,11 +641,11 @@ packages:
     dependency: "direct main"
     description:
       path: "."
-      ref: "^3.0.1"
-      resolved-ref: a6bc04c674c0fb4c9aeb3e439bea6599891793d1
+      ref: "3.0.2"
+      resolved-ref: "6f2a54983151ea97f743445a96a08d460cbc90b1"
       url: "https://github.com/halifox/dart_stun"
     source: git
-    version: "3.0.1"
+    version: "3.0.2"
   term_glyph:
     dependency: transitive
     description:

pubspec.yaml

@@ -42,7 +42,7 @@ dependencies:
   stun:
     git:
       url: https://github.com/halifox/dart_stun
-      ref: ^3.0.1
+      ref: 3.0.2
 dev_dependencies:
   flutter_test:
     sdk: flutter