From 87418d879a95b351eb91c4da6356a6b6bc0ddb6f Mon Sep 17 00:00:00 2001 From: lionsoul2014 Date: Tue, 24 Feb 2026 15:29:41 +0800 Subject: [PATCH 1/3] add english readme for pure lua binding --- README.md | 4 +- README_zh.md | 4 +- binding/lua/README.md | 128 ++++++++++++---------- binding/lua/README_zh.md | 225 +++++++++++++++++++++++++++++++++++++++ 4 files changed, 301 insertions(+), 60 deletions(-) create mode 100644 binding/lua/README_zh.md diff --git a/README.md b/README.md index d92f136..1c9db4a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: Supported Languages: [中文简体](README_zh.md) | [English](README.md) # ip2region @@ -42,7 +42,7 @@ For API introductions, usage documentation, and test programs, please refer to t | [Java](binding/java/README.md) | java xdb query client | :white_check_mark: | :white_check_mark: | | [C](binding/c/README.md) | POSIX C xdb query client | :white_check_mark: | :white_check_mark: | | [Lua_c](binding/lua_c/README.md) | lua c extension xdb query client | :white_check_mark: | :white_check_mark: | -| [Lua](binding/lua) | lua xdb query client | :white_check_mark: | :white_check_mark: | +| [Lua](binding/lua/README.md) | lua xdb query client | :white_check_mark: | :white_check_mark: | | [Rust](binding/rust) | rust xdb query client | :white_check_mark: | :white_check_mark: | | [Python](binding/python) | python xdb query client | :white_check_mark: | :white_check_mark: | | [Javascript](binding/javascript) | javascript xdb query client | :white_check_mark: | :white_check_mark: | diff --git a/README_zh.md b/README_zh.md index bc431ab..3cf84ee 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,4 +1,4 @@ -[中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: 语言支持: [中文简体](README_zh.md) | [English](README.md) # ip2region @@ -41,7 +41,7 @@ API 介绍，使用文档和测试程序请参考对应 `searcher` 查询客户 | [Java](binding/java/README_zh.md) | java xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [C](binding/c/README_zh.md) | POSIX C xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Lua_c](binding/lua_c/README_zh.md) | lua c 扩展 xdb 查询客户端 | :white_check_mark: | :white_check_mark: | -| [Lua](binding/lua) | lua xdb 查询客户端 | :white_check_mark: | :white_check_mark: | +| [Lua](binding/lua/README_zh.md) | lua xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Rust](binding/rust) | rust xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Python](binding/python) | python xdb 查询客户端 | :white_check_mark: | :white_check_mark: | | [Javascript](binding/javascript) | javascript xdb 查询客户端 | :white_check_mark: | :white_check_mark: | diff --git a/binding/lua/README.md b/binding/lua/README.md index cfce4c3..f1e1a2d 100644 --- a/binding/lua/README.md +++ b/binding/lua/README.md @@ -1,67 +1,77 @@ -# ip2region xdb lua 查询客户端实现 +:globe_with_meridians: Supported Languages: [中文简体](README_zh.md) | [English](README.md) -#### 备注：请优先使用 lua_c 扩展 xdb 查询客户端，性能比纯 lua 实现的要快很多！！！ +# ip2region lua query client -# 版本兼容 -该实现兼容 lua `5.3`, `5.4`，且不再提供更低版本的兼容，如果需要在更低版本的 Lua 下使用请考虑使用 `[lua_c](../lua_c/)` 扩展。 +#### Note: Please prioritize the use of the lua_c extension query client, as its performance is much faster than the pure lua implementation!!! -# 使用方式 +# Version Compatibility + +This implementation is compatible with lua `5.3` and `5.4`, and no longer provides compatibility for lower versions. If you need to use it under lower versions of Lua, please consider using the `[lua_c](../lua_c/)` extension. + +# Usage + +### About Query API + +The prototype of the query API is as follows: -### 关于查询 API -查询 API 的原型如下： ```lua --- 通过字符串 IP 查询 +-- Query via IP string search_by_string(ip_string) (region, error) --- 通过 parse_ip 返回的 bytes IP 查询 +-- Query via bytes IP returned by parse_ip search(ip_bytes) (region, error) ``` -如果查询出错则会返回非 `nil` 的 error 字符串信息，如果查询成功则会返回字符串的 `region` 信息，如果查询的 IP 地址找不到则会返回空字符串 `""`。 -### 关于 IPv4 和 IPv6 +If the query fails, it returns a non-`nil` error string. If successful, it returns the `region` information as a string. If the IP address cannot be found, it returns an empty string `""`. + +### About IPv4 and IPv6 + ```lua local xdb = require("xdb_searcher") --- 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件，IP版本指定为 Version.IPv4 -local dbPath = "../../data/ip2region_v4.xdb" -- 或者你的 ipv4 xdb 的路径 +-- For IPv4: Set xdb path to the v4 xdb file, specify IP version as Version.IPv4 +local dbPath = "../../data/ip2region_v4.xdb" -- or your ipv4 xdb path local version = xdb.IPv4 --- 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件，IP版本指定为 Version.IPv6 -local dbPath = "../../data/ip2region_v6.xdb" -- 或者你的 ipv6 xdb 路径 +-- For IPv6: Set xdb path to the v6 xdb file, specify IP version as Version.IPv6 +local dbPath = "../../data/ip2region_v6.xdb" -- or your ipv6 xdb path local version = xdb.IPv6 --- dbPath 指定的 xdb 的 IP 版本必须和 version 指定的一致，不然查询执行的时候会报错 --- 备注：以下演示直接使用 dbPath 和 version 变量 +-- The IP version of the xdb specified by dbPath must match the version specified, otherwise an error will occur during query execution +-- Note: The following demonstration directly uses the dbPath and version variables ``` -### 文件验证 -建议您主动去验证 xdb 文件的适用性，因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件，验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证，例如在服务启动的时候，或者手动调用命令验证确认版本匹配即可，不要在每次创建的 Searcher 的时候运行验证，这样会影响查询的响应速度，尤其是高并发的使用场景。 +### File Verification + +It is recommended that you actively verify the suitability of the xdb file, as some new features in the future may cause the current Searcher version to be incompatible with the xdb file you are using. Verification can avoid unpredictable errors during runtime. You don't need to verify every time; for example, verify when the service starts or by manually calling the verification command to confirm version matching. Do not run verification every time a Searcher is created, as this will affect query response speed, especially in high-concurrency scenarios. + ```lua local xdb = require('xdb_searcher') local err = xdb.verify(dbPath); if err ~= nil then - -- 适用性验证失败！！！ - -- 当前查询客户端实现不适用于 dbPath 指定的 xdb 文件的查询. - -- 应该停止启动服务，使用合适的 xdb 文件或者升级到适合 dbPath 的 Searcher 实现。 + -- Suitability verification failed!!! + -- The current query client implementation is not suitable for the xdb file specified by dbPath. + -- You should stop the service and use a suitable xdb file or upgrade to a Searcher implementation compatible with dbPath. print(string.format("binding is not applicable for xdb file '%s': %s", dbPath, err)) return end --- 验证通过，当前使用的 Searcher 可以安全的用于对 dbPath 指向的 xdb 的查询操作 +-- Verification passed, the current Searcher can safely be used for query operations on the xdb pointed to by dbPath ``` -### 完全基于文件的查询 +### Entirely File-Based Query + ```lua local xdb = require("xdb_searcher") --- 1，使用上述的 version 和 dbPath 创建完全基于文件的查询对象 +-- 1. Create an entirely file-based query object using the version and dbPath mentioned above local searcher, err = xdb.new_with_file_only(version, db_path) if err ~= nil then print(string.format("failed to create searcher: %s", err)) return end --- 2、调用查询 API 进行查询，IPv4 或者 IPv6 的地址都是同一个接口 +-- 2. Call the query API; with both IPv4 and IPv6 addresses supported local ip_str = "1.2.3.4" -- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 local s_time = xdb.now() @@ -73,34 +83,35 @@ end print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) --- 3、关闭资源 +-- 3. Close resources searcher:close() --- 备注：并发使用，每个协程需要创建单独的 xdb 查询对象 +-- Note: For concurrent use, each coroutine needs to create a separate xdb query object ``` -### 缓存 `VectorIndex` 索引 +### Caching `VectorIndex` + +If supported by your `lua` environment, you can pre-load the vectorIndex cache and make it a global variable. Using the global vectorIndex every time a Searcher is created can reduce one fixed IO operation, thereby accelerating queries and reducing IO pressure. -如果你的 `lua` 母环境支持，可以预先加载 vectorIndex 缓存，然后做成全局变量，每次创建 Searcher 的时候使用全局的 vectorIndex，可以减少一次固定的 IO 操作从而加速查询，减少 io 压力。 ```lua local xdb = require("xdb_searcher") --- 1、从指定的 db_path 加载 vectorIndex 缓存，把下述的 v_index 对象做成全局变量。 --- vectorIndex 加载一次即可，建议在服务启动的时候加载为全局对象。 +-- 1. Load vectorIndex cache from the specified db_path and make the v_index object below a global variable. +-- vectorIndex only needs to be loaded once; it is recommended to load it as a global object when the service starts. v_index, err = xdb.load_vector_index(dbPath) if err ~= nil then print(string.format("failed to load vector index from '%s'", db_path)) return end --- 2、使用全局的 v_index 创建带 vectorIndex 缓存的查询对象。 +-- 2. Use the global v_index to create a query object with vectorIndex cache. searcher, err = xdb.new_with_vector_index(version, dbPath, v_index) if err ~= nil then print(string.format("failed to create vector index searcher: %s", err)) return end --- 3、调用查询 API，IPv4 或者 IPv6 都是同一个接口 +-- 3. Call the query API; the same interface is used for both IPv4 and IPv6 local ip_str = "1.2.3.4" -- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 local s_time = xdb.now() @@ -112,34 +123,35 @@ end print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) --- 4、关闭资源 +-- 4. Close resources searcher:close() --- 备注：并发使用，每个协程需要创建单独的 xdb 查询对象，但是共享全局的 v_index 对象 +-- Note: For concurrent use, each coroutine needs to create a separate xdb query object, but they share the global v_index object ``` -### 缓存整个 `xdb` 数据 +### Caching the Entire `xdb` File + +If supported by your `lua` environment, you can pre-load the entire xdb data into memory to achieve completely memory-based queries, similar to the previous memory search. -如果你的 `lua` 母环境支持，可以预先加载整个 xdb 的数据到内存，这样可以实现完全基于内存的查询，类似之前的 memory search 查询。 ```lua local xdb = require("xdb_searcher") --- 1、从上述的 dbPath 加载整个 xdb 到内存。 --- xdb内容加载一次即可，建议在服务启动的时候加载为全局对象。 +-- 1. Load the entire xdb into memory from the specified dbPath. +-- xdb content only needs to be loaded once; it is recommended to load it as a global object when the service starts. content, err = xdb.load_content(dbPath) if err ~= nil then print(string.format("failed to load xdb content: %s", err)) return end --- 2、使用全局的 content 创建带完全基于内存的查询对象。 +-- 2. Use the global content to create an entirely memory-based query object. searcher, err = xdb.new_with_buffer(version, content) if err ~= nil then print(string.format("failed to create content buffer searcher: %s", err)) return end --- 3、调用查询 API，IPv4 或者 IPv6 都是同一个接口 +-- 3. Call the query API; the same interface is used for both IPv4 and IPv6 local ip_str = "1.2.3.4" -- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 local s_time = xdb.now() @@ -151,17 +163,17 @@ end print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) --- 4、关闭资源 - 该 searcher 对象可以安全用于并发，等整个服务关闭的时候再关闭 searcher +-- 4. Close resources - This searcher object can be safely used for concurrency; close the searcher only when the entire service is shut down -- searcher:close() --- 备注：并发使用，用 xdb 整个缓存创建的查询对象可以安全的用于并发。 --- 建议在服务启动的时候创建好全局的 searcher 对象，然后全局并发使用。 +-- Note: For concurrent use, query objects created with the entire xdb cache can be safely used concurrently. +-- It is recommended to create a global searcher object when the service starts and then use it globally and concurrently. ``` +# Query Testing -# 查询测试 +Perform query tests via the `lua search_test.lua` script: -通过 `lua search_test.lua` 脚本来进行查询测试： ```bash ➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua lua search_test.lua [command options] @@ -170,7 +182,8 @@ options: --cache-policy string cache policy: file/vectorIndex/content ``` -例如：使用默认的 data/ip2region_v4.xdb 文件进行 IPv4 的查询测试： +For example: using the default data/ip2region_v4.xdb file for IPv4 query testing: + ```bash ➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua --db=../../data/ip2region_v4.xdb ip2region xdb searcher test program @@ -182,7 +195,8 @@ ip2region>> 113.118.113.77 {region: 中国|广东省|深圳市|电信|CN, io_count: 2, took: 0μs} ``` -例如：使用默认的 data/ip2region_v6.xdb 文件进行 IPv6 的查询测试： +For example: using the default data/ip2region_v6.xdb file for IPv6 query testing: + ```bash ➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua --db=../../data/ip2region_v6.xdb ip2region xdb searcher test program @@ -194,12 +208,12 @@ ip2region>> 2604:a840:3::a04d {region: United States|California|San Jose|xTom|US, io_count: 13, took: 0μs} ``` -输入 ip 即可进行查询测试。也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的效率。 +Enter an IP to perform a query test. You can also set `cache-policy` to file/vectorIndex/content respectively to test the efficiency of the three different cache implementations. +# Bench Testing -# bench 测试 +Perform automatic bench testing via the `lua bench_test.lua` script. This ensures that the `xdb` file has no errors and tests average query performance through a large number of queries: -通过 `lua bench_test.lua` 脚本来进行自动 bench 测试，一方面确保 `xdb` 文件没有错误，另一方面通过大量的查询测试平均查询性能： ```bash ➜ lua git:(fr_lua_ipv6) ✗ lua bench_test.lua lua bench_test.lua [command options] @@ -209,15 +223,17 @@ options: --cache-policy string cache policy: file/vectorIndex/content ``` -例如：通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 文件进行 IPv4 的 bench 测试： +For example: perform IPv4 bench testing using default data/ip2region_v4.xdb and data/ipv4_source.txt files: + ```bash lua bench_test.lua --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt ``` -例如：通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 文件进行 IPv6 的 bench 测试： +For example: perform IPv6 bench testing using default data/ip2region_v6.xdb and data/ipv6_source.txt files: + ```bash lua bench_test.lua --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt ``` -可以通过设置 `cache-policy` 参数来分别测试 file/vectorIndex/content 三种不同的缓存实现的的性能。 -@Note：请注意 bench 使用的 src 文件需要是生成对应的 xdb 文件的相同的源文件。 +You can test the performance of the three different cache implementations (file/vectorIndex/content) by setting the `cache-policy` parameter. +@Note: Please note that the src file used for the bench must be the same source file used to generate the corresponding xdb file. diff --git a/binding/lua/README_zh.md b/binding/lua/README_zh.md new file mode 100644 index 0000000..b41d6d7 --- /dev/null +++ b/binding/lua/README_zh.md @@ -0,0 +1,225 @@ +:globe_with_meridians: 语言支持: [中文简体](README_zh.md) | [English](README.md) + +# ip2region lua 查询客户端 + +#### 备注：请优先使用 lua_c 扩展 xdb 查询客户端，性能比纯 lua 实现的要快很多！！！ + +# 版本兼容 +该实现兼容 lua `5.3`, `5.4`，且不再提供更低版本的兼容，如果需要在更低版本的 Lua 下使用请考虑使用 `[lua_c](../lua_c/)` 扩展。 + +# 使用方式 + +### 关于查询 API +查询 API 的原型如下： +```lua +-- 通过字符串 IP 查询 +search_by_string(ip_string) (region, error) +-- 通过 parse_ip 返回的 bytes IP 查询 +search(ip_bytes) (region, error) +``` +如果查询出错则会返回非 `nil` 的 error 字符串信息，如果查询成功则会返回字符串的 `region` 信息，如果查询的 IP 地址找不到则会返回空字符串 `""`。 + +### 关于 IPv4 和 IPv6 +```lua +local xdb = require("xdb_searcher") + +-- 如果是 IPv4: 设置 xdb 路径为 v4 的 xdb 文件，IP版本指定为 Version.IPv4 +local dbPath = "../../data/ip2region_v4.xdb" -- 或者你的 ipv4 xdb 的路径 +local version = xdb.IPv4 + +-- 如果是 IPv6: 设置 xdb 路径为 v6 的 xdb 文件，IP版本指定为 Version.IPv6 +local dbPath = "../../data/ip2region_v6.xdb" -- 或者你的 ipv6 xdb 路径 +local version = xdb.IPv6 + +-- dbPath 指定的 xdb 的 IP 版本必须和 version 指定的一致，不然查询执行的时候会报错 +-- 备注：以下演示直接使用 dbPath 和 version 变量 +``` + +### 文件验证 +建议您主动去验证 xdb 文件的适用性，因为后期的一些新功能可能会导致目前的 Searcher 版本无法适用你使用的 xdb 文件，验证可以避免运行过程中的一些不可预测的错误。 你不需要每次都去验证，例如在服务启动的时候，或者手动调用命令验证确认版本匹配即可，不要在每次创建的 Searcher 的时候运行验证，这样会影响查询的响应速度，尤其是高并发的使用场景。 +```lua +local xdb = require('xdb_searcher') + +local err = xdb.verify(dbPath); +if err ~= nil then + -- 适用性验证失败！！！ + -- 当前查询客户端实现不适用于 dbPath 指定的 xdb 文件的查询. + -- 应该停止启动服务，使用合适的 xdb 文件或者升级到适合 dbPath 的 Searcher 实现。 + print(string.format("binding is not applicable for xdb file '%s': %s", dbPath, err)) + return +end + +-- 验证通过，当前使用的 Searcher 可以安全的用于对 dbPath 指向的 xdb 的查询操作 +``` + +### 完全基于文件的查询 +```lua +local xdb = require("xdb_searcher") + +-- 1，使用上述的 version 和 dbPath 创建完全基于文件的查询对象 +local searcher, err = xdb.new_with_file_only(version, db_path) +if err ~= nil then + print(string.format("failed to create searcher: %s", err)) + return +end + +-- 2、调用查询 API 进行查询，IPv4 或者 IPv6 的地址都是同一个接口 +local ip_str = "1.2.3.4" +-- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 +local s_time = xdb.now() +region, err = searcher:search_by_string(ip_str) +if err ~= nil then + print(string.format("failed to search(%s): %s", ip_str, err)) + return +end + +print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) + +-- 3、关闭资源 +searcher:close() + +-- 备注：并发使用，每个协程需要创建单独的 xdb 查询对象 +``` + +### 缓存 `VectorIndex` 索引 + +如果你的 `lua` 母环境支持，可以预先加载 vectorIndex 缓存，然后做成全局变量，每次创建 Searcher 的时候使用全局的 vectorIndex，可以减少一次固定的 IO 操作从而加速查询，减少 io 压力。 +```lua +local xdb = require("xdb_searcher") + +-- 1、从指定的 db_path 加载 vectorIndex 缓存，把下述的 v_index 对象做成全局变量。 +-- vectorIndex 加载一次即可，建议在服务启动的时候加载为全局对象。 +v_index, err = xdb.load_vector_index(dbPath) +if err ~= nil then + print(string.format("failed to load vector index from '%s'", db_path)) + return +end + +-- 2、使用全局的 v_index 创建带 vectorIndex 缓存的查询对象。 +searcher, err = xdb.new_with_vector_index(version, dbPath, v_index) +if err ~= nil then + print(string.format("failed to create vector index searcher: %s", err)) + return +end + +-- 3、调用查询 API，IPv4 或者 IPv6 都是同一个接口 +local ip_str = "1.2.3.4" +-- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 +local s_time = xdb.now() +region, err = searcher:search_by_string(ip_str) +if err ~= nil then + print(string.format("failed to search(%s): %s", ip_str, err)) + return +end + +print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) + +-- 4、关闭资源 +searcher:close() + +-- 备注：并发使用，每个协程需要创建单独的 xdb 查询对象，但是共享全局的 v_index 对象 +``` + +### 缓存整个 `xdb` 文件 + +如果你的 `lua` 母环境支持，可以预先加载整个 xdb 的数据到内存，这样可以实现完全基于内存的查询，类似之前的 memory search 查询。 +```lua +local xdb = require("xdb_searcher") + +-- 1、从上述的 dbPath 加载整个 xdb 到内存。 +-- xdb内容加载一次即可，建议在服务启动的时候加载为全局对象。 +content, err = xdb.load_content(dbPath) +if err ~= nil then + print(string.format("failed to load xdb content: %s", err)) + return +end + +-- 2、使用全局的 content 创建带完全基于内存的查询对象。 +searcher, err = xdb.new_with_buffer(version, content) +if err ~= nil then + print(string.format("failed to create content buffer searcher: %s", err)) + return +end + +-- 3、调用查询 API，IPv4 或者 IPv6 都是同一个接口 +local ip_str = "1.2.3.4" +-- local ip_str = "240e:3b7:3272:d8d0:db09:c067:8d59:539e" -- IPv6 +local s_time = xdb.now() +region, err = searcher:search_by_string(ip_str) +if err ~= nil then + print(string.format("failed to search(%s): %s", ip_str, err)) + return +end + +print(string.format("{region: %s, io_count: %d, took: %.5f μs}", region, searcher:get_io_count(), xdb.now() - s_time)) + +-- 4、关闭资源 - 该 searcher 对象可以安全用于并发，等整个服务关闭的时候再关闭 searcher +-- searcher:close() + +-- 备注：并发使用，用 xdb 整个缓存创建的查询对象可以安全的用于并发。 +-- 建议在服务启动的时候创建好全局的 searcher 对象，然后全局并发使用。 +``` + + +# 查询测试 + +通过 `lua search_test.lua` 脚本来进行查询测试： +```bash +➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua +lua search_test.lua [command options] +options: + --db string ip2region binary xdb file path + --cache-policy string cache policy: file/vectorIndex/content +``` + +例如：使用默认的 data/ip2region_v4.xdb 文件进行 IPv4 的查询测试： +```bash +➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua --db=../../data/ip2region_v4.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex) +type 'quit' to exit +ip2region>> 1.2.3.4 +{region: Australia|Queensland|Brisbane|0|AU, io_count: 5, took: 0μs} +ip2region>> 113.118.113.77 +{region: 中国|广东省|深圳市|电信|CN, io_count: 2, took: 0μs} +``` + +例如：使用默认的 data/ip2region_v6.xdb 文件进行 IPv6 的查询测试： +```bash +➜ lua git:(fr_lua_ipv6) ✗ lua search_test.lua --db=../../data/ip2region_v6.xdb +ip2region xdb searcher test program +source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex) +type 'quit' to exit +ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e +{region: 中国|广东省|深圳市|电信|CN, io_count: 8, took: 0μs} +ip2region>> 2604:a840:3::a04d +{region: United States|California|San Jose|xTom|US, io_count: 13, took: 0μs} +``` + +输入 ip 即可进行查询测试。也可以分别设置 `cache-policy` 为 file/vectorIndex/content 来测试三种不同缓存实现的效率。 + + +# bench 测试 + +通过 `lua bench_test.lua` 脚本来进行自动 bench 测试，一方面确保 `xdb` 文件没有错误，另一方面通过大量的查询测试平均查询性能： +```bash +➜ lua git:(fr_lua_ipv6) ✗ lua bench_test.lua +lua bench_test.lua [command options] +options: + --db string ip2region binary xdb file path + --src string source ip text file path + --cache-policy string cache policy: file/vectorIndex/content +``` + +例如：通过默认的 data/ip2region_v4.xdb 和 data/ipv4_source.txt 文件进行 IPv4 的 bench 测试： +```bash +lua bench_test.lua --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt +``` + +例如：通过默认的 data/ip2region_v6.xdb 和 data/ipv6_source.txt 文件进行 IPv6 的 bench 测试： +```bash +lua bench_test.lua --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt +``` + +可以通过设置 `cache-policy` 参数来分别测试 file/vectorIndex/content 三种不同的缓存实现的的性能。 +@Note：请注意 bench 使用的 src 文件需要是生成对应的 xdb 文件的相同的源文件。 From e92650159169ec85e72840c7197ece0b2242c2cf Mon Sep 17 00:00:00 2001 From: lionsoul2014 Date: Tue, 24 Feb 2026 15:31:22 +0800 Subject: [PATCH 2/3] use the gloabl emoji only --- README.md | 2 +- README_zh.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1c9db4a..e0a2b49 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -:globe_with_meridians: Supported Languages: [中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) # ip2region diff --git a/README_zh.md b/README_zh.md index 3cf84ee..1122f1f 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,4 +1,4 @@ -:globe_with_meridians: 语言支持: [中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) # ip2region From 8302525ae8b8206aadadbb313583819dbfd2ad9f Mon Sep 17 00:00:00 2001 From: lionsoul2014 Date: Tue, 24 Feb 2026 15:34:08 +0800 Subject: [PATCH 3/3] remove the lang label --- binding/lua/README.md | 2 +- binding/lua/README_zh.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/binding/lua/README.md b/binding/lua/README.md index f1e1a2d..b4b19aa 100644 --- a/binding/lua/README.md +++ b/binding/lua/README.md @@ -1,4 +1,4 @@ -:globe_with_meridians: Supported Languages: [中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) # ip2region lua query client diff --git a/binding/lua/README_zh.md b/binding/lua/README_zh.md index b41d6d7..1387ee4 100644 --- a/binding/lua/README_zh.md +++ b/binding/lua/README_zh.md @@ -1,4 +1,4 @@ -:globe_with_meridians: 语言支持: [中文简体](README_zh.md) | [English](README.md) +:globe_with_meridians: [中文简体](README_zh.md) | [English](README.md) # ip2region lua 查询客户端