`hutool.core.net`¶

网络工具类，提供端口检测、IP地址处理、子网掩码转换等功能

Module Contents¶

Classes¶

`MaskBit`	掩码位和掩码之间的对应关系
`Ipv4Util`	IPV4地址工具类
`NetUtil`	网络工具类，提供端口检测、IP获取、地址转换等功能

Data¶

__all__

API¶

hutool.core.net.__all__ = ('Ipv4Util', 'MaskBit', 'NetUtil')¶

class hutool.core.net.MaskBit¶

掩码位和掩码之间的对应关系

MASK_BIT_MAP: Final[dict] = None¶

_MASK_TO_BIT: Final[dict] = None¶

static get(mask_bit: int) → str¶

根据掩码位获取掩码

参数:: mask_bit – 掩码位，范围1-32
返回:: 掩码字符串，如”255.255.255.0”
抛出:: KeyError – 掩码位不在合法范围内

static get_mask_bit(mask: str) → Optional[int]¶

根据掩码获取掩码位

参数:: mask – 掩码的点分十进制表示，如”255.255.255.0”
返回:: 掩码位，如24；如果掩码不合法则返回None

class hutool.core.net.Ipv4Util¶

IPV4地址工具类

LOCAL_IP: Final[str] = '127.0.0.1'¶

IP_SPLIT_MARK: Final[str] = '-'¶

IP_MASK_SPLIT_MARK: Final[str] = '/'¶

IP_MASK_MAX: Final[int] = 32¶

static ipv4_to_long(ip: str) → int¶

IPv4 地址转 long 值。

参数:: ip – IPv4 地址，如 "192.168.1.1"
返回:: long 值
抛出:: ValueError – IP 地址格式非法

static long_to_ipv4(long_ip: int) → str¶

long 值转 IPv4 地址。

参数:: long_ip – long 值
返回:: IPv4 地址字符串
抛出:: ValueError – 数值不在合法范围内

static get_begin_ip_str(cidr: str) → str¶

获取 CIDR 表示的网段起始 IP 地址。

参数:: cidr – CIDR 格式，如 "192.168.1.0/24"
返回:: 起始 IP 地址字符串

static get_begin_ip_long(cidr: str) → int¶

获取 CIDR 表示的网段起始 IP 的 long 值。

参数:: cidr – CIDR 格式
返回:: 起始 IP 的 long 值

static get_end_ip_str(cidr: str) → str¶

获取 CIDR 表示的网段结束 IP 地址。

参数:: cidr – CIDR 格式，如 "192.168.1.0/24"
返回:: 结束 IP 地址字符串

static get_end_ip_long(cidr: str) → int¶

获取 CIDR 表示的网段结束 IP 的 long 值。

参数:: cidr – CIDR 格式
返回:: 结束 IP 的 long 值

static count_by_mask_bit(mask_bit: int) → int¶

根据掩码位数计算 IP 数量。

参数:: mask_bit – 掩码位数（0-32）
返回:: IP 数量

static get_mask_by_mask_bit(mask_bit: int) → str¶

根据掩码位数获取子网掩码。

参数:: mask_bit – 掩码位数（0-32）
返回:: 子网掩码字符串

static get_mask_by_ip_range(begin_ip: str, end_ip: str) → str¶

根据 IP 范围获取子网掩码。

参数:

begin_ip – 起始 IP
end_ip – 结束 IP

返回:

子网掩码字符串

static count_by_ip_range(begin_ip: str, end_ip: str) → int¶

计算两个 IP 之间的 IP 数量。

参数:

begin_ip – 起始 IP
end_ip – 结束 IP

返回:

IP 数量

static is_mask_valid(mask: str) → bool¶

检查子网掩码是否有效。

有效掩码的二进制表示为连续的 1 后跟连续的 0。

参数:: mask – 子网掩码字符串
返回:: 是否有效

static is_mask_bit_valid(mask_bit: int) → bool¶

检查掩码位数是否有效。

参数:: mask_bit – 掩码位数
返回:: 是否有效（0-32）

static is_inner_ip(ip: str) → bool¶

判断是否为内网 IP。

内网 IP 范围： - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - 127.0.0.0/8（本地回环）

参数:: ip – IPv4 地址
返回:: 是否为内网 IP

