《Java 服务端通信工程》附录 A 通信 API 速查

这张表怎么用

这不是教程，是把正文里出现过的类和方法压成一张可查的表。写 linkd-v3 时先在这里定位类，再回到对应章节看为什么这样用。

约定：

• 版本固定为 JDK 25、gRPC-Java 1.76.0、Protobuf 4.33.2。方法签名省略返回值类型，只保留参数；需要返回值时看「用途」列。
• 「包」列只写类所在的包，import 时补全类名。gRPC 的类集中在 io.grpc 与其子包，Protobuf 在 com.google.protobuf 与 com.google.rpc。
• 「章节」指向正文节号，附录不重复解释机制。
• 表中 ... 表示可变参数或省略的重载，不是可以照抄的省略号。
• 只列白名单内的 API；不在表里的类，先确认版本再使用。

包名先记四个容易混的：

ManagedChannel 是接口，不是 Netty 的类；StreamObserver 在 io.grpc.stub 下，import 写错是最常见的编译错误之一。

gRPC 核心：Channel、Server 与 Stub

Channel 是客户端的长生命周期对象，Server 是服务端的长生命周期对象，Stub 是每次调用前的轻量视图。三者都不要在请求里反复创建。

ManagedChannelBuilder.build() 不建立连接，第一次调用或 getState(true) 才会。启动自检如果只 build 不调用，看到的「成功」没有意义。

调用、拦截器与流式

拦截器分服务端和客户端两套，方法签名对称但泛型位置不同。Forwarding* 是包装调用的入口，不要直接实现 ServerCall 的全部方法。

ServerCall.close 只能调用一次，重复调用会抛 IllegalStateException。在拦截器里提前关闭后，不要再把调用交给 delegate；13.2 的 abort 就是直接返回空 listener。

Metadata、Deadline 与 Context

Metadata 是 ASCII 键值对加二进制值的容器，key 必须通过 Metadata.Key.of 创建，不能直接用字符串。Deadline 是绝对时间点，Context 是调用范围内的隐式状态。

Deadline.timeRemaining 可能返回负数，表示已经过期；不要直接用返回值算 sleep，先判断 isExpired()。Context.attach() 必须与 detach() 配对，否则线程复用时上下文会串。

Status 与错误详情

Status 是 gRPC 的错误模型。StatusRuntimeException 是同步调用抛出的形式，StatusException 是异步/流式常用的受检形式。错误原因码放在 ErrorInfo 里，通过 StatusProto 与 Status 互转。

Status.withCause 只影响本地日志，不会把堆栈序列化给对端。要把原因码传给客户端，必须用 ErrorInfo 加 StatusProto。

Protobuf 与 JSON

Protobuf 的消息对象不可变，修改要通过 toBuilder()。JsonFormat 用于调试和 HTTP 网关的 JSON 转换，不适合作为 gRPC 的线格式。

JsonFormat 默认不输出默认值字段，网关如果直接透传，客户端可能看不到 stock: 0。需要显式开启 includingDefaultValueFields，并注意这与 proto3 的「默认值不序列化」语义不同。

JDK HttpClient

网关调用 libraryd 用 JDK 自带客户端，不引入额外 HTTP 库。HttpClient 是线程安全的，应该复用；HttpRequest 是每次请求构造的不可变对象。

HttpClient.send 会阻塞调用线程。在 gRPC 服务端直接调用它，会占住服务线程；要么用 sendAsync，要么把阻塞调用移到专用执行器。connectTimeout 和 HttpRequest.timeout 是两个不同的超时，前者管建连，后者管整个请求。

HTTP server 与并发

com.sun.net.httpserver.HttpServer 适合写测试替身和轻量网关，不适合高并发生产服务。并发工具用来实现限流、Bulkhead 和延迟统计。

HttpServer.stop(delay) 的 delay 是秒，不是毫秒；传 0 会立即关闭，可能截断在途响应。Executors.newVirtualThreadPerTaskExecutor() 适合阻塞调用多的场景，但不适合 CPU 密集任务，也不解决下游容量问题。

在 linkd-v3 里落地

一次带元数据、deadline 和错误映射的一元调用：

package com.plume.linkd.v3.gateway;

import com.plume.linkd.v3.api.Book;
import com.plume.linkd.v3.api.GetBookRequest;
import com.plume.linkd.v3.api.LibraryGrpc;
import io.grpc.CallOptions;
import io.grpc.Channel;
import io.grpc.ClientCall;
import io.grpc.ClientInterceptor;
import io.grpc.ForwardingClientCall;
import io.grpc.ManagedChannel;
import io.grpc.Metadata;
import io.grpc.MethodDescriptor;

import java.util.concurrent.TimeUnit;

