首页 > 软件编程 > java > Spring Boot 集成 InfluxDB 3.x

Spring Boot 集成 InfluxDB 3.x完整教程

2026-01-22 11:08:21 作者：高级盘丝洞

本文详细介绍了如何在SpringBoot项目中集成InfluxDB3.x,并提供了一个完整的教程,包括环境准备、添加依赖、配置连接信息、创建客户端配置类、数据写入与查询示例以及关键注意事项,感兴趣的朋友跟随小编一起看看吧

Spring Boot 集成 InfluxDB 3.x 完整教程

你希望实现 Spring Boot 与 InfluxDB 3.x 的集成，InfluxDB 3.x （基于 IOx）相比旧版本有较大架构调整，推荐使用官方提供的 Java 客户端进行集成，以下是详细步骤：

一、环境准备

确保已安装 InfluxDB 3.x（可通过 Docker 快速部署：docker run -p 8086:8086 quay.io/influxdb/influxdb:3.0.0）
获取 InfluxDB 3.x 核心配置信息：
- 连接 URL（默认：http://localhost:8086）
- 认证令牌（Token，在 InfluxDB 控制台生成）
- 数据库名称（Bucket，对应 InfluxDB 3.x 的存储桶）
- 组织 ID（Organization ID，InfluxDB 控制台可查询）

二、添加依赖

在 Spring Boot 项目的 pom.xml（Maven）或 build.gradle（Gradle）中添加 InfluxDB 3.x Java 客户端依赖，推荐使用官方的 influxdb3-java：

Maven 依赖

<!-- InfluxDB 3.x Java 客户端 -->
<dependency>
    <groupId>com.influxdb</groupId>
    <artifactId>influxdb3-java</artifactId>
    <version>6.8.0</version> <!-- 推荐使用最新稳定版 -->
</dependency>
<!-- Spring Boot 核心依赖（已存在可忽略） -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter</artifactId>
</dependency>

Gradle 依赖

dependencies {
    implementation 'com.influxdb:influxdb3-java:6.8.0'
    implementation 'org.springframework.boot:spring-boot-starter'
}

三、配置 InfluxDB 3.x 连接信息

在 application.yml 或 application.properties 中配置 InfluxDB 3.x 连接参数，便于统一管理：

application.yml 配置

spring:
  influxdb3:
    url: http://localhost:8086 # InfluxDB 3.x 连接地址
    token: your-influxdb3-auth-token # 认证令牌
    bucket: your-bucket-name # 存储桶名称（对应数据库）
    org: your-organization-id # 组织ID
    timeout: 30000 # 连接超时时间（可选，默认30秒）

application.properties 配置

properties

spring.influxdb3.url=http://localhost:8086
spring.influxdb3.token=your-influxdb3-auth-token
spring.influxdb3.bucket=your-bucket-name
spring.influxdb3.org=your-organization-id
spring.influxdb3.timeout=30000

四、创建 InfluxDB 3.x 客户端配置类

通过 Spring 配置类创建 InfluxDBClient3 单例 Bean，实现客户端的统一管理和依赖注入：

import com.influxdb.v3.client.InfluxDBClient3;
import com.influxdb.v3.client.InfluxDBClient3Factory;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * InfluxDB 3.x 客户端配置类
 */
@Configuration
public class InfluxDB3Config {
    @Value("${spring.influxdb3.url}")
    private String influxDbUrl;
    @Value("${spring.influxdb3.token}")
    private String influxDbToken;
    @Value("${spring.influxdb3.bucket}")
    private String influxDbBucket;
    @Value("${spring.influxdb3.org}")
    private String influxDbOrg;
    @Value("${spring.influxdb3.timeout:30000}")
    private int influxDbTimeout;
    /**
     * 创建 InfluxDBClient3 单例 Bean
     * @return InfluxDBClient3 客户端实例
     */
    @Bean(destroyMethod = "close") // 容器销毁时自动关闭客户端连接
    public InfluxDBClient3 influxDBClient3() {
        return InfluxDBClient3Factory.create(
                influxDbUrl,
                influxDbToken.toCharArray(),
                influxDbOrg,
                influxDbBucket
        );
    }
}

五、数据写入与查询示例

1. 数据写入（支持 Line Protocol 格式）

InfluxDB 3.x 推荐使用 Line Protocol 格式写入数据，以下是 Service 层示例：

import com.influxdb.v3.client.InfluxDBClient3;
import org.springframework.stereotype.Service;
import java.time.Instant;
/**
 * InfluxDB 3.x 数据操作服务
 */
