SpringBoot集成TDengine的完整使用指南

一、什么是 TDengine

先说说几个关键点。TDengine 是一款高性能、分布式时序数据库，专为物联网、工业互联网、金融监控等场景量身打造。它到底有多强？来看看它的核心特性。

• 高性能写入：单表每秒可以达到百万级数据写入，这速度，对于海量设备数据来说，简直不要太爽。
• 高压缩比：时序数据专用压缩算法，让存储空间节省 90% 以上，成本控制这块拿捏得死死的。
• 超级表设计：一次定义数据结构，就能自动为每个设备创建自表，这个设计思路相当巧妙。
• 标签查询：支持按设备类型、位置等维度快速聚合，让数据筛选变得简单直接。
• SQL 语法：采用类 SQL 语法，学习成本低，团队上手非常快。

二、快速开始

那么，我们需要准备什么环境呢？先来看看这张表格，一目了然。

2.1 环境要求

2.2 TDengine 安装

接下来，安装 TDengine。这里给出两种常见方式，一个用于 Linux 环境，另一个是 Docker 部署，强烈推荐后者，省心省力。

Linux 环境

wget https://www.taosdata.com/assets-download/taos/TD-server-2.6.0-Linux-x64-2.0.15.0.tar.gz
tar -xzf TD-server-2.6.0-Linux-x64-2.0.15.0.tar.gz
cd TD-server-2.6.0-Linux-x64-2.0.15.0
sudo ./install.sh

Docker 环境（推荐）

docker run -d --name tdengine -p 6030:6030 tdengine/tdengine:2.6.0

验证安装

taos

三、项目集成步骤

现在来看看如何将 TDengine 集成到 Spring Boot 项目中。

3.1 创建 Spring Boot 项目

你可以使用 Spring Initializr 或者手动创建一个 Ma ven 项目，这都不是问题。

3.2 添加 Ma ven 依赖

在 pom.xml 中添加以下依赖。这里是核心配置，JDBC 驱动和连接池都安排上了。

    4.0.0
    com.example
    tdengine-demo
    1.0.0
    jar
    
        org.springframework.boot
        spring-boot-starter-parent
        2.5.12
    
    
        1.8
        2.0.0
    
    
        
        
            org.springframework.boot
            spring-boot-starter
        
        
        
            org.springframework.boot
            spring-boot-starter-web
        
        
        
            org.springframework.boot
            spring-boot-starter-jdbc
        
        
        
            com.taosdata.jdbc
            taos-jdbcdriver
            ${taos.version}
        
        
        
            com.zaxxer
            HikariCP
        
        
        
            cn.hutool
            hutool-all
            5.7.22
        
        
        
            org.projectlombok
            lombok
            true
        
    
    
        
            
                org.springframework.boot
                spring-boot-ma ven-plugin
            
        
    

3.3 配置文件

接下来是 application.yml 配置文件。数据源、连接池、日志级别，一次搞定。

src/main/resources/application.yml

server:
  port: 8080
spring:
  application:
    name: tdengine-demo
# TDengine 数据源配置
taos:
  datasource:
    type: com.zaxxer.hikari.HikariDataSource
    driver-class-name: com.taosdata.jdbc.TSDBDriver
    url: jdbc:TAOS://localhost:6030/iot
    username: root
    password: taosdata
    # 连接池配置
    minimum-idle: 5
    maximum-pool-size: 20
    connection-timeout: 30000
    idle-timeout: 600000
    max-lifetime: 1800000
# SQL 执行日志 (开发环境开启)
logging:
  level:
    com.taosdata.jdbc: debug
    com.example.taos: trace

四、自定义注解实现

为了让代码更优雅、更可配置，我们引入了一些自定义注解。这就是框架设计的美妙之处——用注解来完成元数据映射，把复杂的事情简单化。

4.1 @STable - 超级表注解