static matches(ip: str, pattern: str) → bool¶

通配符 IP 匹配。

支持 * 通配符，如 "192.168.1.*"。

参数:

ip – IPv4 地址
pattern – 通配符模式

返回:

是否匹配

static list(ip_range: str) → list¶

列出 CIDR 网段中的所有 IP 地址（不含网络和广播地址）。

参数:: ip_range – CIDR 格式，如 "192.168.1.0/30"
返回:: IP 地址列表

static format_ip_block(ip: str, mask: str) → str¶

格式化IP段

参数:

ip – IP地址
mask – 掩码

返回:

返回xxx.xxx.xxx.xxx/mask的格式

static get_mask_bit_by_mask(mask: str) → int¶

根据子网掩码转换为掩码位

参数:: mask – 掩码的点分十进制表示，例如”255.255.255.0”
返回:: 掩码位，例如24
抛出:: ValueError – 子网掩码非法

static get_mask_bit(mask: str) → Optional[int]¶

获取子网掩码的位数。

参数:: mask – 子网掩码字符串
返回:: 掩码位数，无效掩码返回 None

static _mask_bit_to_long(mask_bit: int) → int¶: 掩码位数转 long 值。

class hutool.core.net.NetUtil¶

网络工具类，提供端口检测、IP获取、地址转换等功能

LOCAL_IP: Final[str] = None¶

PORT_RANGE_MIN: Final[int] = 1024¶

PORT_RANGE_MAX: Final[int] = 65535¶

static is_usable_local_port(port: int) → bool¶

检测本地端口可用性

参数:: port – 被检测的端口
返回:: 是否可用

static is_valid_port(port: int) → bool¶

是否为有效的端口，此方法并不检查端口是否被占用

参数:: port – 端口号
返回:: 是否有效

static get_usable_local_port(min_port: int = PORT_RANGE_MIN, max_port: int = PORT_RANGE_MAX) → int¶

查找指定范围内的可用端口

此方法只检测给定范围内的随机一个端口，最多检测max_port-min_port次。

参数:

min_port – 端口最小值（包含）
max_port – 端口最大值（包含）

返回:

可用的端口

抛出:

RuntimeError – 在指定范围内未找到可用端口

static get_local_ip() → str¶

获取本机IP地址，通过UDP连接外部地址获取本机对外IP

返回:: 本机IP地址，获取失败时返回127.0.0.1

static get_localhost() → str¶

获取本机主机名

返回:: 主机名

static get_host_name() → str¶

获取本机主机名（get_localhost 别名，hutoolpy 兼容）。

返回:: 主机名字符串

static get_host_address() → str¶

获取本机 IP 地址。

通过 UDP socket 探测获取可达的本机 IP，失败时返回 "127.0.0.1"。

返回:: 本机 IP 地址字符串

static get_mac_address() → str¶

获取本机MAC地址

返回:: MAC地址字符串，格式为xx:xx:xx:xx:xx:xx

static is_inner(ip: str) → bool¶

判断是否为内网IP地址

内网IP范围： - 10.0.0.0 ~ 10.255.255.255（A类私有地址） - 172.16.0.0 ~ 172.31.255.255（B类私有地址） - 192.168.0.0 ~ 192.168.255.255（C类私有地址） - 127.0.0.0 ~ 127.255.255.255（本地回环地址）

参数:: ip – IP地址字符串
返回:: 是否为内网IP

static ipv4_to_long(ip: str) → int¶

将IPv4地址转换为long整型数值

参数:: ip – IPv4地址字符串，如”192.168.1.1”
返回:: 对应的long整型值
抛出:: ValueError – IP地址格式非法

static long_to_ipv4(long_ip: int) → str¶

将long整型数值转换为IPv4地址

参数:: long_ip – long整型值
返回:: IPv4地址字符串
抛出:: ValueError – 数值不在合法范围内

static is_open(host: str, port: int, timeout: int = 2000) → bool¶

检测远程主机端口是否可连接

参数:

host – 主机地址
port – 端口号
timeout – 超时时间，单位毫秒，默认2000ms

返回:

端口是否可连接

static is_inner_ip(ip: str) → bool¶

判断是否为内网 IP（与 is_inner 相同）。

参数:: ip – IP 地址字符串
返回:: 是否为内网 IP

