gRPC Java 客户端如何正确传递自定义元数据（Metadata）实现认证-java教程-PHP中文网

gRPC Java 客户端如何正确传递自定义元数据（Metadata）实现认证

本文详解在 grpc java 客户端中通过 `callcredentials` 注入 `clientid`、`workerid` 和 `instance` 等 ascii 元数据的完整实践方案，避免 `unauthenticated: invalid credentials` 错误。

在 gRPC Java 中，若服务端要求通过请求头（即 Metadata）校验身份（如 clientid=1, workerid=2, instance=3），不能将元数据直接写入 stub 或手动构造 Metadata 后调用 apply() —— 这些操作不会被底层传输链路自动携带。正确方式是实现 CallCredentials，让 gRPC 在每次 RPC 调用前异步注入元数据。

核心要点如下：

✅ 必须继承 io.grpc.CallCredentials 并重写 applyRequestMetadata()；
✅ 元数据键必须使用 Metadata.Key.of("key", Metadata.ASCII_STRING_MARSHALLER) 声明（区分大小写，且需 ASCII 编码）；
✅ applyRequestMetadata 中需在传入的 Executor 上异步执行元数据构造与 metadataApplier.apply()，不可阻塞主线程；
✅ 必须实现空方法 thisUsesUnstableApi()（gRPC 1.50+ 强制要求，用于标识 API 兼容性）；
❌ 不要尝试 mock RequestInfo 或 Executor 来“预填充”元数据——这仅适用于单元测试，无法影响真实 RPC 流程。

以下是推荐的生产级实现：

import io.grpc.CallCredentials;
import io.grpc.Metadata;
import io.grpc.Status;
import java.util.concurrent.Executor;

public class ApplyMetadata extends CallCredentials {
    private final String clientid;
    private final String workerid;
    private final String instance;

    // 使用 ASCII string marshaller 构建标准元数据键（注意：key 名会自动转为小写 HTTP 格式）
    private static final Metadata.Key<string> CLIENT_ID_KEY 
        = Metadata.Key.of("clientid", Metadata.ASCII_STRING_MARSHALLER);
    private static final Metadata.Key<string> WORKER_ID_KEY 
        = Metadata.Key.of("workerid", Metadata.ASCII_STRING_MARSHALLER);
    private static final Metadata.Key<string> INSTANCE_KEY 
        = Metadata.Key.of("instance", Metadata.ASCII_STRING_MARSHALLER);

    public ApplyMetadata(String clientid, String workerid, String instance) {
        this.clientid = clientid;
        this.workerid = workerid;
        this.instance = instance;
    }

    @Override
    public void applyRequestMetadata(
            RequestInfo requestInfo,
            Executor executor,
            MetadataApplier metadataApplier) {
        executor.execute(() -> {
            try {
                Metadata headers = new Metadata();
                headers.put(CLIENT_ID_KEY, clientid);
                headers.put(WORKER_ID_KEY, workerid);
                headers.put(INSTANCE_KEY, instance);
                metadataApplier.apply(headers);
            } catch (Throwable t) {
                // 发生异常时必须显式 fail，否则调用可能挂起
                metadataApplier.fail(Status.UNAUTHENTICATED.withCause(t));
            }
        });
    }

    @Override
    public void thisUsesUnstableApi() {
        // 必须实现，无实际逻辑；gRPC 框架据此判断兼容性策略
    }
}</string></string></string>

在业务代码中使用时，只需一行注入：

Java Development Man

Java开发手册规约集合，基于阿里巴巴Java开发手册（嵩山版）。涵盖7大维度：编程规约、异常日志、单元测试、安全规约、MySQL数据库、工程结构、设计规约。

下载

// 构造凭证实例（值可动态传入）
CallCredentials credentials = new ApplyMetadata("1", "2", "3");

// 绑定到 stub（支持 unary / streaming 所有调用）
YourServiceGrpc.YourServiceBlockingStub stub = YourServiceGrpc
    .newBlockingStub(channel)
    .withCallCredentials(credentials);

// 后续所有 RPC 自动携带元数据
stub.add(Empty.newBuilder().build());

⚠️ 注意事项：

元数据键名（如 "clientid"）不区分大小写，但建议全小写以符合 HTTP/2 header 规范；
若服务端期望二进制元数据（如带 -bin 后缀），请改用 Metadata.BINARY_STRING_MARSHALLER；
CallCredentials 是线程安全的，可复用；若需动态值（如 token 刷新），应在 applyRequestMetadata 内实时获取；
如遇 UNAUTHENTICATED 仍存在，请用 Wireshark 或 gRPC 的 NettyChannelBuilder 启用 usePlaintext(true).intercept(new LoggingClientInterceptor()) 查看实际发出的 headers。

该方案简洁、稳定、符合 gRPC 最佳实践，无需修改 stub 生成逻辑或引入额外依赖。