public final class UnaryCallExample {

    private static final Metadata.Key<String> REQUEST_ID =
            Metadata.Key.of("x-request-id", Metadata.ASCII_STRING_MARSHALLER);

    public static Book fetch(ManagedChannel channel, String isbn, String requestId) {
        ClientInterceptor attach = new ClientInterceptor() {
            @Override
            public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
                    MethodDescriptor<ReqT, RespT> method, CallOptions options, Channel next) {
                return new ForwardingClientCall.SimpleForwardingClientCall<>(
                        next.newCall(method, options)) {
                    @Override
                    public void start(Listener<RespT> listener, Metadata headers) {
                        headers.put(REQUEST_ID, requestId);
                        super.start(listener, headers);
                    }
                };
            }
        };
        LibraryGrpc.LibraryBlockingStub stub = LibraryGrpc.newBlockingStub(channel)
                .withInterceptors(attach)
                .withDeadlineAfter(300, TimeUnit.MILLISECONDS);
        return stub.getBook(GetBookRequest.newBuilder().setIsbn(isbn).build());
    }
}

带 ErrorInfo 的错误构造与解析：

package com.plume.linkd.v3.core;

import com.google.protobuf.Any;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.rpc.ErrorInfo;
import io.grpc.Status;
import io.grpc.StatusRuntimeException;
import io.grpc.protobuf.StatusProto;

public final class RpcErrors {

    public static StatusRuntimeException bookNotFound(String isbn) {
        ErrorInfo info = ErrorInfo.newBuilder()
                .setReason("BOOK_NOT_FOUND")
                .setDomain("library")
                .putMetadata("isbn", isbn)
                .build();
        com.google.rpc.Status status = com.google.rpc.Status.newBuilder()
                .setCode(Status.Code.NOT_FOUND.value())
                .setMessage("book not found")
                .addDetails(Any.pack(info))
                .build();
        return StatusProto.toStatusRuntimeException(status);
    }

    public static String reasonOf(Throwable error) {
        com.google.rpc.Status status = StatusProto.fromThrowable(error);
        if (status == null) {
            return "UNKNOWN";
        }
        for (Any detail : status.getDetailsList()) {
            if (detail.is(ErrorInfo.class)) {
                try {
                    return detail.unpack(ErrorInfo.class).getReason();
                } catch (InvalidProtocolBufferException e) {
                    return "MALFORMED_ERROR_INFO";
                }
            }
        }
        return "UNKNOWN";
    }
}

Any.is(Class) 与 Any.unpack(Class) 是 Protobuf 的标准方法；原因码放在 ErrorInfo 里，而不是拼在 Status.description 字符串里，客户端才能稳定解析。

常见错误与边界

错误一：ManagedChannel 每次请求新建。 连接、TLS 握手、NameResolver 全部重来，延迟和 fd 都会失控。Channel 应该是进程级单例。

错误二：Server.shutdownNow() 当默认关闭。 在途请求被取消，客户端看到 UNAVAILABLE。默认用 shutdown() 加 awaitTermination。

错误三：Metadata key 用字符串直接构造。 Metadata.Key 必须通过 of 创建，直接 put("x-request-id", ...) 编译不过。

错误四：把 Status.description 当原因码。 描述是给人看的，可能变化；原因码要放 ErrorInfo.reason。

错误五：在服务线程里调用 HttpClient.send。 阻塞会占住 gRPC 执行线程，高并发时线程池迅速耗尽。用 sendAsync 或专用执行器。

错误六：HttpServer.stop(0)。 参数是秒，0 表示立即关闭，会截断在途响应。

边界：本表只覆盖卷三用到的 API。 gRPC 还有 NameResolver、LoadBalancer、Credentials 等接口，正文按需展开；不在表里的方法，使用前先查 1.76.0 的 javadoc。

边界：版本差异会改变默认值。 消息大小上限、压缩算法、keepalive 默认值都可能随版本变化；升级 gRPC 时重新核对本文的默认参数。

小结

• Channel 与 Server 是长生命周期对象，Stub 是轻量视图；Channel 不要每次请求新建。
• 拦截器用 Forwarding* 包装，ServerCall.close 只能调用一次。
• Metadata key 必须用 Key.of 创建；Deadline 是绝对时间点，剩余时间可能为负。
• 原因码放 ErrorInfo，用 StatusProto 与 Status 互转；description 不是稳定契约。
• JsonFormat 默认不输出默认值字段，网关透传时要显式开启。
• HttpClient 复用、sendAsync 优先；HttpServer.stop 的参数是秒。
• 并发工具按场景选：Semaphore 做 Bulkhead、LongAdder 做计数、虚拟线程处理阻塞调用。