这个注解用来标记实体类与 TDengine 超级表的映射关系。你可以看到，它支持子表名模板，比如 t_${deviceId}，动态解析，非常灵活。

src/main/ja va/com/example/taos/annotation/STable.ja va

package com.example.taos.annotation;

import ja va.lang.annotation.ElementType;
import ja va.lang.annotation.Retention;
import ja va.lang.annotation.RetentionPolicy;
import ja va.lang.annotation.Target;

/**
 * 超级表注解
 * 用于标记 TDengine 的超级表和数据表映射关系
 * 
 * 使用示例:
 * @STable(
 *     value = "meters",           // 超级表名
 *     table = "t_${deviceId}",    // 子表名模板
 *     using = true                // 启用自动创建子表
 * )
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.TYPE})
public @interface STable {

    /**
     * 超级表表名
     * @return 超级表名称，如果不使用超级表则返回空字符串
     */
    String value() default "";

    /**
     * 数据表表名
     * 支持使用 ${} 占位符动态生成表名
     * 示例：数据表名 = "t_${deviceId}" → 实际表名：t_device001, t_device002
     * @return 数据表名称模板
     */
    String table();

    /**
     * 是否自动创建数据表
     * true: 如果数据表不存在，插入时自动创建
     * false: 数据表必须预先创建好
     * @return 是否启用自动创建
     */
    boolean using() default false;
}

4.2 @IotTableId - 时间戳字段注解

每个时序数据表都少不了一个时间戳字段。这个注解就是用来标记那个字段的，而且强制要求一个实体类只能有一个。

src/main/ja va/com/example/taos/annotation/IotTableId.ja va

package com.example.taos.annotation;

import ja va.lang.annotation.ElementType;
import ja va.lang.annotation.Retention;
import ja va.lang.annotation.RetentionPolicy;
import ja va.lang.annotation.Target;

/**
 * 时间戳字段注解
 * 用于标记 TDengine 表的主键时间字段
 * 
 * 使用要求:
 * - 字段类型必须是 Date、Long 或 Timestamp
 * - 每个实体类必须有且仅有一个 @IotTableId 字段
 * 
 * 使用示例:
 * @IotTableId
 * private Date ts;
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface IotTableId {

    /**
     * 字段名称 (默认使用实体字段名)
     * @return 表字段名
     */
    String value() default "";
}

4.3 @IotField - 普通数据字段注解

数据字段都交给它。它支持自定义字段名、数据库字段类型，以及小数位数的设置，灵活性相当高。

src/main/ja va/com/example/taos/annotation/IotField.ja va

package com.example.taos.annotation;

import ja va.lang.annotation.ElementType;
import ja va.lang.annotation.Retention;
import ja va.lang.annotation.RetentionPolicy;
import ja va.lang.annotation.Target;
import ja va.sql.Types;

/**
 * 普通数据字段注解
 * 用于标记 TDengine 表的数据列
 * 
 * 使用示例:
 * @IotField("voltage")
 * private Double voltage;
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface IotField {

    /**
     * 表字段名 (默认使用实体字段名)
     * @return 字段名
     */
    String value() default "";

    /**
     * 表字段类型 (默认使用实体字段类型)
     * @see ja va.sql.Types
     * @return 字段类型
     */
    int type() default Types.NULL;

    /**
     * 保留小数位数 (针对浮点数)
     * -1 表示不处理
     * @return 小数位数
     */
    int scale() default -1;
}

4.4 @IotTag - 标签字段注解

TDengine 的超级表有一个特色功能就是 Tag。它用来存储设备的维度信息，比如设备ID、位置、类型等，是进行高效聚合查询的关键。

src/main/ja va/com/example/taos/annotation/IotTag.ja va

package com.example.taos.annotation;

import ja va.lang.annotation.ElementType;
import ja va.lang.annotation.Retention;
import ja va.lang.annotation.RetentionPolicy;
import ja va.lang.annotation.Target;
import ja va.sql.Types;

