netipzh

Lightweight Go package that provides IP address and network operations with Chinese function names, plus enhanced context when handling issues

---

CHINESE README

中文说明

---

DISCLAIMER

Writing Go code in Chinese is a viable technique, but something to avoid in production engineering. This approach should not be used in serious and business settings. Teams and companies that embrace it could face contempt from peers and negative judgment across the profession. In business companies, this practice is even more prone to becoming a target of public criticism. This project is dedicated to research and academic studies. Do not use this approach in production.

---

Main Features

🎯 Chinese Function Names: Intuitive Chinese-named wrappers around Go's standard net/netip package 🔒 Enhanced Context on Exceptions: Stack traces with rich context using github.com/pkg/errors 🎨 Type-Safe Operations: Returns pointers enabling nil values on errors in idiomatic Go 📊 Comprehensive Coverage: IP addresses (IPv4/IPv6), ports, and CIDR prefixes 🌐 Clean Exception Returns: Standard handling with enhanced context on exceptions

Installation

go get github.com/yylego/netipzh

Quick Start

IP Address Parsing

Parse IPv4 and IPv6 addresses using P解析地址.

package main

import (
	"fmt"

	"github.com/yylego/netipzh"
	"github.com/yylego/rese"
)

func main() {
	// Parse IPv4 address
	ipv4 := rese.P1(netipzh.P解析地址("192.168.1.100"))
	fmt.Printf("IPv4 Address: %s\n", ipv4.String())
	fmt.Printf("Is IPv4: %v\n", ipv4.Is4())
	fmt.Printf("Is Private: %v\n", ipv4.IsPrivate())

	fmt.Println()

	// Parse IPv6 address
	ipv6 := rese.P1(netipzh.P解析地址("2001:db8::1"))
	fmt.Printf("IPv6 Address: %s\n", ipv6.String())
	fmt.Printf("Is IPv6: %v\n", ipv6.Is6())
	fmt.Printf("Is Loopback: %v\n", ipv6.IsLoopback())
}

⬆️ Source: Source

Address and Port Operations

Parse and construct address:port combinations using P解析地址端口 and G构建地址端口.

package main

import (
	"fmt"

	"github.com/yylego/netipzh"
	"github.com/yylego/rese"
)

func main() {
	// Parse address with port
	addrPort := rese.P1(netipzh.P解析地址端口("192.168.1.100:8080"))
	fmt.Printf("Address:Port: %s\n", addrPort.String())
	fmt.Printf("Address: %s\n", addrPort.Addr().String())
	fmt.Printf("Port: %d\n", addrPort.Port())

	fmt.Println()

	// Construct address with port
	addr := rese.P1(netipzh.P解析地址("10.0.0.1"))
	newAddrPort := netipzh.G构建地址端口(*addr, 443)
	fmt.Printf("Constructed: %s\n", newAddrPort.String())
	fmt.Printf("Port: %d\n", newAddrPort.Port())
}

⬆️ Source: Source

Network Prefix Operations

Parse and construct CIDR network prefixes using P解析前缀 and G构建前缀.

package main

import (
	"fmt"

	"github.com/yylego/netipzh"
	"github.com/yylego/rese"
)

func main() {
	// Parse CIDR prefix
	prefix := rese.P1(netipzh.P解析前缀("192.168.1.0/24"))
	fmt.Printf("Prefix: %s\n", prefix.String())
	fmt.Printf("Network Address: %s\n", prefix.Addr().String())
	fmt.Printf("Prefix Bits: %d\n", prefix.Bits())
	fmt.Printf("Is Valid: %v\n", prefix.IsValid())

	fmt.Println()

	// Construct prefix from address
	addr := rese.P1(netipzh.P解析地址("10.0.0.0"))
	newPrefix := rese.P1(netipzh.G构建前缀(*addr, 16))
	fmt.Printf("Constructed Prefix: %s\n", newPrefix.String())
	fmt.Printf("Prefix Bits: %d\n", newPrefix.Bits())

	// Check if an address is in the prefix
	testAddr := rese.P1(netipzh.P解析地址("10.0.5.100"))
	fmt.Printf("Is %s in %s? %v\n", testAddr.String(), newPrefix.String(), newPrefix.Contains(*testAddr))
}

⬆️ Source: Source

API Reference

Main Package Functions

Parse Functions

• P解析地址(s string) (*netip.Addr, error) - Parse string to IP address (IPv4 or IPv6)
• P解析地址端口(s string) (*netip.AddrPort, error) - Parse string to address:port combination
• P解析前缀(s string) (*netip.Prefix, error) - Parse string to CIDR network prefix

Build Functions

• G构建地址端口(addr netip.Addr, port uint16) *netip.AddrPort - Construct AddrPort from address and port
• G构建前缀(addr netip.Addr, bits int) (*netip.Prefix, error) - Construct Prefix from address and bit length

Exception Context

Exceptions from this package include enhanced context:

addr, err := netipzh.P解析地址("invalid.ip.address")
if err != nil {
    // Includes context: "解析地址错误: <the source message>"
    // With stack trace from github.com/pkg/errors
    fmt.Printf("%+v\n", err) // Prints with stack trace
}

Function Name Meanings

• P解析地址 - Parse Address (解析地址 = parse address)
• P解析地址端口 - Parse Address Port (解析地址端口 = parse address port)
• P解析前缀 - Parse Prefix (解析前缀 = parse prefix)
• G构建地址端口 - Generate Address Port (构建地址端口 = build address port)
• G构建前缀 - Generate Prefix (构建前缀 = build prefix)

Safe Type Operations

Functions that return pointers enable idiomatic nil checks when issues happen:

addr, err := netipzh.P解析地址("192.168.1.1")
if err != nil {
    // Handle the issue
    return
}
// addr is *netip.Addr, guaranteed non-nil at this point
fmt.Println(addr.String())

Safe Design

This package uses Go's standard net/netip package, which provides safe and efficient IP address operations. The netip package is designed to be allocation-free and safe from common IP address parsing vulnerabilities.

---

📄 License

MIT License. See LICENSE.

---

🤝 Contributing

Contributions are welcome! Report bugs, suggest features, and contribute code:

• 🐛 Found a mistake? Open an issue on GitHub with reproduction steps
• 💡 Have a feature idea? Create an issue to discuss the suggestion
• 📖 Documentation confusing? Report it so we can improve
• 🚀 Need new features? Share the use cases to help us understand requirements
• ⚡ Performance issue? Help us optimize through reporting slow operations
• 🔧 Configuration problem? Ask questions about complex setups
• 📢 Follow project progress? Watch the repo to get new releases and features
• 🌟 Success stories? Share how this package improved the workflow
• 💬 Feedback? We welcome suggestions and comments

---

🔧 Development

New code contributions, follow this process:

1. Fork: Fork the repo on GitHub (using the webpage UI).
2. Clone: Clone the forked project (git clone https://github.com/yourname/repo-name.git).
3. Navigate: Navigate to the cloned project (cd repo-name)
4. Branch: Create a feature branch (git checkout -b feature/xxx).
5. Code: Implement the changes with comprehensive tests
6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
7. Documentation: Update documentation to support client-facing changes and use significant commit messages
8. Stage: Stage changes (git add .)
9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
10. Push: Push to the branch (git push origin feature/xxx).
11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

---

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

• ⭐ Give GitHub stars if this project helps you
• 🤝 Share with teammates and (golang) programming friends
• 📝 Write tech blogs about development tools and workflows - we provide content writing support
• 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

---

GitHub Stars