From 6b2e18e55138fd2b1728c6e8bc5a58592dda372e Mon Sep 17 00:00:00 2001
From: lion <chenxin619315@gmail.com>
Date: Sat, 6 Sep 2025 10:07:13 +0800
Subject: [PATCH] update the Doc for the latest API call (IPv4 & IPv6)

---
 binding/golang/ReadMe.md | 69 ++++++++++++++++++++++++++++------------
 1 file changed, 49 insertions(+), 20 deletions(-)

diff --git a/binding/golang/ReadMe.md b/binding/golang/ReadMe.md
index c440317..ecbcdfa 100644
--- a/binding/golang/ReadMe.md
+++ b/binding/golang/ReadMe.md
@@ -7,6 +7,21 @@
 go get github.com/lionsoul2014/ip2region/binding/golang
 ```
 
+### 关于 IPv4 / IPv6
+该 xdb 查询客户端实现同时支持对 IPv4 和 IPv6 的查询，使用方式如下：
+```golang
+// 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件，IP版本指定为 xdb.IPv4
+dbPath := "../../data/ip2region_v4.xdb"  // 或者你的 ipv4 xdb 的路径
+version := xdb.IPv4
+
+// 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件，IP版本指定为 xdb.IPv6
+dbPath = "../../data/ip2region_v6.xdb"  // 或者你的 ipv6 xdb 路径
+version = xdb.IPv6
+
+// dbPath 指定的 xdb 的 IP 版本必须和 version 指定的一致，不然查询执行的时候会报错
+// 备注：以下演示直接使用 dbPath 和 version 变量
+```
+
 ### 完全基于文件的查询
 
 ```golang