/**
 * 标签字段注解
 * 用于标记 TDengine 超级表的 TAG 列
 * TAG 是 TDengine 的特色，用于设备维度查询
 * 
 * 使用示例:
 * @IotTag("device_id")
 * private String deviceId;
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
public @interface IotTag {

    /**
     * 标签名称 (默认使用实体字段名)
     * @return 标签名
     */
    String value() default "";

    /**
     * 标签字段类型 (默认使用实体字段类型)
     * @see ja va.sql.Types
     * @return 字段类型
     */
    int type() default Types.NULL;
}

五、核心工具类实现

好，注解看完了，核心工具类来了。有了这些类，元数据解析、SQL 生成、表名解析，一切都变得井井有条。

5.1 字段元数据类

这个类封装了实体字段和数据库列的映射信息。它负责把 Ja va 反射的 Field 变成一个更易于管理的元数据对象。

src/main/ja va/com/example/taos/sql/FieldMeta.ja va

package com.example.taos.sql;

import ja va.lang.reflect.Field;

/**
 * 字段元数据
 * 封装实体类字段的映射信息
 */
public class FieldMeta {

    /** 字段名 */
    private String fieldName;

    /** 字段类型 (Ja va 类型) */
    private String fieldType;

    /** 数据库字段名 */
    private String columnName;

    /** 数据库字段类型 */
    private int columnType;

    /** 反射字段对象 */
    private Field field;

    /** 小数位数 */
    private int scale = -1;

    public FieldMeta() {
    }

    public FieldMeta(Field field) {
        this.field = field;
        this.fieldName = field.getName();
        this.fieldType = field.getType().getSimpleName();
        this.columnName = field.getName();
        field.setAccessible(true);
    }

    // Getter 和 Setter
    public String getFieldName() {
        return fieldName;
    }

    public void setFieldName(String fieldName) {
        this.fieldName = fieldName;
    }

    public String getFieldType() {
        return fieldType;
    }

    public void setFieldType(String fieldType) {
        this.fieldType = fieldType;
    }

    public String getColumnName() {
        return columnName;
    }

    public void setColumnName(String columnName) {
        this.columnName = columnName;
    }

    public int getColumnType() {
        return columnType;
    }

    public void setColumnType(int columnType) {
        this.columnType = columnType;
    }

    public Field getField() {
        return field;
    }

    public void setField(Field field) {
        this.field = field;
    }

    public int getScale() {
        return scale;
    }

    public void setScale(int scale) {
        this.scale = scale;
    }

    /**
     * 获取字段值
     */
    public Object getFieldValue(Object entity) throws IllegalAccessException {
        return field.get(entity);
    }
}

5.2 表元数据类

这个类封装了完整的表结构映射信息，包括超级表名、子表名模板、字段列表和标签列表。它放了一堆生成 SQL 的方法，很实用。

src/main/ja va/com/example/taos/sql/TaosTableMeta.ja va

package com.example.taos.sql;

import ja va.util.ArrayList;
import ja va.util.List;

/**
 * TDengine 表元数据
 * 封装超级表、数据表、字段的完整映射信息
 */
public class TaosTableMeta {

    /** 超级表名 */
    private String stableName;

    /** 数据表名模板 */
    private String tableNameTemplate;

    /** 是否自动创建数据表 */
    private boolean using;

    /** 时间戳字段 */
    private FieldMeta timeField;

    /** 数据字段列表 */
    private List dataFields = new ArrayList<>();

    /** 标签字段列表 */
    private List tagFields = new ArrayList<>();

    // Getter 和 Setter
    public String getStableName() {
        return stableName;
    }

    public void setStableName(String stableName) {
        this.stableName = stableName;
    }

    public String getTableNameTemplate() {
        return tableNameTemplate;
    }

    public void setTableNameTemplate(String tableNameTemplate) {
        this.tableNameTemplate = tableNameTemplate;
    }

    public boolean isUsing() {
        return using;
    }

