《Java 服务端通信工程》1.2 错误模型与状态码

message ErrorInfo {
  string reason = 1;
  string domain = 2;
  map<string, string> metadata = 3;
}

package com.plume.linkd.v3.core.error;

import com.google.protobuf.Any;
import com.google.rpc.ErrorInfo;
import com.plume.linkd.v3.api.ErrorReasons;
import io.grpc.Status;
import io.grpc.StatusRuntimeException;
import io.grpc.protobuf.StatusProto;

import java.util.Map;
import java.util.Set;

public record RpcError(Status.Code code, String reason, String message, boolean retryable) {

    public static final String DOMAIN = "linkd.v3";

    private static final Set<String> RETRYABLE_REASONS = Set.of(
            ErrorReasons.STOCK_CONFLICT, ErrorReasons.RATE_LIMITED,
            ErrorReasons.UPSTREAM_UNAVAILABLE);

    public static RpcError bookNotFound(String isbn) {
        return new RpcError(Status.Code.NOT_FOUND, ErrorReasons.BOOK_NOT_FOUND,
                "book not found: " + isbn, false);
    }

    public static RpcError stockConflict(String isbn, long expectedVersion) {
        return new RpcError(Status.Code.ABORTED, ErrorReasons.STOCK_CONFLICT,
                "stock version conflict: " + expectedVersion, true);
    }

    public static RpcError rateLimited(int retryAfterMillis) {
        return new RpcError(Status.Code.RESOURCE_EXHAUSTED, ErrorReasons.RATE_LIMITED,
                "rate limited, retry after " + retryAfterMillis + " ms", true);
    }

    public static RpcError upstreamUnavailable(String target, Throwable cause) {
        return new RpcError(Status.Code.UNAVAILABLE, ErrorReasons.UPSTREAM_UNAVAILABLE,
                "upstream " + target + " unavailable: " + cause.getClass().getSimpleName(), true);
    }

    public StatusRuntimeException toException(Map<String, String> metadata) {
        ErrorInfo.Builder info = ErrorInfo.newBuilder()
                .setReason(reason)
                .setDomain(DOMAIN);
        metadata.forEach(info::putMetadata);
        com.google.rpc.Status status = com.google.rpc.Status.newBuilder()
                .setCode(code.value())
                .setMessage(message)
                .addDetails(Any.pack(info.build()))
                .build();
        return StatusProto.toStatusRuntimeException(status);
    }

    public static RpcError from(Throwable throwable) {
        com.google.rpc.Status status = StatusProto.fromThrowable(throwable);
        if (status != null) {
            for (Any detail : status.getDetailsList()) {
                if (detail.is(ErrorInfo.class)) {
                    try {
                        ErrorInfo info = detail.unpack(ErrorInfo.class);
                        Status.Code code = Status.fromCodeValue(status.getCode()).getCode();
                        boolean retryable = RETRYABLE_REASONS.contains(info.getReason());
                        return new RpcError(code, info.getReason(), status.getMessage(), retryable);
                    } catch (com.google.protobuf.InvalidProtocolBufferException ignored) {
                        break;
                    }
                }
            }
        }
        Status fallback = Status.fromThrowable(throwable);
        String description = fallback.getDescription() == null ? "" : fallback.getDescription();
        return new RpcError(fallback.getCode(), fallback.getCode().name(), description,
                fallback.getCode() == Status.Code.UNAVAILABLE);
    }
}

package com.plume.linkd.v3.demo;

import com.plume.linkd.v3.api.Book;
import com.plume.linkd.v3.api.GetBookRequest;
import com.plume.linkd.v3.api.LibraryMethods;
import com.plume.linkd.v3.core.error.RpcError;
import io.grpc.CallOptions;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.Server;
import io.grpc.ServerBuilder;
import io.grpc.ServerServiceDefinition;
import io.grpc.StatusRuntimeException;
import io.grpc.stub.ClientCalls;
import io.grpc.stub.ServerCalls;

import java.util.Map;

public final class ErrorRoundTrip {

    public static void main(String[] args) throws Exception {
        ServerServiceDefinition service = ServerServiceDefinition.builder("plume.linkd.v3.Library")
                .addMethod(LibraryMethods.GET_BOOK, ServerCalls.asyncUnaryCall((request, observer) -> {
                    if (!"42".equals(request.getIsbn())) {
                        observer.onError(RpcError.bookNotFound(request.getIsbn())
                                .toException(Map.of("isbn", request.getIsbn())));
                        return;
                    }
                    observer.onNext(Book.newBuilder().setIsbn("42").setTitle("book:42").build());
                    observer.onCompleted();
                }))
                .build();

        Server server = ServerBuilder.forPort(0).addService(service).build().start();
        ManagedChannel channel = ManagedChannelBuilder
                .forAddress("127.0.0.1", server.getPort())
                .usePlaintext()
                .build();
        try {
            try {
                ClientCalls.blockingUnaryCall(channel, LibraryMethods.GET_BOOK,
                        CallOptions.DEFAULT, GetBookRequest.newBuilder().setIsbn("99").build());
            } catch (StatusRuntimeException e) {
                RpcError error = RpcError.from(e);
                System.out.println("code=" + error.code());
                System.out.println("reason=" + error.reason());
                System.out.println("retryable=" + error.retryable());
            }
        } finally {
            channel.shutdownNow();
            server.shutdownNow();
        }
    }
}

code=NOT_FOUND
reason=BOOK_NOT_FOUND
retryable=false

RATE_LIMITED + RetryInfo.retry_delay = 0.2s
客户端退避 = max(本地计算 20ms, 服务端建议 200ms) × jitter(0.8–1.2)