net包阅读摘记

简介

在 net 包中有很多的结构体，各种函数各种方法。我自己决定总体上看一遍，然后做个导图。

复制粘贴来源：https://studygolang.com/stati…

常量

const (
    IPv4len = 4
    IPv6len = 16
)

全局变量

常用的 IPv4 地址。

var (IPv4bcast     = IPv4(255, 255, 255, 255) // 广播地址
    IPv4allsys    = IPv4(224, 0, 0, 1)       // 所有主机和路由器
    IPv4allrouter = IPv4(224, 0, 0, 2)       // 所有路由器
    IPv4zero      = IPv4(0, 0, 0, 0)         // 本地地址，只能作为源地址（曾用作广播地址）)

很多 OpError 类型的错误会包含本错误。

var (ErrWriteToConnected = errors.New("use of WriteTo with pre-connected connection")
)

Error 接口

内嵌了 内置的 error，这意味这我们在处理 net 包的错误的时候，要记住 go net 包已经为我们封装这么一个错误接口。

type Error interface {
    error            // =>Error（）string
    Timeout() bool   // 错误是否为超时？Temporary() bool // 错误是否是临时的？}

各种 Error 接口的实现类型

通过其命名可直观看出分别是哪类错误

• UnknownNetworkError

type UnknownNetworkError string

• InvalidAddrError

type InvalidAddrError string

• DNSConfigError：DNSConfigError 代表读取主机 DNS 配置时出现的错误。

type DNSConfigError struct {Err error}

疑问：为什么这个结构体值包含一个内置错误接口类型，这样包装有何目的？？

• DNSError

type DNSError struct {
    Err       string // 错误的描述
    Name      string // 查询的名称
    Server    string // 使用的服务器
    IsTimeout bool
}

• AddrError

type AddrError struct {
    Err  string
    Addr string
}

• OpError(常用)

OpError 是经常被 net 包的函数返回的错误类型。它描述了该错误的操作、网络类型和网络地址。

type OpError struct {
    // Op 是出现错误的操作，如 "read" 或 "write"
    Op  string
    // Net 是错误所在的网络类型，如 "tcp" 或 "udp6"
    Net string
    // Addr 是出现错误的网络地址
    Addr Addr
    // Err 是操作中出现的错误
    Err error
}

HardwareAddr 类型

type HardwareAddr []byte

很明显，用来描述 mac 地址的。

• 函数 ParseMAC：解析硬件地址

func ParseMAC(s string) (hw HardwareAddr, err error)

• 方法 String

func (a HardwareAddr) String() string

Flags 类型: 接口的属性

type Flags uint
const (
    FlagUp           Flags = 1 << iota // 接口在活动状态
    FlagBroadcast                      // 接口支持广播
    FlagLoopback                       // 接口是环回的
    FlagPointToPoint                   // 接口是点对点的
    FlagMulticast                      // 接口支持组播
)

• String 方法

func (f Flags) String() string

Interface 类型：描述网卡

描述的内容即是我们通过 ifconfig 输出的内容

type Interface struct {
    Index        int          // 索引，>= 1 的整数
    MTU          int          // 最大传输单元
    Name         string       // 接口名，例如 "en0"、"lo0"、"eth0.100"
    HardwareAddr HardwareAddr // 硬件地址，IEEE MAC-48、EUI-48 或 EUI-64 格式
    Flags        Flags        // 接口的属性，例如 FlagUp、FlagLoopback、FlagMulticast
}

• InterfaceByIndex 函数：返回指定索引的网络接口

func InterfaceByIndex(index int) (*Interface, error)

• InterfaceByName 函数：返回指定名字的网络接口。

func InterfaceByName(name string) (*Interface, error)

• Interfaces 函数：返回该系统的网络接口列表

func Interfaces() ([]Interface, error)

• InterfaceAddrs 函数：返回该系统的网络接口的地址列表

func InterfaceAddrs() ([]Addr, error)

• Addrs 方法：返回网络接口 ifi 的一或多个接口地址

func (ifi *Interface) Addrs() ([]Addr, error)

• MulticastAddrs 方法：返回网络接口 ifi 加入的多播组地址。

func (ifi *Interface) MulticastAddrs() ([]Addr, error）

Example：

func main() {infslice, _ := net.Interfaces()
    w := new(tabwriter.Writer).Init(os.Stdout, 8, 8, 3, ' ', 0)
    fmt.Fprintln(w, "Index\tName\tMac\tMTU\tFlags\tAddrs")
    for _, inf := range infslice {addr, _ := inf.Addrs()
        fmt.Fprintf(w, "%v\t%v\t%v\t%v\t%v\t%v\n", inf.Index, inf.Name, inf.HardwareAddr, inf.MTU, inf.Flags, addr)
    }
    w.Flush()}

IP 类型：描述 ipv4 或 ipv6 地址

注意: 开发中判断 IPV4 还是 IPV6 不能根据其切片长度

type IP []byte

• IPv4 函数：返回包含一个 IPv4 地址 a.b.c.d 的 IP 地址（16 字节格式）。`
• ParseIP 函数：将 s 解析为 IP 地址，并返回该地址。如果 s 不是合法的 IP 地址文本表示，ParseIP 会返回 nil。
• DefaultMask 方法：返回 IP 地址 ip 的默认子网掩码。只有 IPv4 有默认子网掩码；如果 ip 不是合法的 IPv4 地址，会返回 nil。
• Equal 方法：如果 ip 和 x 代表同一个 IP 地址，Equal 会返回真。代表同一地址的 IPv4 地址和 IPv6 地址也被认为是相等的。
• Mask 方法：返回网络号

func IPv4(a, b, c, d byte) IP
func ParseIP(s string) IP
func (ip IP) DefaultMask() IPMask
func (ip IP) Equal(x IP) bool
func (ip IP) Mask(mask IPMask) IP

IPMask 类型：描述 IPv4 地址掩码

type IPMask []byte

• IPv4Mask 函数：返回一个 4 字节格式的 IPv4 掩码 a.b.c.d。
• CIDRMask 函数：返回一个 IPMask 类型值，该返回值总共有 bits 个字位，其中前 ones 个字位都是 1，其余字位都是 0。
• Size 方法：返回 m 的前导的 1 字位数和总字位数。如果 m 不是规范的子网掩码（字位：/^1+0+$/），将返会(0, 0)。

func IPv4Mask(a, b, c, d byte) IPMask
func CIDRMask(ones, bits int) IPMask
func (m IPMask) Size() (ones, bits int)

IPNet 类型：表示一个 IP 网络（IP+MASK）

type IPNet struct {
    IP   IP     // 网络地址
    Mask IPMask // 子网掩码
}

• ParseCIDR 函数：将 s 作为一个 CIDR（无类型域间路由）的 IP 地址和掩码字符串，如 ”192.168.100.1/24″ 或 ”2001:DB8::/48″，解析并返回 IP 地址和 IP 网络。对于 ”192.168.100.1/24″ 会返回 IP 地址 192.168.100.1 和 IP 网络 192.168.0.0/16。
• Contains 函数：报告该网络是否包含地址 ip
• Network 方法：返回网络类型名：”ip+net”。其实说白了就无论啥都返回这么一个字符串？

func ParseCIDR(s string) (IP, *IPNet, error)
func (n *IPNet) Contains(ip IP) bool
func (n *IPNet) Network() string

Addr 接口：代表一个网络中的终端地址

type Addr interface {Network() string // 网络名，eg:”tcp“String() string  // 字符串格式的地址，eg：”127.0.0.1:10999“}

Conn 接口：代表通用的 面向流 的网络连接

type Conn interface {
    // Read 从连接中读取数据
    // Read 方法可能会在超过某个固定时间限制后超时返回错误，该错误的 Timeout()方法返回真
    Read(b []byte) (n int, err error)
    // Write 从连接中写入数据
    // Write 方法可能会在超过某个固定时间限制后超时返回错误，该错误的 Timeout()方法返回真
    Write(b []byte) (n int, err error)
    // Close 方法关闭该连接
    // 并会导致任何阻塞中的 Read 或 Write 方法不再阻塞并返回错误
    Close() error
    // 返回本地网络地址
    LocalAddr() Addr
    // 返回远端网络地址
    RemoteAddr() Addr
    // 设定该连接的读写 deadline，等价于同时调用 SetReadDeadline 和 SetWriteDeadline
    // deadline 是一个绝对时间，超过该时间后 I / O 操作就会直接因超时失败返回而不会阻塞
    // deadline 对之后的所有 I / O 操作都起效，而不仅仅是下一次的读或写操作
    // 参数 t 为零值表示不设置期限
    SetDeadline(t time.Time) error
    // 设定该连接的读操作 deadline，参数 t 为零值表示不设置期限
    SetReadDeadline(t time.Time) error
    // 设定该连接的写操作 deadline，参数 t 为零值表示不设置期限
    // 即使写入超时，返回值 n 也可能 >0，说明成功写入了部分数据
    SetWriteDeadline(t time.Time) error
}

• Dial 函数：在网络 network 上连接地址 address，并返回一个 Conn 接口
• DialTimeout 函数：类似 Dial 但采用了超时。timeout 参数如果必要可包含名称解析。
• Pipe 函数：创建一个内存中的同步、全双工网络连接。连接的两端都实现了 Conn 接口。一端的读取对应另一端的写入，直接将数据在两端之间作拷贝；没有内部缓冲。

// network:"tcp"、"tcp4"、"tcp6"、"udp"、"udp4"、"udp6"、"ip"、"ip4"、"ip6"、"unix"、"unixgram"、"unixpacket"
// address 支持域名，要提供端口
func Dial(network, address string) (Conn, error)
func DialTimeout(network, address string, timeout time.Duration) (Conn, error)
func Pipe() (Conn, Conn)

PacketConn 接口：代表通用的 面向数据包 的网络连接。

网络层

type PacketConn interface {
    // ReadFrom 方法从连接读取一个数据包，并将有效信息写入 b
    // ReadFrom 方法可能会在超过某个固定时间限制后超时返回错误，该错误的 Timeout()方法返回真
    // 返回写入的字节数和该数据包的来源地址
    ReadFrom(b []byte) (n int, addr Addr, err error)
    // WriteTo 方法将有效数据 b 写入一个数据包发送给 addr
    // WriteTo 方法可能会在超过某个固定时间限制后超时返回错误，该错误的 Timeout()方法返回真
    // 在面向数据包的连接中，写入超时非常罕见
    WriteTo(b []byte, addr Addr) (n int, err error)
    // Close 方法关闭该连接
    // 会导致任何阻塞中的 ReadFrom 或 WriteTo 方法不再阻塞并返回错误
    Close() error
    // 返回本地网络地址
    LocalAddr() Addr
    // 设定该连接的读写 deadline
    SetDeadline(t time.Time) error
    // 设定该连接的读操作 deadline，参数 t 为零值表示不设置期限
    // 如果时间到达 deadline，读操作就会直接因超时失败返回而不会阻塞
    SetReadDeadline(t time.Time) error
    // 设定该连接的写操作 deadline，参数 t 为零值表示不设置期限
    // 如果时间到达 deadline，写操作就会直接因超时失败返回而不会阻塞
    // 即使写入超时，返回值 n 也可能 >0，说明成功写入了部分数据
    SetWriteDeadline(t time.Time) error
}

• ListenPacket 函数：监听本地网络地址 laddr。网络类型 net 必须是面向数据包的网络类型

// net:"ip"、"ip4"、"ip6"、"udp"、"udp4"、"udp6"、或 "unixgram"
// laddr 的格式参见 Dial 函数。func ListenPacket(net, laddr string) (PacketConn, error)

IPConn 类型：代表 IP 网络连接，实现了 Conn 和 PacketConn 接口

type IPConn struct {// 内含隐藏或非导出字段}

TCPConn 类型：代表一个 TCP 网络连接，实现了 Conn 接口。

type TCPConn struct {// 内含隐藏或非导出字段}

UDPConn 类型：UDPConn 代表一个 UDP 网络连接，实现了 Conn 和 PacketConn 接口。

type UDPConn struct {// 内含隐藏或非导出字段}

UnixConn 类型：代表 Unix 域 socket 连接，实现了 Conn 和 PacketConn 接口

type UnixConn struct {// 内含隐藏或非导出字段}

Dialer 类型：包含与某个地址建立连接时的参数

type Dialer struct {
    // Timeout 是 dial 操作等待连接建立的最大时长，默认值代表没有超时。// 如果 Deadline 字段也被设置了，dial 操作也可能更早失败。// 不管有没有设置超时，操作系统都可能强制执行它的超时设置。// 例如，TCP（系统）超时一般在 3 分钟左右。Timeout time.Duration
    // Deadline 是一个具体的时间点期限，超过该期限后，dial 操作就会失败。// 如果 Timeout 字段也被设置了，dial 操作也可能更早失败。// 零值表示没有期限，即遵守操作系统的超时设置。Deadline time.Time
    // LocalAddr 是 dial 一个地址时使用的本地地址。// 该地址必须是与 dial 的网络相容的类型。// 如果为 nil，将会自动选择一个本地地址。LocalAddr Addr
    // DualStack 允许单次 dial 操作在网络类型为 "tcp"，// 且目的地是一个主机名的 DNS 记录具有多个地址时，// 尝试建立多个 IPv4 和 IPv6 连接，并返回第一个建立的连接。DualStack bool
    // KeepAlive 指定一个活动的网络连接的生命周期；如果为 0，会禁止 keep-alive。// 不支持 keep-alive 的网络连接会忽略本字段。KeepAlive time.Duration
}

每一个字段的零值都等价于没有该字段。因此调用 Dialer 零值的 Dial 方法等价于调用 Dial 函数。

• Dial 方法：指定的网络上连接指定的地址。比 Dial 函数多了许多控制信息。

func (d *Dialer) Dial(network, address string) (Conn, error)

Listener 接口：用于 面向流 的网络协议的公用的网络监听器接口。

type Listener interface {
    // Addr 返回该接口的网络地址
    Addr() Addr
    // Accept 等待并返回下一个连接到该接口的连接
    Accept() (c Conn, err error)
    // Close 关闭该接口，并使任何阻塞的 Accept 操作都会不再阻塞并返回错误。Close() error}

• Listen 函数：返回在一个本地网络地址 laddr 上监听的 Listener。网络类型参数 net 必须是面向流的网络

func Listen(net, laddr string) (Listener, error)

TCPListener 类型

TCPListener 代表一个 TCP 网络的监听者。使用者应尽量使用 Listener 接口而不是假设（网络连接为）TCP

type TCPListener struct {// 内含隐藏或非导出字段}

UnixListener 类型

UnixListener 代表一个 Unix 域 scoket 的监听者。使用者应尽量使用 Listener 接口而不是假设（网络连接为）Unix 域 scoket。

type UnixListener struct {// 内含隐藏或非导出字段}

IPAddr

type IPAddr struct {
    IP   IP
    Zone string // IPv6 范围寻址域
}

• ResolveIPAddr 函数：将 addr 作为一个格式为 ”host” 或 ”ipv6-host%zone” 的 IP 地址来解析。函数会在参数 net 指定的网络类型上解析，net 必须是 ”ip”、”ip4″ 或 ”ip6″。
• Network 方法：返回地址的网络类型：”ip”。

func ResolveIPAddr(net, addr string) (*IPAddr, error)
func (a *IPAddr) Network() string

TCPAddr 类型：代表一个 TCP 终端地址

type TCPAddr struct {
    IP   IP
    Port int
    Zone string // IPv6 范围寻址域
}

• ResolveTCPAddr 函数：将 addr 作为 TCP 地址解析并返回。参数 addr 格式为 ”host:port” 或 ”[ipv6-host%zone]:port”，解析得到网络名和端口名；net 必须是 ”tcp”、”tcp4″ 或 ”tcp6″。
• Network 方法：“tcp”

UDPAddr 类型：代表一个 UDP 终端地址

type UDPAddr struct {
    IP   IP
    Port int
    Zone string // IPv6 范围寻址域
}

• ResolveTCPAddr 函数：将 addr 作为 TCP 地址解析并返回。参数 addr 格式为 ”host:port” 或 ”[ipv6-host%zone]:port”，解析得到网络名和端口名；net 必须是 ”udp”、”udp4″ 或 ”udp6″。
• Network 方法：返回地址的网络类型，”udp”。

UnixAddr 类型：代表一个 Unix 域 socket 终端地址