    public void setUsing(boolean using) {
        this.using = using;
    }

    public FieldMeta getTimeField() {
        return timeField;
    }

    public void setTimeField(FieldMeta timeField) {
        this.timeField = timeField;
    }

    public List getDataFields() {
        return dataFields;
    }

    public void setDataFields(List dataFields) {
        this.dataFields = dataFields;
    }

    public List getTagFields() {
        return tagFields;
    }

    public void setTagFields(List tagFields) {
        this.tagFields = tagFields;
    }

    /**
     * 生成 INSERT SQL 语句
     */
    public String generateInsertSql() {
        StringBuilder sb = new StringBuilder();
        sb.append("(");
        
        // 时间戳字段
        sb.append(timeField.getColumnName());
        
        // 数据字段
        for (FieldMeta field : dataFields) {
            sb.append(", ").append(field.getColumnName());
        }
        
        sb.append(")");
        return sb.toString();
    }

    /**
     * 生成参数占位符 SQL
     */
    public String generateParamSql() {
        StringBuilder sb = new StringBuilder();
        sb.append("(");
        sb.append("?");
        
        int totalFields = 1 + dataFields.size();
        for (int i = 1; i < totalFields; i++) {
            sb.append(", ?");
        }
        
        sb.append(")");
        return sb.toString();
    }

    /**
     * 生成超级表 USING 子句
     */
    public String generateUsingClause() {
        if (stableName == null || stableName.isEmpty()) {
            return null;
        }

        StringBuilder sb = new StringBuilder();
        sb.append("USING ").append(stableName);
        
        if (!tagFields.isEmpty()) {
            sb.append(" (");
            for (int i = 0; i < tagFields.size(); i++) {
                if (i > 0) sb.append(", ");
                sb.append(tagFields.get(i).getColumnName());
            }
            sb.append(")");
        }

        return sb.toString();
    }

    /**
     * 生成 TAG 值列表
     */
    public String generateTagValues() {
        if (tagFields.isEmpty()) {
            return null;
        }

        StringBuilder sb = new StringBuilder();
        sb.append("(");
        
        for (int i = 0; i < tagFields.size(); i++) {
            if (i > 0) sb.append(", ");
            sb.append("?");
        }
        
        sb.append(")");
        return sb.toString();
    }

    /**
     * 获取总字段数
     */
    public int getTotalFields() {
        return 1 + dataFields.size(); // 时间戳 + 数据字段
    }
}

5.3 SQL 执行上下文

一个轻量级的封装，将 SQL 语句和参数打包在一起，方便传递和执行。

src/main/ja va/com/example/taos/sql/SqlExecContext.ja va

package com.example.taos.sql;

/**
 * SQL 执行上下文
 * 封装要执行的 SQL 语句和参数
 */
public class SqlExecContext {

    /** SQL 语句 */
    private String sql;

    /** 参数值数组 */
    private Object[] params;

    public SqlExecContext(String sql, Object[] params) {
        this.sql = sql;
        this.params = params;
    }

    public String getSql() {
        return sql;
    }

    public void setSql(String sql) {
        this.sql = sql;
    }

    public Object[] getParams() {
        return params;
    }

    public void setParams(Object[] params) {
        this.params = params;
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        sb.append("SQL: ").append(sql).append("n");
        sb.append("Params: ");
        if (params != null) {
            for (Object param : params) {
                sb.append(param).append(", ");
            }
        }
        return sb.toString();
    }
}

5.4 元数据解析器

这才是重头戏。它负责扫描实体类上的注解，解析出结构化的元数据。它还引入了缓存，避免重复解析开销。

src/main/ja va/com/example/taos/sql/TaosMetaExtractor.ja va

package com.example.taos.annotation;
import com.example.taos.sql.FieldMeta;
import com.example.taos.sql.TaosTableMeta;