@@ -17,8 +32,8 @@ import (
 )
 
 func main() {
-    var dbPath = "ip2region.xdb file path"
-    searcher, err := xdb.NewWithFileOnly(dbPath)
+	// 通过 version 和 dbPath 创建完全基于文件的查询对象
+    searcher, err := xdb.NewWithFileOnly(version, dbPath)
     if err != nil {
         fmt.Printf("failed to create searcher: %s\n", err.Error())
         return
@@ -26,8 +41,9 @@ func main() {
 
     defer searcher.Close()
 
-    // do the search
-    var ip = "1.2.3.4"
+    // 定位信息查询：IPv4 或者 IPv6 的地址都支持
+    var ip = "1.2.3.4"  // IPv4
+	// ip = "2001:4:112:ffff:ffff:ffff:ffff:ffff" // IPv6
     var tStart = time.Now()
     region, err := searcher.SearchByStr(ip)
     if err != nil {
@@ -35,6 +51,7 @@ func main() {
         return
     }
 
+	// IPv4 或者 IPv6 的定位信息 
     fmt.Printf("{region: %s, took: %s}\n", region, time.Since(tStart))
 
     // 备注：并发使用，每个 goroutine 需要创建一个独立的 searcher 对象。
@@ -46,14 +63,14 @@ func main() {
 可以预先加载 `vectorIndex` 缓存，然后做成全局变量，每次创建 searcher 的时候使用全局的 `vectorIndex`，可以减少一次固定的 IO 操作从而加速查询，减少系统 io 压力。
 ```golang
 // 1、从 dbPath 加载 VectorIndex 缓存，把下述 vIndex 变量全局到内存里面。
-vIndex, err := LoadVectorIndexFromFile(dbPath)
+vIndex, err := xdb.LoadVectorIndexFromFile(dbPath)
 if err != nil {
     fmt.Printf("failed to load vector index from `%s`: %s\n", dbPath, err)
     return
 }
 
 // 2、用全局的 vIndex 创建带 VectorIndex 缓存的查询对象。
-searcher, err := xdb.NewWithVectorIndex(dbPath, vIndex)
+searcher, err := xdb.NewWithVectorIndex(version, dbPath, vIndex)
 if err != nil {
     fmt.Printf("failed to create searcher with vector index: %s\n", err)
     return
@@ -67,14 +84,14 @@ if err != nil {
 可以预先加载整个 ip2region.xdb 到内存，完全基于内存查询，类似于之前的 memory search 查询。
 ```golang
 // 1、从 dbPath 加载整个 xdb 到内存
-cBuff, err := LoadContentFromFile(dbPath)
+cBuff, err := xdb.LoadContentFromFile(dbPath)
 if err != nil {
     fmt.Printf("failed to load content from `%s`: %s\n", dbPath, err)
     return
 }
 
 // 2、用全局的 cBuff 创建完全基于内存的查询对象。
-searcher, err := xdb.NewWithBuffer(cBuff)
+searcher, err := xdb.NewWithBuffer(version, cBuff)
 if err != nil {
     fmt.Printf("failed to create searcher with content: %s\n", err)
     return
@@ -97,30 +114,42 @@ make
 # 查询测试
 
 通过 `xdb_searcher search` 命令来测试 ip2region.xdb 的查询：
-```
-➜  golang git:(v2.0_xdb) ./xdb_searcher search
+```bash
+➜  golang git:(fr_xdb_ipv6) ✗ ./xdb_searcher search                                 
 ./xdb_searcher search [command options]
 options:
  --db string              ip2region binary xdb file path
  --cache-policy string    cache policy: file/vectorIndex/content
 ```
 
-例如：使用默认的 data/ip2region.xdb 进行查询测试
+例如：使用默认的 data/ip2region_v4.xdb 进行 IPv4 的查询测试
 ```bash
-➜  golang git:(v2.0_xdb) ✗ ./xdb_searcher search --db=../../data/ip2region.xdb
-ip2region xdb searcher test program, type `quit` to exit
-ip2region>> 1.2.3.4
-{region:美国|0|华盛顿|0|谷歌, took:101.57µs}
+ip2region xdb searcher test program
+source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex)
+type 'quit' to exit
+ip2region>> 219.133.111.87
+{region: 中国|0|广东省|深圳市|电信, ioCount: 2, took: 19.005µs}
+ip2region>> 
 ```
 
-输入 ip 地址进行查询即可，输入 quit 退出测试程序。可以设置 `cache-policy` 为 file/vectorIndex/content 来测试不同的查询缓存机制。
+使用默认的 data/ip2region_v6.xdb 进行 IPv6 的查询：
+```bash
+ip2region xdb searcher test program
+source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex)
+type 'quit' to exit
+ip2region>> 240e:87c:892:ffff:ffff:ffff:ffff:ffff
+{region: 中国|广东省|深圳市|专线用户, ioCount: 12, took: 130.294µs}
+ip2region>>
+```
+
+输入对应版本的 ip 地址进行查询即可，输入 quit 退出测试程序。可以设置 `cache-policy` 为 file/vectorIndex/content 来测试不同的查询缓存机制。
 
 
 # bench 测试
 
 通过 `xdb_searcher bench` 命令来进行自动 bench 测试，一方面确保程序和 `xdb` 文件都没有错误，另一方面通过大量的查询得到平均查询性能：
 ```bash
-➜  golang git:(v2.0_xdb) ./xdb_searcher bench
+➜  golang git:(fr_xdb_ipv6) ./xdb_searcher bench
 ./xdb_searcher bench [command options]
 options:
  --db string              ip2region binary xdb file path
@@ -128,10 +157,10 @@ options:
  --cache-policy string    cache policy: file/vectorIndex/content
 ```
 
-例如：通过 data/ip2region.xdb 和 data/ip.merge.txt 进行 bench 测试：
+例如：通过 data/ip2region_v4.xdb 和 data/ipv4_source.txt 进行 bench 测试：
 ```bash
-➜  golang git:(v2.0_xdb) ✗ ./xdb_searcher bench --db=../../data/ip2region.xdb --src=../../data/ip.merge.txt
-Bench finished, {total: 3417955, took: 28.211578339s, cost: 8253 ns/op}
+➜  golang git:(fr_xdb_ipv6) ✗ ./xdb_searcher bench --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt 
+Bench finished, {cachePolicy: vectorIndex, total: 1367688, took: 19.730647202s, cost: 14 μs/op}
 ```
 
 可以设置 `cache-policy` 参数来分别测试 file/vectorIndex/content 不同缓存实现机制的效率。