Spring Boot 与 TDengine 的深度集成实践（一）

引言

在当今数字化时代，数据处理与存储对于各类应用的重要性不言而喻。Spring Boot 作为一款流行的 Java 开发框架，以其快速开发、约定大于配置、内嵌容器等特性，大大提升了 Java 企业级应用的开发效率，降低了开发门槛，让开发者能够专注于业务逻辑的实现，广泛应用于各种 Web 应用、微服务架构等项目中。

TDengine 则是一款高性能、云原生的时序数据库，专门针对物联网、工业互联网、运维监控等场景进行优化。它具备卓越的写入性能，能够支持每秒数百万条数据的写入，同时拥有高效的数据压缩算法，有效降低了存储成本，其独特的超级表设计和灵活的查询语法，也使得对时序数据的处理变得更加便捷和高效。

将 Spring Boot 与 TDengine 集成，能够充分发挥两者的优势，为需要处理大量时序数据的应用提供强大的技术支持。在物联网场景中，大量传感器设备不断产生海量的时序数据，通过集成 Spring Boot 与 TDengine，可以实现对这些数据的快速采集、存储和分析，为实时监控、设备状态预测等业务提供有力支撑；在工业互联网领域，生产线上的各种设备运行数据同样需要高效处理，这种集成方案能够满足对设备运行状态实时监测和故障预警的需求，保障生产的稳定运行。

环境准备

在开始集成 Spring Boot 与 TDengine 之前，我们需要先准备好开发环境，确保相关软件和工具都已正确安装和配置。

安装 Java

Java 是 Spring Boot 开发的基础，因此我们首先需要安装 Java Development Kit（JDK）。目前，Java 有多个版本可供选择，建议使用长期支持（LTS）版本，以确保稳定性和安全性，比如 JDK 11 或 JDK 17 。你可以从 Oracle 官方网站或 OpenJDK 项目官网下载适合你操作系统的 JDK 安装包。

以 Windows 系统为例，安装步骤如下：

1. 下载 JDK 安装包后，双击运行安装程序，按照安装向导的提示进行操作。在安装过程中，可以选择自定义安装路径，建议将 JDK 安装在一个全英文且路径层级较浅的目录下，例如C:\Program Files\Java\jdk-11.0.11，以避免因路径问题导致的潜在错误。

1. 安装完成后，需要配置环境变量。右键点击 “此电脑”，选择 “属性”，在弹出的窗口中点击 “高级系统设置”，然后在 “系统属性” 窗口中点击 “环境变量” 按钮。在 “系统变量” 区域中，新建一个变量名为JAVA_HOME，变量值为 JDK 的安装路径，例如C:\Program Files\Java\jdk-11.0.11。接着，找到Path变量，点击 “编辑”，在弹出的窗口中点击 “新建”，添加%JAVA_HOME%\bin和%JAVA_HOME%\jre\bin两个路径，这两个路径分别指向 JDK 的二进制文件目录和 Java 运行时环境的二进制文件目录，确保系统能够找到 Java 相关的可执行文件 。

1. 配置完成后，打开命令提示符（CMD），输入java -version命令，如果显示出 Java 的版本信息，则说明 JDK 安装和环境变量配置成功。

安装 Maven

Maven 是一个项目管理和构建工具，它可以帮助我们自动化构建项目、管理项目依赖等。安装 Maven 的步骤如下：

1. 从 Maven 官方网站（https://maven.apache.org/download.cgi）下载最新版本的 Maven 二进制包，选择与你操作系统相应的版本进行下载，通常选择下载 Binary zip archive 版本 。

1. 下载完成后，将 Maven 压缩包解压到你希望安装的目录，例如D:\maven\apache-maven-3.8.6 。

1. 配置环境变量。与配置 JDK 环境变量类似，在 “系统变量” 中新建一个变量名为MAVEN_HOME，变量值为 Maven 的解压路径，例如D:\maven\apache-maven-3.8.6。然后，编辑Path变量，添加%MAVEN_HOME%\bin路径，这样系统就可以找到 Maven 的命令行工具。

1. 验证 Maven 安装是否成功。打开命令提示符，输入mvn -v命令，如果显示出 Maven 的版本信息，则说明安装成功。

