Spring Cloud Tencent Metadata Transfer 使用指南

目录

• 元数据管理简介
• 元数据分类
• 代码结构
• 使用说明
  • 系统环境变量读取
  • 配置文件读取
  • InstanceMetadataProvider接口的实现类读取（1.6.0及以上版本包含此功能）
  • 服务链路上游传递
  • 引入 Spring Cloud Tencent Metadata Transfer 依赖
• 元数据 API

元数据管理简介

在微服务架构中，常常需要在微服务实例内部或实例之间管理一些元数据，这些元数据可以用来做为内部使用的基础系统信息，也可以作为需要在实例之间传递的数据信息，在微服务的全链路中都会有或多或少的作用。而 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) -> {
    // ...
});

2. 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();