# xkdb-sdk

**Repository Path**: cym1102/xkdb-sdk

## Basic Information

- **Project Name**: xkdb-sdk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-24
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XKDB SDK

以 `xkdb-java` 为基准的 XKDB v4 读取 SDK。各语言项目独立使用；每个项目都有与 `MainTest.java` 对应的手动测试入口。

| 项目 | 手动入口 | 在对应目录执行 |
| --- | --- | --- |
| C# | `MainTest/Program.cs` | `dotnet run --project MainTest` |
| Go | `cmd/main-test/main.go` | `go run ./cmd/main-test` |
| Lua（LuaJIT） | `main_test.lua` | `luajit main_test.lua` |
| Node.js | `main-test.js` | `node main-test.js` |
| PHP | `main_test.php` | `php main_test.php` |
| Python | `main_test.py` | `python main_test.py` |

先按照对应目录的 README 安装依赖。所有入口默认读取 `d:\xkdb.key`、打开 `d:\ipv4.pay.xkdb`、查询 `117.176.161.141` 并打印 JSON，随后关闭数据库，与 Java 示例一致。也支持依次传入数据库路径、密钥文件路径、IP，最后可加 `--verify`；C# 的应用参数放在 `--` 后。

```text
<手动入口命令> /path/ipv4.pay.xkdb /path/xkdb.key 117.176.161.141 --verify
```

密钥文件必须恰好是 128 个 ASCII 字母或数字，且包含大小写字母和数字；与 Java 一样不会自动去除 BOM、空格或换行。

## 兼容能力

- 160 字节大端头部、32 字节索引、IPv4/IPv6 最长前缀匹配；IPv4-mapped IPv6 按 IPv4 查询。
- SHA-512 密钥派生、128 字符读取密钥中滑动查找 16 字符文件密钥、AES-256-CTR 随机访问解密、HMAC-SHA256 完整性验证。
- 加密原始 JSON（flags=1）、加密 zlib（flags=3）、加密 Zstd 字典（flags=5）；包括训练字典、原始字典、空字典。
- 返回 JSON **字符串**，在原对象前插入 `ip`，保留原字段；无匹配时返回 `{"ip":"...","msg":"未找到该IP信息"}`。
- 普通打开只验证头部、密钥与布局；完整打开/`verifyIntegrity` 额外扫描密文并验证索引顺序、重复项和范围，耗时随文件大小与索引条数增加。

所有版本按需从磁盘读取，不把整个数据库加载到内存。数据库打开期间应保持文件不变。C#、Go 和 Python 支持并发查询；Lua/PHP 实例供所属运行上下文使用；Node.js API 为同步调用。Node.js 和 Lua 仅接受 IP 字面量；其他语言另提供所在运行时的主机名解析，DNS 选择结果可能因系统而异。Node.js/Lua 的文件偏移最大为 `2^53-1`，PHP 要求 64 位运行时。

当前 Java 项目只对外提供读取能力，因此移植项目也提供读取 SDK。

## 兼容性测试

`tests/generate_fixtures.py` 独立生成合成数据库和测试密钥，`tests/check_sdk.py` 对任意手动入口运行同一组协议测试。覆盖压缩、IPv4/IPv6、最长匹配、密钥窗口首尾、格式校验、损坏文件等；不使用实际数据库密钥生成测试文件。

```sh
python -m pip install -r xkdb-python/requirements.txt
python tests/generate_fixtures.py
python tests/check_sdk.py python xkdb-python/main_test.py
python tests/check_sdk.py node xkdb-nodejs/main-test.js
python tests/check_sdk.py php xkdb-php/main_test.php
python tests/check_sdk.py luajit xkdb-lua/main_test.lua
```

Go 和 C# 建议先编译，再把可执行文件（或 `dotnet MainTest.dll`）作为 `check_sdk.py` 的命令参数。`tests/JavaOracle.java` 可与原 Java 源码、`zstd-jni` 一起编译，作为原实现对照；使用 `python tests/check_java.py java -cp <类路径> JavaOracle` 可以在单个 JVM 中批量验证。Windows 下 Java 对照命令应指定 `-Dstdout.encoding=UTF-8`。

首次移植验证使用 Windows x64；各项目的 Linux/macOS 安装方式见各目录 README。原生库名称和路径需要与运行时架构一致。

验证结果见 `tests/VALIDATION.md`。