Skip to content

Spring Cloud Tencent Metadata Transfer 使用指南

Jump to bottom
Haotian Zhang edited this page Oct 28, 2025 · 17 revisions

目录

元数据管理简介

在微服务架构中，常常需要在微服务实例内部或实例之间管理一些元数据，这些元数据可以用来做为内部使用的基础系统信息，也可以作为需要在实例之间传递的数据信息，在微服务的全链路中都会有或多或少的作用。而 Spring Cloud 默认的组件没有提供相应的功能，因此，Spring Cloud Tencent 为了自身组件的使用并拓展给开发者自定义开发，提供了一套元数据管理解决方案。

元数据分类

元数据管理功能，会让应用从多个渠道读取元数据，覆盖尽可能多的使用场景，方便开发者使用不同姿势设置元数据。元数据可以根据来源进行分类，包括：

  • 系统环境变量读取
  • 配置文件读取
  • InstanceMetadataProvider接口的实现类读取（1.6.0及以上版本包含此功能）
  • 服务链路上游传递

元数据有些是需要传递到下游服务的，有些是只允许当前服务实例使用的，因此元数据还可以根据传递类型分为：

  • 可传递元数据
  • 不可传递元数据
  • 一跳（一次性）元数据（1.7.0及以上版本包含此功能）

代码结构

在项目内，元数据相关逻辑主要在两个模块内。

  1. spring-cloud-tencent-commons，其中包含微服务实例本地元数据存储和读取等逻辑。
  2. spring-cloud-starter-tencent-metadata-transfer，其中包含元数据在上下游传递的具体行为逻辑，包括从上游传下来的元数据读取和向下游传递可传递元数据。

使用说明

系统环境变量读取

元数据管理支持从系统环境变量读取。开发者可以在系统环境变量中添加以 SCT_METADATA_CONTENT_ 开头的环境变量，设置需要被读取的元数据键值对，同时添加:

  • SCT_METADATA_CONTENT_TRANSITIVE 环境变量用于表示需要传递到下游的元数据键的列表，用“,”分隔。
  • SCT_METADATA_CONTENT_DISPOSABLE 环境变量用于表示需要传递到下游的一跳（一次性）的元数据键列表，用“,”分隔。（1.7.0及以上版本包含此功能）
  • SCT_TRAFFIC_CONTENT_RAW_TRANSHEADERS 环境变量用于表示需要传递到下游的原始HTTP头部的头部键列表，用“,”分隔。（1.8.0及以上版本包含此功能）

元数据管理还支持三个特定的环境变量读取，即 SCT_METADATA_ZONE、SCT_METADATA_REGION 和 SCT_METADATA_CAMPUS，用于表示服务实例的位置信息，用于就近路由。如下所示，自定义元数据总共包含三个，即 (env,blue)、(label,value1)、(name,zhangsan)，从第四行可以得出，只有 (env,blue) 和 (label,value1) 两个元数据键值对需要传递到下游服务。最后三行是位置信息元数据，依次是华南地区、深圳地域、深圳1区，该元数据会被上报到注册中心，并使用于就近路由。

SCT_METADATA_CONTENT_env=blue
SCT_METADATA_CONTENT_label=value1
SCT_METADATA_CONTENT_name=zhangsan
SCT_METADATA_CONTENT_disposable=zhangsan
SCT_METADATA_CONTENT_TRANSITIVE=env,label
SCT_METADATA_CONTENT_DISPOSABLE=disposable
SCT_TRAFFIC_CONTENT_RAW_TRANSHEADERS=custom-header
SCT_METADATA_REGION=huanan
SCT_METADATA_ZONE=shenzhen
SCT_METADATA_CAMPUS=shenzhen1

配置文件读取

自定义元数据通过 spring.cloud.tencent.metadata.content 打标，需要被链路上传递的标签则需要在 spring.cloud.tencent.metadata.transitive 指定 Key。不在 spring.cloud.tencent.metadata.transitive 中的 Key 则不会被传递到链路上。

在spring.cloud.tencent.metadata.disposable 中的 Key会被往下游服务传递一次，假设有a,b,c链路服务，a 中的 disposable 元数据，只会被传递到 b 服务中，不会传递到 c 服务中。

如下所示 (a,1) 将会被传递到下游服务，而 (b,2) 不会被传递，(c,3) 将只会被（一跳）传递到直接的下游服务。

spring:
  cloud:
    tencent:
      metadata:
        content:
          a: 1
          b: 2
          c: 3
        transitive:
          - a
        # 一次性（一跳）元数据键列表配置，（1.7.0及以上版本包含此功能）
        disposable:
          - c
        # 需要传递的原始HTTP头部数据，（1.13.0及以上版本包含此功能）
        headers:
          - k1

InstanceMetadataProvider接口的实现类读取（1.6.0及以上版本包含此功能）

元数据支持通过实现内部提供的接口来进行读取，开发者可以实现相关的方法，提供对应的元数据，包括静态元数据、可传递元数据和地域信息等。具体开发可以参考InstanceMetadataProvider接口实现样例。

服务链路上游传递

