Spring Boot 集成 InfluxDB 3.x

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

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

一、环境准备

1. 确保已安装 InfluxDB 3.x（可通过 Docker 快速部署：docker run -p 8086:8086 quay.io/influxdb/influxdb:3.0.0）
2. 获取 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 依赖

xml

<!-- 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 依赖

groovy

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 配置

yaml

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，实现客户端的统一管理和依赖注入：

java

运行

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 层示例：

java

运行

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 查询示例：

java

运行

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. 控制器调用示例

java

运行

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);
    }
}

六、关键注意事项

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

总结

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