From cf97c791c4e4ed38fad19b4c3eb60308de1cb42f Mon Sep 17 00:00:00 2001
From: mei <i@mmeiblog.cn>
Date: Sat, 5 Apr 2025 10:33:39 +0800
Subject: [PATCH] update: README.md

---
 README.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 218 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2d546a5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,218 @@
+# 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之前）协议