参数传递

最近更新时间:2019-04-08 16:31:55

元数据类别

TSF 提供两种类型的元数据供开发者在代码中进行设置:

类型 特点
标签信息(Tags) 可设置传递性,仅支持 key-value 数据结构,key 和 value 均为字符串类型。
辅助信息(CustomMetadata) 仅供展示,不支持筛选,不具备传递性。

场景说明:

  • 标签信息 :用于信息分类,使用场景包括:

    • 服务鉴权:被调方通过标签来决定是否提供服务。
    • 服务路由:通过标签来判断应该访问什么服务,可用于实现金丝雀发布等。
    • 调用链:可用于调用链的筛选和附带业务信息。
  • 辅助信息 (CustomMetadata):仅供展示,不支持筛选,不具备传递性。

元数据的传递性

以调用关系 A ≥ B ≥ C,说明传递性的概念:

  • 可传递(Transitive):需要传递的标签,在整条链路都传递,即用户在 A 设置的标签,会传递到 B 再传递到 C。
  • 不可传递:不需要传递的标签,即用户在 A 设置的标签,会传递到 B,但是不会传递到 C。

标签信息支持允许用户设置是否支持传递,辅助信息不支持传递。
不同的标签可以设置不同传递性,比如一些业务场景:

  • userid 标签是需要传递的:
    • 可以作为整条调用链上的服务的 上下文信息。
    • 可以实现按 uin 区分的服务路由,比如 A、B、C 三个服务同时做滚动发布,那么可以让一批 uin 都走新版本的 A、B、C 服务,其他用户走老版本。
  • level=高级会员 这种标签,很可能就不需要在调用间传递下去。

使用元数据

依赖项

pom.xml 中添加依赖项:

<dependency>
    <groupId>com.tencent.tsf</groupId>
    <artifactId>spring-cloud-tsf-core</artifactId>
    <version><!-- 调整为 SDK 最新版本号 --></version>
</dependency>

接口

public enum ControlFlag {
    TRANSITIVE     // 表示标签要传递下去,默认不启用
    NOT_IN_AUTH    // 表示标签不被使用在服务鉴权,默认是被使用的
    NOT_IN_ROUTE   // 表示标签不被使用在服务路由,默认是被使用的
    NOT_IN_SLEUTH  // 表示标签不被使用在调用链,默认是被使用的
}

public class TsfContext {
    /**
     * 设置多个 Tag。如果有某个 Tag 之前已经被设置过,那么它的值会被覆盖。
     */
    public static void putTags(Map<String, String> tagMap, TagControlFlag... flags) {}

    /**
     * 设置 Tag。如果该 key 之前已经被设置过,那么它的值会被覆盖。
     */
    public static void putTag(String key, String value, TagControlFlag... flags) {}
}

场景1:设置鉴权 Tag

TSF 提供的 Demo consumer-demo/src/main/java/com/tsf/demo/consumer/Controller.java 中设置了键为 user,请求参数作为值的 Tag。Tag 鉴权的具体使用方法可参考 服务鉴权

@RequestMapping(value = "/echo-rest/{str}", method = RequestMethod.GET)
public String rest(@PathVariable String str, @RequestParam String user) {
    TsfContext.putTag("user", user); 
    return restTemplate.getForObject("http://provider-demo/echo/" + str, String.class);
}

场景2:设置调用链 Tag

设置 user=12345678 的标签,用户可以在控制台 调用链查询界面 通过标签 user=12345678 来检索调用链。调用链标签的具体使用方法参考 调用链

TsfContext.putTag("user", "12345678", TRANSITIVE);

Tag 的长度限制

用户传递到下流的 Tag (包含从上流带过来的有传递性的 Tag),数量上限为16个。Key 的长度上限为 UTF-8 编码后32字节,value 的长度上限为 UTF-8 编码后128字节。