go-mc-server-listener/README.md

Minecraft Server Query Library (Go)

一个高效、功能完备的Minecraft服务器状态查询库，支持连接复用、SRV记录解析和智能连接管理。

功能特性

• ✅ 自动SRV记录解析
• 🚀 TCP连接池复用
• ⚡ 毫秒级延迟检测
• 📦 完整的服务器状态信息
• 🔒 线程安全设计
• ⏱️ 可配置超时控制
• 🩺 自动连接健康检查

安装

go get git.mei.lv/mei/go-mc-server-listener/minecraftquery

快速开始

package main

import (
 "fmt"
 "time"
 "git.mei.lv/mei/go-mc-server-listener/minecraftquery"
)

func main() {
 // 基本查询
 status, err := minecraftquery.Query("mc.example.com", 25565, 3*time.Second)
 if err != nil {
  panic(err)
 }

 fmt.Printf("服务器版本: %s (协议版本 %d)\n", status.Version, status.Protocol)
 fmt.Printf("在线玩家: %d/%d\n", status.Online, status.MaxPlayers)
 fmt.Printf("连接延迟: %s\n", status.Latency)
 fmt.Printf("实际连接地址: %s\n", status.ResolvedHost)
}

API文档

Query 函数

func Query(addr string, port int, timeout time.Duration) (*ServerStatus, error)

参数:

• addr: 服务器地址（域名或IP）
• port: 服务器端口（当存在SRV记录时会被覆盖）
• timeout: 整个查询操作的超时时间

返回值:

• *ServerStatus: 服务器状态信息
• error: 错误信息（包含上下文）

ServerStatus 结构体

type ServerStatus struct {
 Version      string        // 服务器版本名称
 Protocol     int           // 协议版本号
 Online       int           // 当前在线玩家数
 MaxPlayers   int           // 最大玩家容量
 Description  string        // 服务器描述/MOTD
 Latency      time.Duration // 查询延迟
 ResolvedHost string        // 实际连接地址（包含SRV解析结果）
}

高级功能

1. SRV记录解析

库会自动检测并优先使用SRV记录：

// 当存在 _minecraft._tcp.mc.example.com 的SRV记录时
status, _ := minecraftquery.Query("mc.example.com", 25565, 3*time.Second)
fmt.Println(status.ResolvedHost) // 输出类似 "real-server.com:25566"

2. 连接池配置

// 调整连接池设置
minecraftquery.ConnExpiry = 1 * time.Minute  // 连接保留时间
minecraftquery.PoolCapacity = 20             // 最大连接数

// 手动清理连接池
minecraftquery.CleanupPool()

3. 自定义DNS解析

// 实现自定义解析器
minecraftquery.CustomSRVResolver = func(domain string) (string, int, error) {
 // 自定义SRV解析逻辑
 return "custom.host", 25565, nil
}

错误处理

常见错误类型：

// 网络错误
if errors.Is(err, minecraftquery.ErrConnectionFailed) {
 // 处理连接失败
}

// 协议错误
if errors.Is(err, minecraftquery.ErrProtocolError) {
 // 处理协议不匹配
}

// 超时错误
if errors.Is(err, minecraftquery.ErrTimeout) {
 // 处理查询超时
}

性能建议

1. 连接复用：

• 默认保持连接30秒
• 适合高频查询场景（5-10次/秒）

2. 超时设置：

// 生产环境推荐设置
queryTimeout := 1 * time.Second  // 快速失败
retries := 2                     // 重试次数

3. 批量查询：

// 使用goroutine并行查询
servers := []string{"server1", "server2", "server3"}
var wg sync.WaitGroup

for _, s := range servers {
    wg.Add(1)
    go func(addr string) {
        defer wg.Done()
        status, _ := minecraftquery.Query(addr, 25565, 2*time.Second)
        // 处理结果
    }(s)
}
wg.Wait()

示例

基本使用

status, err := minecraftquery.Query("hypixel.net", 25565, 3*time.Second)

自定义配置

// 在init函数中配置
func init() {
 minecraftquery.ConnExpiry = 2 * time.Minute
 minecraftquery.PoolCapacity = 30
 minecraftquery.CustomSRVResolver = MyCustomResolver
}

错误处理

status, err := minecraftquery.Query("offline.server", 25565, 1*time.Second)
if err != nil {
 switch {
 case errors.Is(err, minecraftquery.ErrConnectionFailed):
  fmt.Println("连接失败")
 case errors.Is(err, minecraftquery.ErrProtocolError):
  fmt.Println("协议错误")
 case errors.Is(err, minecraftquery.ErrTimeout):
  fmt.Println("查询超时")
 default:
  fmt.Println("未知错误:", err)
 }
}

注意事项

1. DNS缓存：

• SRV记录查询结果会被本地DNS缓存
• 需要自定义解析请使用CustomSRVResolver

2. 连接限制：

• 默认最大保持10个活跃连接
• 修改PoolCapacity调整容量

3. 协议支持：

• 支持Minecraft 1.7+ 服务器
• 不支持旧版（Beta 1.8之前）协议