元数据也支持在服务链路上进行传递，开发者可以在HTTP头部加入以 X-SCT-Metadata-Transitive- 开头的键值对，然后被 spring-cloud-starter-tencent-metadata-transfer 模块识别后，纳入可传递元数据之中。例如：

curl -L -X GET 'localhost:48083/router/service/caller/feign?name=skye' -H 'X-SCT-Metadata-Transitive-env: env2'

引入 Spring Cloud Tencent Metadata Transfer 依赖

使用元数据传递能力需要增加以下依赖

注意： Spring Cloud 、 Spring Boot 、 Spring Framework 之间有严格的版本对应关系，在 Spring Cloud Tencent 版本管理 文档中有详细罗列版本兼容性关系。请您在引入 Spring Cloud Tencent 版本时，根据项目 Spring Boot 和 Spring Framework 的版本，选择合适的 Spring Cloud Tencent 版本。

例如：

<!-- 引入 Bom -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.tencent.cloud</groupId>
            <artifactId>spring-cloud-tencent-dependencies</artifactId>
            <version>${latest.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<!-- 引入依赖 -->
<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-metadata-transfer</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-bootstrap</artifactId>
</dependency>

元数据 API

可传递的自定义 Metadata

  1. MetadataContextHolder 途径

该途径为获取ThreadLocal。

  • 获取可传递的元数据映射表
MetadataContextHolder.get().getTransitiveMetadata();
  • 获取上游传递过来的一次性元数据
Map<String, String> upstreamDisposableMetadatas = MetadataContextHolder.getAllDisposableMetadata(true);
upstreamDisposableMetadatas.forEach((key, value) -> {
    // ...
});
  • 获取本地配置的一次性元数据
Map<String, String> localDisposableMetadatas = MetadataContextHolder.getAllDisposableMetadata(false);
localDisposableMetadatas.forEach((key, value) -> {
    // ...
});
  1. StaticMetadataManager途径

该途径首先需要获取对应的 Bean ，然后再进行使用操作。

@Autowired
private StaticMetadataManager staticMetadataManager;
  • 获取region
staticMetadataManager.getRegion();
  • 获取zone
staticMetadataManager.getZone();
  • 获取campus
staticMetadataManager.getCampus();
  • 获取所有地理信息元数据映射表
staticMetadataManager.getLocationMetadata();
  • 获取所有环境变量读取到的元数据映射表
staticMetadataManager.getAllEnvMetadata();
  • 获取环境变量中可传递的元数据映射表
staticMetadataManager.getEnvTransitiveMetadata();
  • 获取环境变量中可传递的一次性（一跳）元数据映射表
staticMetadataManager.getEnvDisposableMetadata();
  • 获取所有配置文件读取到的元数据映射表
staticMetadataManager.getAllConfigMetadata();
  • 获取配置文件中可传递的元数据映射表
staticMetadataManager.getConfigTransitiveMetadata();
  • 获取配置文件中可传递的一次性（一跳）元数据映射表
staticMetadataManager.getConfigDisposableMetadata();
  • 获取InstanceMetadataProvider实现类读取到的元数据映射表
staticMetadataManager.getAllCustomMetadata();
  • 获取InstanceMetadataProvider实现类中可传递的元数据映射表
staticMetadataManager.getCustomSPITransitiveMetadata();
  • 获取InstanceMetadataProvider实现类中可传递的一次性（一跳）元数据映射表
staticMetadataManager.getCustomSPIDisposableMetadata();
  • 获取所有读取到的元数据映射表
staticMetadataManager.getMergedStaticMetadata();
  • 获取所有读取到的可传递的元数据映射表
staticMetadataManager.getMergedStaticTransitiveMetadata();
  • 获取所有读取到的可传递的一次性（一跳）元数据映射表
staticMetadataManager.getMergedStaticDisposableMetadata();

跨线程标签传递

相关工具类

父线程标签上下文获取

com.tencent.cloud.common.metadata.CrossThreadMetadataContext#CROSS_THREAD_METADATA_CONTEXT_SUPPLIER

子线程标签上下文设置

com.tencent.cloud.common.metadata.CrossThreadMetadataContext#CROSS_THREAD_METADATA_CONTEXT_CONSUMER

CompletableFuture

supplyAsync

调用如下方法代替 CompletableFuture.supplyAsync

com.tencent.cloud.common.util.PolarisCompletableFutureUtils#supplyAsync

runAsync

调用如下方法代替 CompletableFuture.runAsync

com.tencent.cloud.common.util.PolarisCompletableFutureUtils#runAsync`

TaskExecutor

使用如下类包装原有的 TaskExecutor

com.tencent.cloud.plugin.threadlocal.TaskExecutorWrapper#TaskExecutorWrapper

如：

new TaskExecutorWrapper<>(new ThreadPoolTaskExecutor(), CROSS_THREAD_METADATA_CONTEXT_SUPPLIER, CROSS_THREAD_METADATA_CONTEXT_CONSUMER);
  • 您在使用过程中遇到任何问题，请提 Issue 或者加入我们的开发者群告诉我们，我们会在第一时间反馈
  • Spring Cloud Tencent 社区期待您的加入，一个 Star、PR 都是对我们最大的支持

Clone this wiki locally