ZH Release Notes 2.1.3

Home · English | 简体中文

TsGate 2.1.3 发布说明

2.1.3 已通过 GitHub 源码／标签和 Maven Central 发布，同 SHA CI 与公开制品核验通过。

2.1.3 收紧结构化过滤参数校验，在整批预检前归并 IoTDB 物理表名的大小写变体，在测试与 CI 中核对后端登记，拒绝 IoTDB／InfluxDB 3 的重复结果键，并在复制输入前检查直接 adapter 批写的记录数。公开 API、Template → SPI → adapter 主干、Java 17／客户端／服务端基线与配置默认值均保持。

本补丁的修改

1. 结构化过滤与默认 count 保护。 比较运算恰好一个操作数，BETWEEN 两个，IN 至少一个。列名缺失／空白、运算符缺失、null 操作数、Float／Double 非有限值均在数据库 I/O 前返回 ARGUMENT_ERROR。链式可选输入清理保持；query／count 校验实际保留的条件。count 仍在私有副本中忽略分页／游标，公共 SPI 默认 count(null) 返回 ARGUMENT_ERROR。
2. IoTDB 物理表归并。 按 Locale.ROOT 小写物理表身份归并表名后，执行整批列角色／类型校验。兼容大小写变体共同构造 Tablet，保留同表行序及调用方记录／map。冲突变体以 METADATA_ERROR、NOT_COMMITTED 拒绝完整应用批次，I/O 为零。已定位的失败表返回小写物理名；尚未定位的预检／获取连接失败仍可为 null。不增加跨 Tablet 事务。
3. 后端登记完整性。 测试专用清单与可移植检查器交叉核对 reactor 模块、adapter 启用、starter／imports、BOM、共享契约、必需 Docker／CI 执行及发行制品清单。缺失必需关联时拒绝通过；公共运行器与 CI 执行门禁。生产启用逻辑与 SPI 不变，各后端只需覆盖其声明的部署拓扑。
4. 重复结果解码。 IoTDB 在读取结果行前拒绝 SDK 输出列名的精确重复，空结果重复元数据也报错。InfluxDB 3 拒绝成功查询响应中同一 JSON 对象的精确重复键，包括前值 null、后续行重复。整次 query、count、adapter executeQuery 返回 QUERY_ERROR，不发布部分行或伪造成功计数，沿用资源清理。大小写不同名称、跨行同名、合法 null、数值精度保持。原生 SQL 不改写，服务端可能先拒绝有歧义 alias；借用原生客户端不经过适配器解码。InfluxDB 1.x／openGemini 保留原有重复列及 tag／field 冲突检查，不扩大为任意 JSON 元数据键严格校验，也不收紧 DTO 宽松匹配。
5. 直接 adapter 批写数量提前检查。 四后端在生命周期／null／空批次检查后、List.copyOf 前检查非空集合报告大小，复制后再次复核，随后才逐条校验或编码。明显超限时返回 ARGUMENT_ERROR、NOT_COMMITTED，已校验／已提交记录、物理批次及 I/O 均为零，不调用集合的迭代／复制方法。TGTemplate 原本已有保护；null／空批次和既有数量限额／默认值保持。任意自定义或并发修改集合仍无内存硬上限／原子性保证。

升级影响

升级前检查动态拼接的过滤条件：比较运算必须恰好一个操作数，BETWEEN 两个，IN 至少一个。直接模型中的 null 操作数、Float／Double 非有限值现在会在 I/O 前返回 ARGUMENT_ERROR。链式 builder 的可选输入清理保持；文字字符串 "null" 仍是普通字符串。count 在私有副本中忽略分页／游标，SPI 默认 count(null) 返回 ARGUMENT_ERROR。

IoTDB 在整批列角色／类型检查前，按 Locale.ROOT 小写物理表身份归并表名。冲突的大小写变体在借用 session 前以 METADATA_ERROR／NOT_COMMITTED 拒绝；兼容变体保留同表行序及既有 Tablet 拆分。原生查询应使用唯一输出 alias：SDK 输出列名或 InfluxDB 3 JSON 对象键精确重复时，整次 query／count／executeQuery 返回 QUERY_ERROR。大小写不同结果键及既有宽松 DTO 映射保持。