此外，为了提高依赖下载速度，我们可以配置 Maven 的本地仓库和镜像。在 Maven 的安装目录下，找到conf文件夹中的settings.xml文件，进行如下配置：

1. 配置本地仓库：在settings.xml文件中找到<localRepository>标签，如果该标签不存在，则在<settings>标签内添加如下内容，将本地仓库路径设置为你希望的目录，例如D:\maven\repository：

<localRepository>D:\maven\repository</localRepository>

1. 配置镜像：在国内，直接连接中央仓库下载依赖可能速度较慢，我们可以使用阿里云的镜像来加速下载。在settings.xml文件中找到<mirrors>标签，在其中添加以下镜像配置：

<mirror>

<id>nexus-aliyun</id>

<mirrorOf>central</mirrorOf>

<name>Nexus aliyun</name>

<url>http://maven.aliyun.com/nexus/content/groups/public</url>

</mirror>

安装 TDengine

TDengine 的安装过程因操作系统而异，这里以 Linux 系统（CentOS 7 为例）安装 TDengine 的 Server 端为例进行介绍 ：

1. 从 TDengine 官方网站（https://www.taosdata.com/cn/getting-started/）下载适合你操作系统和硬件架构的安装包，TDengine 提供了 rpm、deb、tar.gz 等多种格式的安装包，这里我们选择 tar.gz 格式的安装包，例如TDengine-server-3.0.4.0-Linux-x64.tar.gz 。

1. 将下载的安装包上传到 Linux 服务器的指定目录，例如/usr/local/tdengine 。

1. 解压安装包。使用以下命令解压：

tar -zxvf TDengine-server-3.0.4.0-Linux-x64.tar.gz

解压后会得到一个TDengine-server的文件夹。4. 进入解压后的文件夹，执行安装脚本。使用以下命令：

cd TDengine-server

sudo ./install.sh

在安装过程中，会提示你是否加入已有的集群，如果是首次安装，直接回车跳过即可。安装完成后，会提示相关的配置和启动信息 。5. 配置 TDengine。TDengine 的配置文件位于/etc/taos/taos.cfg，你可以根据实际需求修改其中的配置参数，例如数据存储路径、日志存储路径等 。6. 启动 TDengine。使用以下命令启动服务：

sudo systemctl start taosd

可以使用以下命令检查服务状态：

sudo systemctl status taosd

如果服务状态显示为active (running)，则说明 TDengine 安装和启动成功。

安装完成后，你可以使用 TDengine 提供的命令行工具taos来测试数据库的连接和基本操作。例如，输入taos命令进入 TDengine 的命令行界面，然后可以执行创建数据库、表，插入数据等操作 。

通过以上步骤，我们完成了 Java、Maven 和 TDengine 的安装和基本配置，为后续的 Spring Boot 与 TDengine 集成开发做好了准备。

创建 Spring Boot 项目

使用 Spring Initializr 创建项目

Spring Initializr 是 Spring Boot 官方提供的一个快速创建 Spring Boot 项目的工具，它可以帮助我们快速生成项目的基础结构，并自动添加所需的依赖。我们可以通过 Web 界面、IDE 插件或命令行等方式使用它，这里我们以 Web 界面方式为例进行创建。

1. 打开浏览器，访问 Spring Initializr 网站：https://start.spring.io/ 。该网站提供了简洁直观的界面，方便我们进行项目配置。

1. 在页面中进行项目配置：

• • Project：选择项目构建工具，这里我们选择 “Maven Project”，Maven 是一个广泛使用的项目管理和构建工具，它通过 pom.xml 文件来管理项目的依赖和构建过程，能够帮助我们自动化编译、测试、打包等操作 。

• • Language：选择编程语言，这里我们选择 “Java”，Java 作为一种成熟且广泛应用的编程语言，具有跨平台、面向对象、安全性高等特点，非常适合企业级应用开发。

• • Spring Boot：选择 Spring Boot 版本，这里我们选择最新的稳定版本，比如 “3.2.0”，新版本通常会带来性能优化、功能增强以及安全修复等优势 。

• • Project Metadata：

• • • Group：输入项目组 ID，通常使用公司或组织域名的逆序，比如 “com.example”，这样可以确保项目组 ID 的唯一性，便于在 Maven 仓库中管理项目依赖。

