本文详解在 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 CLIENT_ID_KEY
= Metadata.Key.of("clientid", Metadata.ASCII_STRING_MARSHALLER);
private static final Metadata.Key WORKER_ID_KEY
= Metadata.Key.of("workerid", Metadata.ASCII_STRING_MARSHALLER);
private static final Metadata.Key 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 框架据此判断兼容性策略
}
} 在业务代码中使用时，只需一行注入：
立即学习“Java免费学习笔记（深入）”；
// 构造凭证实例（值可动态传入）
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 生成逻辑或引入额外依赖。
