# 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之前）协议