• • • Artifact：输入项目名，例如 “spring-boot-tdengine-integration”，这个名称将作为 Maven 的 Artifact ID，用于标识项目。

• • • Name：输入项目显示名称，也可以保持与 Artifact 一致。

• • • Description：输入项目描述信息，这是可选的，用于对项目进行简要说明，方便团队成员了解项目的用途和目标。

• • • Package Name：输入包名，通常是 Group 和 Artifact 的组合，例如 “com.example.springboottdengineintegration”，包名用于组织项目中的 Java 类，遵循一定的命名规范有助于代码的管理和维护 。

• • • Packaging：选择项目打包方式，这里我们选择 “Jar”，Spring Boot 项目默认使用 Jar 打包方式，这种方式可以将项目及其依赖打包成一个可执行的 Jar 文件，方便部署和运行，在生产环境中，我们可以直接通过java -jar命令来启动应用 。

• • • Java Version：选择 JDK 版本，根据我们之前安装的 JDK，这里选择对应的版本，比如 “11” 。

1. 在 “Dependencies” 部分添加项目依赖：

• • 搜索并添加 “Spring Web” 依赖，Spring Web 依赖提供了构建 Web 应用所需的基础组件，包括 Spring MVC 框架和内置的 Tomcat 服务器等，它使得我们可以方便地创建 RESTful 接口、处理 HTTP 请求和响应等操作，为后续实现数据的接收和展示功能提供支持。

• • 搜索并添加 “Spring Data JPA” 依赖，Spring Data JPA 是 Spring Data 的一部分，它提供了一种基于 JPA（Java Persistence API）的简化数据访问方式，通过使用 Spring Data JPA，我们可以使用简单的接口和方法来操作数据库，而无需编写大量的 SQL 语句，大大提高了开发效率，方便我们与 TDengine 数据库进行交互。

1. 完成配置后，点击 “Generate” 按钮，Spring Initializr 会生成一个包含项目基础结构的 ZIP 文件，下载并解压该文件，即可得到我们的 Spring Boot 项目。

项目结构介绍

解压后的 Spring Boot 项目目录结构如下：

spring-boot-tdengine-integration

├── .gitignore

├── mvnw

├── mvnw.cmd

├── pom.xml

├── src

│ ├── main

│ │ ├── java

│ │ │ └── com

│ │ │ └── example

│ │ │ └── springboottdengineintegration

│ │ │ ├── SpringBootTdengineIntegrationApplication.java

│ │ │ ├── config

│ │ │ ├── controller

│ │ │ ├── dao

│ │ │ ├── service

│ │ │ └── entity

│ │ └── resources

│ │ ├── application.properties

│ │ ├── static

│ │ └── templates

│ └── test

│ ├── java

│ │ └── com

│ │ └── example

│ │ └── springboottdengineintegration

│ │ └── SpringBootTdengineIntegrationApplicationTests.java

│ └── resources

└── target

• .gitignore：版本控制系统 Git 的配置文件，用于指定哪些文件或目录不需要被 Git 跟踪，比如编译生成的文件、日志文件等，避免将不必要的文件提交到代码仓库中，保持仓库的整洁和高效 。

• mvnw 和 mvnw.cmd：Maven Wrapper 的脚本文件，分别用于 Linux 和 Windows 系统。Maven Wrapper 可以让项目使用指定版本的 Maven，而无需在本地全局安装该版本的 Maven，它会自动下载并使用项目指定的 Maven 版本，确保项目在不同环境中的构建一致性，比如当团队成员使用不同的 Maven 版本时，通过 Maven Wrapper 可以保证每个人使用的 Maven 版本与项目要求的一致 。

• pom.xml：Maven 项目对象模型文件，是项目的核心配置文件。它定义了项目的基本信息，如 Group ID、Artifact ID、版本号等，同时管理项目的依赖关系，我们在 Spring Initializr 中添加的依赖都会在这个文件中体现，例如：

<dependencies>

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-data-jpa</artifactId>

</dependency>

</dependencies>

在后续开发中，如果需要添加新的依赖，也可以手动在这个文件中进行配置，然后通过 Maven 的mvn clean install命令来下载新的依赖 。