static is_in_range(ip: str, cidr: str) → bool¶

判断 IP 是否在 CIDR 范围内。

参数:

ip – IP 地址字符串
cidr – CIDR 格式字符串，如 “192.168.1.0/24”

返回:

是否在范围内

static hide_ip_part(ip: str) → str¶

遮蔽 IP 地址，将最后一段替换为 *。

参数:: ip – IP 地址
返回:: 遮蔽后的 IP，如 “192.168.1.*”

static local_ipv4s() → list¶

获取本机所有 IPv4 地址列表。

返回:: IPv4 地址列表

static get_local_host_name() → str¶

获取本机主机名（与 get_localhost 相同）。

返回:: 主机名

static get_ip_by_host(hostname: str) → str¶

解析主机名获取 IP 地址。

参数:: hostname – 主机名
返回:: IP 地址，解析失败返回空字符串

static to_absolute_url(base: str, relative: str) → str¶

将相对 URL 补全为绝对 URL。

参数:

base – 基础 URL
relative – 相对 URL

返回:

绝对 URL

static ipv6_to_big_integer(ipv6: str) → int¶

将 IPv6 地址转为大整数。

参数:: ipv6 – IPv6 地址字符串
返回:: 对应的大整数
抛出:: ValueError – IPv6 地址格式非法

static big_integer_to_ipv6(n: int) → str¶

将大整数转为 IPv6 地址。

参数:: n – 大整数
返回:: IPv6 地址字符串
抛出:: ValueError – 数值不在合法范围内

static get_usable_local_ports(count: int, min_port: int = 1024, max_port: int = 65535) → List[int]¶

批量获取可用的本地端口。

参数:

count – 需要的端口数量
min_port – 最小端口
max_port – 最大端口

返回:

可用端口列表

抛出:

RuntimeError – 无法获取足够数量的可用端口

static hide_ip_part_from_long(long_ip: int) → str¶

从 long 型 IP 遐藏最后一段。

参数:: long_ip – long 型 IP 值
返回:: 遮蔽后的 IP 字符串

static local_ipv6s() → List[str]¶

获取本机所有 IPv6 地址列表。

返回:: IPv6 地址列表

static to_ip_list(ip_range: str) → List[str]¶

将 IP 范围字符串转为 IP 列表。

支持 CIDR 格式（如 192.168.1.0/30）和短横线范围（如 192.168.1.1-192.168.1.5）。

参数:: ip_range – IP 范围字符串
返回:: IP 地址列表

static local_ips() → List[str]¶

获取所有本地 IP 地址（IPv4 + IPv6）。

返回:: IP 地址列表

static get_localhost_str() → str¶

获取 localhost 字符串表示。

返回:: “localhost” 字符串

static idn_to_ascii(domain: str) → str¶

将国际化域名 (IDN) 转为 ASCII 形式。

参数:: domain – 域名
返回:: ASCII 编码的域名

static is_unknown(ip: str) → bool¶

判断是否为未知 IP 地址。

未知 IP 包括 None、空字符串和 “unknown”（不区分大小写）。

参数:: ip – IP 地址
返回:: 是否为未知 IP

static ping(host: str, timeout: int = 3000) → bool¶

Ping 测试主机是否可达。

通过尝试建立 TCP 连接到端口 80 来检测。

参数:

host – 主机地址
timeout – 超时时间，单位毫秒

返回:

是否可达

static parse_cookies(cookie_str: str) → dict¶

解析 Cookie 字符串为字典。

参数:: cookie_str – Cookie 字符串，如 "name=value; name2=value2"
返回:: Cookie 字典

static get_dns_info(hostname: str) → dict¶

获取主机名的 DNS 信息。

参数:: hostname – 主机名
返回:: DNS 信息字典，包含 ip、aliases、family 等

static net_cat(host: str, port: int, data: str, timeout: int = 5000) → str¶

网络连接发送数据并接收响应（类似 nc/netcat）。

参数:

host – 主机地址
port – 端口号
data – 要发送的数据
timeout – 超时时间，单位毫秒

返回:

接收到的响应数据

抛出:

ConnectionRefusedError – 连接被拒绝
socket.timeout – 连接超时

hutool.core.net¶

Module Contents¶

Classes¶

Data¶

API¶

`hutool.core.net`¶