网络工具 - NetUtil / Ipv4Util¶

由来¶

网络编程中经常需要判断 IP 地址、端口、内网/外网等。NetUtil 提供了常用的网络工具方法。

NetUtil¶

IP 地址¶

from hutool import NetUtil

NetUtil.get_local_ip()  # "192.168.1.100"（本机 IP）
NetUtil.get_localhost()  # "127.0.0.1"
NetUtil.get_mac_address()  # "AA:BB:CC:DD:EE:FF"

# 判断内网 IP
NetUtil.is_inner("192.168.1.1")  # True
NetUtil.is_inner("10.0.0.1")  # True
NetUtil.is_inner("8.8.8.8")  # False

端口¶

NetUtil.is_valid_port(8080)  # True
NetUtil.is_valid_port(0)  # False
NetUtil.is_usable_port(8080)  # True（端口是否可用）
NetUtil.get_usable_port()  # 获取一个可用端口

IP 转换¶

# IPv4 与长整型互转
NetUtil.ipv4_to_long("192.168.1.1")  # 3232235777
NetUtil.long_to_ipv4(3232235777)  # "192.168.1.1"

连通性¶

NetUtil.ping("baidu.com")  # True/False
NetUtil.is_open("baidu.com", 80)  # True（端口是否开放）

新增方法¶

# 判断内网 IP（别名）
NetUtil.is_inner_ip("192.168.1.1")  # True
NetUtil.is_inner_ip("8.8.8.8")  # False

# IP 是否在 CIDR 范围内
NetUtil.is_in_range("192.168.1.100", "192.168.1.0/24")  # True
NetUtil.is_in_range("10.0.0.1", "192.168.1.0/24")  # False

# 遮蔽 IP 地址
NetUtil.hide_ip_part("192.168.1.100")  # "192.168.1.*"

# 获取本机 IPv4 列表
NetUtil.local_ipv4s()  # ["192.168.1.100", ...]

# 获取本机主机名
NetUtil.get_local_host_name()  # "my-computer"

# 解析主机名
NetUtil.get_ip_by_host("localhost")  # "127.0.0.1"

# 补全相对 URL
NetUtil.to_absolute_url("http://example.com/a/b", "../c")
# "http://example.com/c"

Ipv4Util¶

IPv4 地址的高级操作：

from hutool import Ipv4Util, MaskBit

# 掩码操作
MaskBit.get_mask(24)  # "255.255.255.0"
MaskBit.get_mask_bit("255.255.255.0")  # 24

主机信息¶

from hutool import NetUtil

# 获取本机主机名（与 get_localhost 相同）
NetUtil.get_host_name()  # "DESKTOP-ABC123"

# 获取本机 IP 地址（通过 UDP 探测）
NetUtil.get_host_address()  # "192.168.1.100"

AsyncNetUtil（异步网络工具）¶

NetUtil 的异步版本，基于标准库 asyncio（asyncio.open_connection 做真正的非阻塞连接， loop.run_in_executor 包裹阻塞式 DNS 解析），无需任何第三方依赖。方法名与同步版一致，所有网络 I/O 方法均为协程，调用时需 await：

from hutool import AsyncNetUtil

# 检测端口是否可连接
if await AsyncNetUtil.is_open("example.com", 80):
    print("端口可达")

# Ping 测试（TCP 80 端口）
reachable = await AsyncNetUtil.ping("example.com")

# 类似 nc/netcat 发送并接收
resp = await AsyncNetUtil.net_cat("example.com", 80, "GET / HTTP/1.0\r\n\r\n")

# 解析主机名 / DNS 信息 / 本机 IP
ip = await AsyncNetUtil.get_ip_by_host("example.com")
info = await AsyncNetUtil.get_dns_info("example.com")
local = await AsyncNetUtil.get_local_ip()

.. note::

``AsyncNetUtil`` 已与 ``NetUtil`` **完全镜像**：除网络 I/O 方法外，所有纯计算方法（``ipv4_to_long`` /
``hide_ip_part`` / ``to_ip_list`` / ``idn_to_ascii`` / ``to_absolute_url`` 等）也提供同名 ``async`` 薄壳。
引入 ``AsyncNetUtil`` 后通常可不再使用 ``NetUtil``。