• src：项目源代码目录，包含main和test两个子目录，分别用于存放生产代码和测试代码 。

• • src/main/java：存放项目的 Java 源代码，按照包名进行组织，我们的业务逻辑代码、配置类、控制器、数据访问层代码等都放在这里。其中，SpringBootTdengineIntegrationApplication.java是 Spring Boot 项目的启动类，包含main方法，通过运行这个类来启动整个 Spring Boot 应用，它使用了@SpringBootApplication注解，这是一个组合注解，包含了@Configuration、@EnableAutoConfiguration和@ComponentScan等注解，用于开启 Spring Boot 的自动配置和组件扫描功能 。config目录用于存放配置类，比如数据库连接配置、自定义 Bean 配置等；controller目录用于存放控制器类，处理 HTTP 请求并返回响应；dao目录用于存放数据访问对象（DAO），负责与数据库进行交互；service目录用于存放业务逻辑层代码，处理具体的业务逻辑；entity目录用于存放实体类，对应数据库中的表结构 。

• • src/main/resources：存放项目的资源文件，如配置文件、静态资源、模板文件等。其中，application.properties是 Spring Boot 的默认配置文件，我们可以在这个文件中配置项目的各种属性，如数据库连接信息、服务器端口号等；static目录用于存放静态资源，如 CSS、JavaScript、图片等，这些资源可以直接通过浏览器访问；templates目录用于存放模板文件，如 Thymeleaf、Freemarker 等模板引擎的模板文件，用于生成动态页面 。

• • src/test/java：存放项目的测试代码，用于对项目中的功能进行单元测试和集成测试，SpringBootTdengineIntegrationApplicationTests.java是一个默认的测试类，用于测试 Spring Boot 应用的基本功能，我们可以在这个类中编写各种测试方法，使用 JUnit、Mockito 等测试框架来验证代码的正确性 。

• • src/test/resources：存放测试相关的资源文件，比如测试用的配置文件、测试数据等 。

• target：项目构建输出目录，Maven 在构建项目时会将编译后的 class 文件、资源文件以及打包后的 Jar 文件等输出到这个目录下 。

了解项目的目录结构和各文件的作用，有助于我们在后续开发中更好地组织和管理代码，提高开发效率。

添加 TDengine 依赖

在完成 Spring Boot 项目的创建后，我们需要在项目中添加 TDengine 相关的依赖，以便能够与 TDengine 数据库进行交互。依赖管理是 Maven 项目的重要特性之一，通过在pom.xml文件中声明依赖，Maven 会自动下载并管理这些依赖及其传递依赖，确保项目在不同环境中的一致性和可重复性 。

打开项目根目录下的pom.xml文件，在<dependencies>标签内添加 TDengine 的 JDBC 驱动依赖和 Java SDK 依赖。TDengine 官方提供了 JDBC 驱动，使得 Java 应用能够通过标准的 JDBC 接口与 TDengine 数据库进行通信，而 Java SDK 则提供了更丰富的功能和便捷的操作方法，方便我们在 Java 代码中对 TDengine 进行各种操作 。

<dependencies>

<!-- TDengine JDBC驱动依赖 -->

<dependency>

<groupId>com.taosdata.jdbc</groupId>

<artifactId>tdengine-jdbc</artifactId>

<version>3.0.4.0</version>

</dependency>

<!-- TDengine Java SDK依赖（如果需要更高级功能，可添加） -->

<dependency>

<groupId>com.taosdata</groupId>

<artifactId>taos-sdk</artifactId>

<version>3.0.4.0</version>

</dependency>

<!-- 其他已有的依赖，如Spring Web、Spring Data JPA等 -->

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-web</artifactId>

</dependency>

<dependency>

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-data-jpa</artifactId>

</dependency>

</dependencies>

在添加依赖时，需要注意版本号的选择。版本号3.0.4.0是当前的示例版本，你应该根据实际情况选择与你安装的 TDengine 服务器版本相匹配的驱动和 SDK 版本，以确保兼容性和稳定性 。可以通过 TDengine 官方网站或 Maven 仓库（https://mvnrepository.com/）查询最新的版本信息 。如果版本不匹配，可能会导致连接错误、功能异常等问题 。

