219 lines
4.6 KiB
Markdown
219 lines
4.6 KiB
Markdown
# Minecraft Server Query Library (Go)
|
||
|
||
一个高效、功能完备的Minecraft服务器状态查询库，支持连接复用、SRV记录解析和智能连接管理。
|
||
|
||
## 功能特性
|
||
|
||
* ✅ 自动SRV记录解析
|
||
* 🚀 TCP连接池复用
|
||
* ⚡ 毫秒级延迟检测
|
||
* 📦 完整的服务器状态信息
|
||
* 🔒 线程安全设计
|
||
* ⏱️ 可配置超时控制
|
||
* 🩺 自动连接健康检查
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
go get git.mei.lv/mei/go-mc-server-listener/minecraftquery
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
```go
|
||
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 函数
|
||
|
||
```go
|
||
func Query(addr string, port int, timeout time.Duration) (*ServerStatus, error)
|
||
```
|
||
|
||
**参数**:
|
||
|
||
* `addr`: 服务器地址（域名或IP）
|
||
* `port`: 服务器端口（当存在SRV记录时会被覆盖）
|
||
* `timeout`: 整个查询操作的超时时间
|
||
|
||
**返回值**:
|
||
|
||
* `*ServerStatus`: 服务器状态信息
|
||
* `error`: 错误信息（包含上下文）
|
||
|
||
### ServerStatus 结构体
|
||
|
||
```go
|
||
type ServerStatus struct {
|
||
Version string // 服务器版本名称
|
||
Protocol int // 协议版本号
|
||
Online int // 当前在线玩家数
|
||
MaxPlayers int // 最大玩家容量
|
||
Description string // 服务器描述/MOTD
|
||
Latency time.Duration // 查询延迟
|
||
ResolvedHost string // 实际连接地址（包含SRV解析结果）
|
||
}
|
||
```
|
||
|
||
## 高级功能
|
||
|
||
### 1. SRV记录解析
|
||
|
||
库会自动检测并优先使用SRV记录：
|
||
|
||
```go
|
||
// 当存在 _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. 连接池配置
|
||
|
||
```go
|
||
// 调整连接池设置
|
||
minecraftquery.ConnExpiry = 1 * time.Minute // 连接保留时间
|
||
minecraftquery.PoolCapacity = 20 // 最大连接数
|
||
|
||
// 手动清理连接池
|
||
minecraftquery.CleanupPool()
|
||
```
|
||
|
||
### 3. 自定义DNS解析
|
||
|
||
```go
|
||
// 实现自定义解析器
|
||
minecraftquery.CustomSRVResolver = func(domain string) (string, int, error) {
|
||
// 自定义SRV解析逻辑
|
||
return "custom.host", 25565, nil
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
常见错误类型：
|
||
|
||
```go
|
||
// 网络错误
|
||
if errors.Is(err, minecraftquery.ErrConnectionFailed) {
|
||
// 处理连接失败
|
||
}
|
||
|
||
// 协议错误
|
||
if errors.Is(err, minecraftquery.ErrProtocolError) {
|
||
// 处理协议不匹配
|
||
}
|
||
|
||
// 超时错误
|
||
if errors.Is(err, minecraftquery.ErrTimeout) {
|
||
// 处理查询超时
|
||
}
|
||
```
|
||
|
||
## 性能建议
|
||
|
||
1. **连接复用**：
|
||
|
||
* 默认保持连接30秒
|
||
* 适合高频查询场景（5-10次/秒）
|
||
|
||
2. **超时设置**：
|
||
|
||
```go
|
||
// 生产环境推荐设置
|
||
queryTimeout := 1 * time.Second // 快速失败
|
||
retries := 2 // 重试次数
|
||
```
|
||
|
||
3. **批量查询**：
|
||
|
||
```go
|
||
// 使用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()
|
||
```
|
||
|
||
## 示例
|
||
|
||
### 基本使用
|
||
|
||
```go
|
||
status, err := minecraftquery.Query("hypixel.net", 25565, 3*time.Second)
|
||
```
|
||
|
||
### 自定义配置
|
||
|
||
```go
|
||
// 在init函数中配置
|
||
func init() {
|
||
minecraftquery.ConnExpiry = 2 * time.Minute
|
||
minecraftquery.PoolCapacity = 30
|
||
minecraftquery.CustomSRVResolver = MyCustomResolver
|
||
}
|
||
```
|
||
|
||
### 错误处理
|
||
|
||
```go
|
||
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之前）协议
|