Repository navigation
ZH Overview
2.1.3 已通过 GitHub 源码／标签和 Maven Central 发布，同 SHA CI 与公开制品核验通过。 当前坐标为 2.1.3；详见 2.1.3 发布说明.
2.1.3 收紧结构化过滤参数校验，在整批预检前归并 IoTDB 物理表名的大小写变体，在测试与 CI 中核对后端登记，拒绝 IoTDB／InfluxDB 3 的重复结果键，并在复制输入前检查直接 adapter 批写的记录数。公开 API、Template → SPI → adapter 主干、Java 17／客户端／服务端基线与配置默认值均保持。 详见 2.1.3 发布说明。
面向 Spring Boot 业务服务的 TSDB 适配模块。当前已经拆分为 core、具体 adapter 和四个独立 starter（含 OpenGemini）。业务侧引入对应 starter
后，通过自动装配获得 TGTemplate，使用带注解的普通 Java POJO 完成时序数据写入、链式查询和原生查询；如果自动装配不满足业务侧要求，也可以只引入对应
adapter 模块后自行配置 Bean。
TsGate 2.1.0 新增 tsgate-opengemini 与 tsgate-opengemini-spring-boot-starter，构建包含四个后端、九个 JAR 模块，2.1.0 BOM 管理这两个新模块。Central 2.0.0 不包含它们。准确的默认引擎版本与拓扑验证范围见 OpenGemini 接入指南。
历史已验证的准确组合见兼容性与验证：
- IoTDB 表模型，默认 SDK 为
iotdb-session:2.0.11。已验证的服务端为 2.0.2（须显式配置tsdb.iotdb.table.rpc-compression-enabled=false）以及 2.0.10 / 2.0.11（两种设置均通过）。精确的 JDK / Boot / SDK 组合与历史结果见兼容指南，未测的中间版本不属于已认证范围。 - InfluxDB 3 Core 3.0.0 / 3.0.3，须显式配置
tsdb.influxdb.strict-cursor-sql=union-all；3.10.0 / 3.11.5 的默认or和显式union-all均通过（influxdb3-java:1.10.0）。该设置影响结构化严格游标续页，准确运行时/策略验证见兼容指南。 - InfluxDB OSS 1.13.1 / InfluxQL（
influxdb-java:2.25） - openGemini 1.4.1 / 1.5.2 默认引擎，使用兼容的 HTTP/InfluxQL（
influxdb-java:2.25），已验证单节点与三节点三副本集群。
这些是具体版本与配置组合的证据，不代表同系列所有版本都已兼容。其他 openGemini 版本和引擎也未验证。InfluxDB 3 Core 3.0.0 / 3.0.3 仍无法执行原有 OR 严格游标形态，已验证支持须显式使用 UNION 策略；原生 SQL 不改写，也不自动降级。Enterprise、Cloud 和 InfluxDB 2.x 不在当前认证范围。
四个后端默认关闭。业务直接在 application.yml 中填写连接参数，并将所需后端的 enable 显式设为 true；无需配置 spring.profiles.active，也无需为其他后端填写 enable: false。省略 enable 或设置为 false 均不启用，即使保留了连接参数。 同一 Spring 上下文最多启用一个后端，多个 true 在客户端初始化前报错。没有启用的后端时不创建 adapter、TGTemplate 或官方客户端 Bean；未引入的 adapter 不参与启用或冲突判断。详见配置说明。
| module | 职责 |
|---|---|
tsgate-core |
公共注解、模型、元数据解析、TGQueryBuilder、TGTemplate 和 TSDBException
|
tsgate-iotdb |
IoTDB 表模型 adapter 核心实现，可由业务侧自行配置使用 |
tsgate-influxdb3 |
InfluxDB 3 Core adapter 核心实现，可由业务侧自行配置使用 |
tsgate-iotdb-spring-boot-starter |
IoTDB adapter 自动装配 |
tsgate-influxdb3-spring-boot-starter |
InfluxDB 3 Core 自动装配 |
tsgate-influxdb1 |
InfluxDB OSS 1.x / InfluxQL adapter |
tsgate-influxdb1-spring-boot-starter |
InfluxDB OSS 1.x 自动装配 |
tsgate-opengemini |
openGemini 默认引擎 InfluxQL adapter；2.1.0 新增 |
tsgate-opengemini-spring-boot-starter |
openGemini 独立自动装配；2.1.0 新增 |
业务入口为 TGTemplate，链式查询使用 TGQueryBuilder<T>；四个 TG* 注解描述 measurement、time、tag 与 field 映射。公共元数据层将其转换为既有的 TSDBRecord / TSDBQuery 模型，再由既有 TSDBAdapter SPI 调用当前启用的后端。当前源码的 Java 包路径为 com.alandevise.tsgate.annotation 与 com.alandevise.tsgate.core。
- 注解 POJO 单条写入和批量写入
- 写入时按
@TGMeasurement、@TGTime、@TGTag、@TGField转换为统一内部记录 - IoTDB 表模型写入按 measurement 组装 Tablet
- InfluxDB 与 openGemini 写入转换为批量 line protocol
- 批量写入在 I/O 前完成全量校验，并通过
BatchWriteResult表达成功、未提交、部分提交或提交状态未知 - 链式查询支持时间范围、tag/field 条件、字段选择、聚合、时间窗口、排序、limit、offset 和分页
- 查询结果映射为业务承接对象，不向业务侧返回内部
QueryResult - 原生查询入口
executeQuery(...) - 自动暴露当前 adapter 对应的原生 client Bean；openGemini 使用兼容的
org.influxdb.InfluxDB，不是 openGemini 专用 SDK - 参数、配置、注解解析、连接和数据库执行错误统一抛出携带六位业务错误码的
TSDBException；底层 TSDB client、HTTP 或数据库异常 保留为原始 cause - adapter 初始化成功后输出
TsGate启动标识、当前构建版本和实际后端类型
启动标识沿用 MINI 字体风格，品牌统一为 TsGate，版本来自构建资源：
___ __
| _/__ _._|_ _
|_>\_|(_| |_(/_
TsGate 2.1.1 · InfluxDB1 initialized
开始使用 →