@Service
public class InfluxDB3Service {
    private final InfluxDBClient3 influxDBClient3;
    // 构造函数注入客户端
    public InfluxDB3Service(InfluxDBClient3 influxDBClient3) {
        this.influxDBClient3 = influxDBClient3;
    }
    /**
     * 写入监控数据（Line Protocol 格式）
     * @param measurement 测量值名称（表名）
     * @param deviceId 设备ID（标签）
     * @param temperature 温度（字段）
     * @param humidity 湿度（字段）
     */
    public void writeMonitorData(String measurement, String deviceId, double temperature, double humidity) {
        // 构建 Line Protocol 字符串：measurement tagKey=tagValue fieldKey=fieldValue timestamp
        String lineProtocol = String.format(
                "%s,device_id=%s temperature=%.2f,humidity=%.2f %d",
                measurement,
                deviceId,
                temperature,
                humidity,
                Instant.now().toEpochMilli() * 1_000_000 // 时间戳（纳秒级）
        );
        // 写入数据
        influxDBClient3.writeRecord(lineProtocol);
        System.out.println("数据写入成功：" + lineProtocol);
    }
}

2. 数据查询（支持 SQL 或 InfluxQL）

InfluxDB 3.x 支持 SQL 和 InfluxQL 两种查询语法，以下是 SQL 查询示例：

import com.influxdb.v3.client.QueryResult;
import com.influxdb.v3.client.exceptions.InfluxException;
import java.util.List;
import java.util.Map;
/**
 * 扩展查询方法
 */
public class InfluxDB3Service {
    // 省略已有代码...
    /**
     * 查询指定设备的最新监控数据
     * @param deviceId 设备ID
     * @return 查询结果列表
     */
    public List<Map<String, Object>> queryLatestMonitorData(String deviceId) {
        // SQL 查询语句（InfluxDB 3.x 兼容 SQL 语法）
        String sql = String.format(
                "SELECT * FROM monitor_data WHERE device_id = '%s' ORDER BY time DESC LIMIT 10",
                deviceId
        );
        try {
            // 执行查询
            QueryResult queryResult = influxDBClient3.query(sql);
            // 转换为 Map 列表（便于后续处理）
            return queryResult.getRecords();
        } catch (InfluxException e) {
            System.err.println("查询失败：" + e.getMessage());
            throw new RuntimeException("InfluxDB 查询异常", e);
        }
    }
}

3. 控制器调用示例

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import java.util.Map;
@RestController
@RequestMapping("/influxdb3")
public class InfluxDB3Controller {
    private final InfluxDB3Service influxDB3Service;
    public InfluxDB3Controller(InfluxDB3Service influxDB3Service) {
        this.influxDB3Service = influxDB3Service;
    }
    /**
     * 写入数据接口
     */
    @PostMapping("/write")
    public String writeData(
            @RequestParam String deviceId,
            @RequestParam double temperature,
            @RequestParam double humidity
    ) {
        influxDB3Service.writeMonitorData("monitor_data", deviceId, temperature, humidity);
        return "数据写入成功";
    }
    /**
     * 查询数据接口
     */
    @GetMapping("/query")
    public List<Map<String, Object>> queryData(@RequestParam String deviceId) {
        return influxDB3Service.queryLatestMonitorData(deviceId);
    }
}

六、关键注意事项

Token 安全性：不要硬编码 Token，推荐通过配置文件、环境变量或配置中心管理，生产环境需加密存储。
连接关闭：配置 @Bean(destroyMethod = "close") 确保容器销毁时关闭客户端，避免连接泄露。
时间戳格式：InfluxDB 3.x 推荐使用纳秒级时间戳，Instant.now().toEpochMilli() * 1_000_000 可将毫秒级转换为纳秒级。
异常处理：实际项目中需添加更完善的异常捕获和重试机制，避免单次网络波动导致数据写入失败。
依赖版本：定期更新 influxdb3-java 版本，获取最新功能和 bug 修复，最新版本可在 Maven Central 查询。

总结

Spring Boot 集成 InfluxDB 3.x 的核心是引入 influxdb3-java 依赖，并配置 InfluxDBClient3 客户端 Bean。
连接参数（URL、Token、Bucket、Org）需在配置文件中统一配置，便于环境切换。
数据写入优先使用 Line Protocol 格式，数据查询支持 SQL 和 InfluxQL 两种语法。
通过 @Bean(destroyMethod = "close") 可自动管理客户端连接的生命周期，避免资源泄露。

到此这篇关于Spring Boot 集成 InfluxDB 3.x完整教程的文章就介绍到这了,更多相关Spring Boot 集成 InfluxDB 3.x内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

Spring Boot 集成 InfluxDB 3.x完整教程