升级Spring Boot3及Prometheus、Micrometer后访问监控端点遇类型转换异常

云上老周

2026-6-20

问题描述

将项目Maven依赖升级至Spring Boot 3后，同步将Prometheus和Micrometer升级到1.10及以上版本。应用启动正常，但访问/actuator/prometheus端点时抛出以下类型转换异常：

caused: class io.prometheus.metrics.model.snapshots.SummarySnapshot$SummaryDataPointSnapshot cannot be cast to class io.prometheus.metrics.model.snapshots.GaugeSnapshot$GaugeDataPointSnapshot (io.prometheus.metrics.model.snapshots.SummarySnapshot$SummaryDataPointSnapshot and io.prometheus.metrics.model.snapshots.GaugeSnapshot$GaugeDataPointSnapshot are in unnamed module of loader 'app');

当前相关Maven依赖配置如下：

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient</artifactId>
</dependency>

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-core</artifactId>
</dependency>

已参考官方迁移指南完成代码适配，但该异常未在指南中提及，且项目代码并未直接使用SummarySnapshot和GaugeSnapshot类，请问该异常的触发原因是什么？

异常原因分析

这个问题的核心是依赖版本不兼容导致的Prometheus metrics SDK版本冲突：

新旧API不兼容：Spring Boot 3 + Micrometer 1.10+ 适配的是Prometheus全新的metrics API，而你引入的io.prometheus:simpleclient是旧版Prometheus客户端依赖，二者的指标数据快照模型完全不同，底层处理时会出现类型误判。
缺少适配桥接：单独引入micrometer-core仅能提供核心指标能力，Spring Boot 3整合Prometheus需要专门的桥接依赖完成Micrometer指标到Prometheus格式的转换，当前依赖配置缺失该组件，导致指标流转流程中出现类型转换错误。
隐式依赖冲突：即使你没有直接使用SummarySnapshot和GaugeSnapshot，这些类是底层指标处理框架的核心类，旧版simpleclient和新版Micrometer依赖的Prometheus API版本不一致，加载了不同版本的类，最终触发强制转换异常。

解决方案

移除旧版依赖：删除io.prometheus:simpleclient依赖，避免新旧API冲突。
添加官方桥接依赖：引入Spring Boot推荐的Micrometer-Prometheus桥接组件：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

统一版本管理：确保所有Micrometer、Prometheus相关依赖都通过Spring Boot的spring-boot-starter-parent或spring-boot-dependencies进行版本管理，不要手动指定版本，避免出现隐式版本冲突。

内容的提问来源于stack exchange，提问作者CN Dioxide