添加完依赖后，保存pom.xml文件，Maven 会自动下载这些依赖及其传递依赖。如果 Maven 没有自动下载，可以在命令行中进入项目根目录，执行mvn clean install命令，Maven 会读取pom.xml文件中的依赖信息，并从配置的镜像仓库中下载相应的依赖包到本地仓库中，以供项目使用 。在下载过程中，如果网络连接不稳定或仓库地址不可用，可能会出现下载失败的情况，此时可以检查网络连接、镜像配置或尝试更换仓库地址 。

通过添加 TDengine 依赖，我们的 Spring Boot 项目已经具备了与 TDengine 数据库进行交互的基本能力，接下来就可以进行数据库连接配置等后续步骤了 。

配置数据库连接

在完成依赖添加后，我们需要在 Spring Boot 项目中配置 TDengine 数据库的连接信息。Spring Boot 通过配置文件来管理各种配置参数，这种方式使得配置的修改和维护更加方便，同时也提高了项目的可移植性和可扩展性 。

我们可以在src/main/resources目录下的application.properties文件（如果使用 YAML 格式配置，则为application.yml文件）中添加 TDengine 的连接配置。以下是在application.properties文件中的配置示例：

# TDengine数据库连接URL，需要替换为实际的TDengine服务器地址、端口号和数据库名

spring.datasource.url=jdbc:TAOS://localhost:6030/your_database_name

# TDengine数据库用户名，默认为root

spring.datasource.username=root

# TDengine数据库密码，默认为taosdata，实际使用中请替换为安全的密码

spring.datasource.password=taosdata

# TDengine JDBC驱动类名

spring.datasource.driver-class-name=com.taosdata.jdbc.TSDBDriver

在上述配置中：

• spring.datasource.url：指定 TDengine 数据库的连接 URL，其格式为jdbc:TAOS://<服务器地址>:<端口号>/<数据库名>。其中，<服务器地址>需要替换为实际的 TDengine 服务器 IP 地址或域名，如果 TDengine 服务器与 Spring Boot 应用在同一台机器上运行，可以使用localhost；<端口号>默认为 6030，这是 TDengine 的默认服务端口；<数据库名>需要替换为你在 TDengine 中创建的实际数据库名称，例如iot_data，用于存储物联网设备产生的时序数据 。如果需要设置其他连接参数，如字符集、时区等，可以在 URL 后面以?key=value的形式添加，例如jdbc:TAOS://localhost:6030/iot_data?charset=UTF-8&timezone=UTC-8 。

• spring.datasource.username：指定连接 TDengine 数据库的用户名，TDengine 默认的用户名是root，在实际应用中，如果有自定义的用户并分配了相应的权限，可以使用自定义用户名 。

• spring.datasource.password：指定连接 TDengine 数据库的密码，默认密码是taosdata，为了确保数据库的安全，建议在生产环境中修改为一个强密码，并妥善保管 。

• spring.datasource.driver-class-name：指定 TDengine 的 JDBC 驱动类名，com.taosdata.jdbc.TSDBDriver是 TDengine 官方提供的 JDBC 驱动类，用于建立 Java 应用与 TDengine 数据库之间的连接 。

如果你使用的是application.yml文件，配置如下：

spring:

datasource:

url: jdbc:TAOS://localhost:6030/your_database_name

username: root

password: taosdata

driver-class-name: com.taosdata.jdbc.TSDBDriver

YAML 格式的配置文件以缩进表示层级关系，更加简洁易读，在实际项目中，可以根据个人习惯和团队规范选择使用application.properties或application.yml文件进行配置 。

配置完成后，Spring Boot 在启动时会读取这些配置信息，并根据这些信息创建与 TDengine 数据库的连接。如果配置信息有误，例如服务器地址错误、端口号被占用、用户名或密码错误等，在应用启动时会抛出相应的异常，如org.springframework.jdbc.CannotGetJdbcConnectionException，提示无法获取数据库连接 。此时，需要仔细检查配置信息，确保其准确性。同时，还需要确保 TDengine 服务器已经正确启动并运行，网络连接正常，以保证 Spring Boot 应用能够成功连接到 TDengine 数据库 。