Spring Cloud Tencent 元数据传递示例详解

原创于 2025-06-11 09:19:57 发布 · 305 阅读

CC 4.0 BY-SA版权

Spring Cloud Tencent 元数据传递示例详解

spring-cloud-tencent Tencent/spring-cloud-tencent: 一个基于 Spring Cloud 的腾讯云微服务框架，用于实现腾讯云微服务的集成和自动化。适合用于需要腾讯云微服务集成和自动化场景，可以实现高效的服务管理和通信。项目地址: https://gitcode.com/gh_mirrors/sp/spring-cloud-tencent

概述

本文将通过一个完整示例，详细介绍如何在 Spring Cloud Tencent 项目中实现元数据传递功能。元数据传递是微服务架构中的重要能力，它允许服务间传递自定义的业务上下文信息，实现全链路信息透传。

示例架构

本示例采用典型的三层服务调用链：

metadata-frontend：前端服务，接收外部请求
metadata-middle：中间层服务，处理业务逻辑
metadata-backend：后端服务，提供基础数据

核心概念

在 Spring Cloud Tencent 中，元数据分为三种类型：

本地元数据：仅在当前服务生效，不会传递给下游服务
可传递元数据：会随着调用链路一直传递到末端服务
一次性元数据：只会传递给直接的下游服务，不会继续传递

环境准备

基础依赖

在项目中添加以下 Maven 依赖：

<dependency>
    <groupId>com.tencent.cloud</groupId>
    <artifactId>spring-cloud-starter-tencent-metadata-transfer</artifactId>
</dependency>

配置中心连接

在 application.yml 中配置 Polaris 服务发现地址：

spring:
  cloud:
    polaris:
      address: ${ip}:${port}

元数据配置详解

前端服务配置

spring:
  cloud:
    tencent:
      metadata:
        content:
          # 本地元数据（不会传递）
          CUSTOM-METADATA-KEY-LOCAL: CUSTOM-VALUE-LOCAL
          # 可传递元数据（全链路传递）
          CUSTOM-METADATA-KEY-TRANSITIVE: CUSTOM-VALUE-TRANSITIVE-FRONTEND
          # 一次性元数据（只传一级）
          CUSTOM-METADATA-KEY-DISPOSABLE: CUSTOM-VALUE-DISPOSABLE-FRONTEND
        transitive:
          - CUSTOM-METADATA-KEY-TRANSITIVE  # 指定可传递的key
        disposable:
          - CUSTOM-METADATA-KEY-DISPOSABLE   # 指定一次性的key

中间层服务配置

spring:
  cloud:
    tencent:
      metadata:
        content:
          CUSTOM-METADATA-KEY-LOCAL-2: CUSTOM-VALUE-LOCAL-2
          CUSTOM-METADATA-KEY-TRANSITIVE-2: CUSTOM-VALUE-TRANSITIVE-2
          CUSTOM-METADATA-KEY-DISPOSABLE: CUSTOM-VALUE-DISPOSABLE-MIDDLE
        transitive:
          - CUSTOM-METADATA-KEY-TRANSITIVE-2
        disposable:
          - CUSTOM-METADATA-KEY-DISPOSABLE

验证与测试

发起测试请求

curl -L -X GET 'http://127.0.0.1:48080/metadata/service/caller/feign/info'

预期响应分析

响应结果展示了三种元数据在不同服务中的表现：

可传递元数据：
- 前端设置的 CUSTOM-METADATA-KEY-TRANSITIVE 贯穿整个调用链
- 中间层设置的 CUSTOM-METADATA-KEY-TRANSITIVE-2 从中间层开始传递
一次性元数据：
- 前端设置的 CUSTOM-METADATA-KEY-DISPOSABLE 只传递到中间层
- 中间层设置的 CUSTOM-METADATA-KEY-DISPOSABLE 只传递到后端
本地元数据：
- 不会出现在响应中，因为仅在各服务本地有效

编程式获取元数据

获取全链路传递的元数据

MetadataContext context = MetadataContextHolder.get();
Map<String, String> customMetadataMap = context.getFragmentContext(MetadataContext.FRAGMENT_TRANSITIVE);

获取上游传来的一次性元数据

Map<String, String> upstreamMetadatas = MetadataContextHolder.getAllDisposableMetadata(true);

获取本地设置的一次性元数据

Map<String, String> localMetadatas = MetadataContextHolder.getAllDisposableMetadata(false);

实际应用场景

全链路灰度发布：通过传递版本号元数据实现流量路由
业务上下文传递：传递用户身份、权限等业务信息
调试信息跟踪：传递调试标志，实现全链路调试
流量染色：标记特殊流量实现监控隔离

最佳实践建议

命名规范：元数据key建议使用统一前缀，避免冲突
大小控制：元数据不宜过大，避免影响网络性能
敏感信息：避免在元数据中传递敏感信息
版本兼容：变更元数据结构时考虑向后兼容

通过本文的示例和讲解，开发者可以快速掌握 Spring Cloud Tencent 的元数据传递功能，在微服务架构中实现灵活的业务上下文传递。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考