直接 adapter 的 batchWriteDetailed／batchWrite 在复制或遍历记录前拒绝报告大小明显超限的集合，复制后再次复核。生命周期检查仍优先，ready 状态的 null／空批次仍成功。超限返回 ARGUMENT_ERROR／NOT_COMMITTED，数据库 I/O 为零。业务应主动拆批，或评估后调整既有正数 max-batch-records；本次不新增资源预算配置，也不承诺任意自定义集合的内存硬上限。

从 Central 2.1.0 升级的用户也会获得此前仅通过 GitHub 发布的 2.1.1／2.1.2 修复：数值游标边界、IoTDB 列身份、HTTP 重定向写入确认、InfluxDB 3 缺失 JSON 报错、聚合输出名检查、可配置的 64 MiB HTTP 整批预算，以及 POJO 读计划缓存。这些是继承的修改，不是 2.1.3 首次新增。请同时阅读 2.1.1 说明 与 2.1.2 说明，包括最终 HTTP 入口配置及显式拆批要求。

公开 API、配置默认值、依赖基线及主干架构保持不变。已有资源限制及 BOM 验证保留已说明的范围。

验证证据

冻结实现已通过本地预发布验证：JDK 17／21／25 各 1,476 项单元检查、323 项 Docker 集成检查及 83 项 Python 检查，失败／错误／跳过均为零，自有资源清理通过。发布准备前已核对 166 项源码输入清单及实现差异。这是此前本地预发布结果，不是新执行的 2.1.3 JDK 21／25 或 Docker 回归。

最终源码 18fccb6 与标签 v2.1.3 已推送；该源码 fresh 签名 Temurin 17 构建通过 1,476 项单元检查。九个 JAR 模块的 27 JAR／11 POM 审计、38 份有效签名及 228 个签名上传包条目均通过，凭据扫描通过。上传包 SHA-256：e192aec3177c6cb5ab2dd9cd4d6a61b31a6c8c2f01e7a0f921d599d90612bb3f。同 SHA 标签 CI 9 个作业全部通过，覆盖 JDK 17／21／25 各 1,476 项单元检查及 323 项 Docker 集成检查。Central 已进入 PUBLISHED；从公共 Maven 仓库下载的 38 份主体制品及 38 份公开签名，SHA-256 均与签名上传包一致。

本地预发布运行时	单元检查数
Temurin 17.0.14／Spring Boot 2.7.18	1,476
JDK 21.0.11／Spring Boot 3.5.14	1,476
JDK 25.0.2／Spring Boot 4.1.0	1,476

本地 Docker 覆盖 IoTDB 2.0.10（49 项）、InfluxDB OSS 1.13.1（27 项）、InfluxDB 3 Core 3.11.5（55 项），以及 openGemini 1.4.1／1.5.2 默认引擎各自单节点和三节点三副本（每部署 48 项、合计 192 项），总计 323 项 Docker 检查。11 个自有容器与 4 个网络均已删除。83 项 Python 检查覆盖运行器／登记／夹具。这些代表版本不重新认证全部历史支持组合，旧版本证据仍按原范围保留。

发布验证通过： 最终源码的 Java 17 签名打包、同 SHA 标签 CI 完整矩阵、Central 发布及公开制品／签名哈希核对均完成。上方此前本地预发布结果仍保留独立源码范围。

用户管理的 Central 部署 666534d2-2358-486c-bc96-0446619a3e12 已进入 PUBLISHED。38 份主体制品及 38 份对应的公开签名均与签名上传包一致。

分发

坐标为 io.github.alandevise:*:2.1.3，包含 tsgate-bom 及四个 starter；TsGate 模块与 BOM 必须保持版本一致。2.1.3 已可从 Maven Central 解析；仍可选择匹配源码本地安装。当前状态见测试与发布，开始使用提供 2.1.3 示例。历史 2.1.0、2.1.1、2.1.2 发布说明保留原始证据。