import ja va.lang.reflect.Field;
import ja va.sql.Date;
import ja va.sql.Types;
import ja va.util.Map;
import ja va.util.concurrent.ConcurrentHashMap;

/**
 * TDengine 元数据解析器
 * 从实体类注解中提取表结构信息
 */
public class TaosMetaExtractor {

    /** 元数据缓存 */
    private static final Map, TaosTableMeta> META_CACHE = new ConcurrentHashMap<>();

    /**
     * 解析实体类的表元数据
     */
    public static TaosTableMeta parse(Class entityClass) {
        return META_CACHE.computeIfAbsent(entityClass, TaosMetaExtractor::doParse);
    }

    /**
     * 清空缓存
     */
    public static void clearCache() {
        META_CACHE.clear();
    }

    private static TaosTableMeta doParse(Class entityClass) {
        STable sTable = entityClass.getAnnotation(STable.class);
        if (sTable == null) {
            throw new IllegalArgumentException(
                "实体类必须使用 @STable 注解：" + entityClass.getName()
            );
        }

        TaosTableMeta meta = new TaosTableMeta();
        meta.setStableName(sTable.value());
        meta.setTableNameTemplate(sTable.table());
        meta.setUsing(sTable.using());

        // 解析字段
        FieldMeta timeField = null;

        for (Field field : entityClass.getDeclaredFields()) {
            field.setAccessible(true);

            if (field.isAnnotationPresent(IotTableId.class)) {
                // 时间戳字段
                if (timeField != null) {
                    throw new IllegalArgumentException(
                        "实体类只能有一个 @IotTableId 字段：" + entityClass.getName()
                    );
                }
                timeField = parseField(field, Types.TIMESTAMP);

                // 验证类型
                Class fieldType = field.getType();
                if (!Date.class.isAssignableFrom(fieldType) 
                    && !Long.class.isAssignableFrom(fieldType) 
                    && field.getType() != long.class) {
                    throw new IllegalArgumentException(
                        "@IotTableId 字段必须是 Date 或 Long 类型：" + field.getName()
                    );
                }

            } else if (field.isAnnotationPresent(IotField.class)) {
                // 普通数据字段
                IotField annotation = field.getAnnotation(IotField.class);
                FieldMeta fieldMeta = parseField(field, annotation.type());
                
                // 自定义字段名
                if (!annotation.value().isEmpty()) {
                    fieldMeta.setColumnName(annotation.value());
                }
                
                // 小数位数
                if (annotation.scale() >= 0) {
                    fieldMeta.setScale(annotation.scale());
                }
                
                meta.getDataFields().add(fieldMeta);

            } else if (field.isAnnotationPresent(IotTag.class)) {
                // 标签字段
                IotTag annotation = field.getAnnotation(IotTag.class);
                FieldMeta fieldMeta = parseField(field, annotation.type());
                
                // 自定义标签名
                if (!annotation.value().isEmpty()) {
                    fieldMeta.setColumnName(annotation.value());
                }
                
                meta.getTagFields().add(fieldMeta);
            }
        }

        if (timeField == null) {
            throw new IllegalArgumentException(
                "实体类必须有且仅有一个 @IotTableId 字段：" + entityClass.getName()
            );
        }

        meta.setTimeField(timeField);
        return meta;
    }

    private static FieldMeta parseField(Field field, int columnType) {
        FieldMeta meta = new FieldMeta(field);
        
        // 根据 Ja va 类型推断数据库类型
        if (columnType == Types.NULL) {
            columnType = inferSqlType(field.getType());
        }
        meta.setColumnType(columnType);
        
        return meta;
    }

    /**
     * 根据 Ja va 类型推断 SQL 类型
     */
    private static int inferSqlType(Class type) {
        if (type == String.class) {
            return Types.VARCHAR;
        } else if (type == Integer.class || type == int.class) {
            return Types.INTEGER;
        } else if (type == Long.class || type == long.class) {
            return Types.BIGINT;
        } else if (type == Double.class || type == double.class) {
            return Types.DOUBLE;
        } else if (type == Float.class || type == float.class) {
            return Types.FLOAT;
        } else if (type == Boolean.class || type == boolean.class) {
            return Types.BOOLEAN;
        } else if (ja va.util.Date.class.isAssignableFrom(type) 
                || ja va.sql.Date.class.isAssignableFrom(type)
                || ja va.sql.Timestamp.class.isAssignableFrom(type)) {
            return Types.TIMESTAMP;
        } else {
            return Types.VARCHAR;
        }
    }
}

5.5 动态表名解析器

当表名里包含 ${fieldName} 这样的占位符时，就需要这个解析器来干活了。它负责从实体对象中提取对应字段的值，替换占位符，生成真实的子表名。

src/main/ja va/com/example/taos/sql/TableNameResolver.ja va

package com.example.taos.sql;

import ja va.lang.reflect.Field;
import ja va.util.regex.Matcher;
import ja va.util.regex.Pattern;

/**
 * 动态表名解析器
 * 解析表名模板中的 ${fieldName} 占位符
 */
public class TableNameResolver {

    private static final Pattern PLACEHOLDER_PATTERN = Pattern.compile("\$\{([^}]+)\}");

    /**
     * 解析表名
     * 示例：tableTemplate = "t_${deviceId}", entity.deviceId = "device001"
     *      返回："t_device001"
     */
    public static String resolve(String tableTemplate, Object entity) {
        if (tableTemplate == null || tableTemplate.isEmpty()) {
            throw new IllegalArgumentException("表名模板不能为空");
        }

        Matcher matcher = PLACEHOLDER_PATTERN.matcher(tableTemplate);
        String tableName = tableTemplate;

        while (matcher.find()) {
            String fieldName = matcher.group(1);
            String fieldValue = getFieldValue(entity, fieldName);
            
            if (fieldValue == null) {
                throw new IllegalArgumentException(
                    "解析表名失败，字段 [" + fieldName + "] 的值为 null"
                );
            }

            tableName = tableName.replace("${" + fieldName + "}", fieldValue);
        }

        return tableName;
    }

    /**
     * 获取字段值
     */
    private static String getFieldValue(Object entity, String fieldName) {
        try {
            Field field = entity.getClass().getDeclaredField(fieldName);
            field.setAccessible(true);
            Object value = field.get(entity);
            return value != null ? value.toString() : null;
        } catch (NoSuchFieldException | IllegalAccessException e) {
            throw new IllegalArgumentException(
                "无法获取字段值：" + fieldName, e
            );
        }
    }
}

六、数据访问层实现

底层工具类准备就绪，数据访问层就可以直接上手了。

6.1 数据源配置类

Spring Boot 项目，数据源配置是第一步。这个类把配置文件中 taos.datasource 前缀的属性绑定到 HikariCP 连接池。

src/main/ja va/com/example/taos/config/TaosConfig.ja va

package com.example.taos.config;

import com.zaxxer.hikari.HikariDataSource;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import ja vax.sql.DataSource;

/**
 * TDengine 数据源配置
 */
@Configuration
public class TaosConfig {

    /**
     * 创建 TDengine 数据源
     */
    @Bean("taosDataSource")
    @ConfigurationProperties(prefix = "taos.datasource")
    public DataSource taosDataSource() {
        return new HikariDataSource();
    }
}

6.2 TDengine 操作接口

定义一个 Repository 接口，先约定好数据访问的方法。

src/main/ja va/com/example/taos/repository/TaosRepository.ja va

package com.example.taos.repository;

import ja va.util.List;

/**
 * TDengine 数据访问接口
 */
public interface TaosRepository {

    /**
     * 插入单条数据
     * @param entity 实体对象
     * @return 影响的行数
     */
    int insert(Object entity);

    /**
     * 批量插入数据
     * @param entities 实体对象列表
     * @return 影响的行数
     */
    int batchInsert(List