《Java 服务端通信工程》9.3 错误与超时映射

服务端业务异常
  -> google.rpc.Status { code, message, details[ErrorInfo, RetryInfo] }
  -> StatusProto.toStatusRuntimeException
  -> gRPC trailers（grpc-status-details-bin）
  -> 客户端 StatusProto.fromThrowable
  -> 网关 HTTP 状态码 + Retry-After + JSON error body

package com.plume.linkd.v3.api;

import com.google.protobuf.Any;
import com.google.protobuf.InvalidProtocolBufferException;
import com.google.rpc.ErrorInfo;
import com.google.rpc.RetryInfo;
import io.grpc.Status;
import io.grpc.StatusRuntimeException;
import io.grpc.protobuf.StatusProto;
import java.time.Duration;
import java.util.Map;

public final class GrpcErrors {

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

    private GrpcErrors() {
    }

    public static StatusRuntimeException bookNotFound(String isbn) {
        return error(Status.Code.NOT_FOUND, "BOOK_NOT_FOUND",
                "book not found: " + isbn, null, Map.of("isbn", isbn));
    }

    public static StatusRuntimeException stockConflict(String isbn, int expected, int actual) {
        return error(Status.Code.ABORTED, "STOCK_CONFLICT",
                "stock version conflict", null,
                Map.of("isbn", isbn,
                        "expected", Integer.toString(expected),
                        "actual", Integer.toString(actual)));
    }

    public static StatusRuntimeException rateLimited(Duration retryAfter) {
        return error(Status.Code.RESOURCE_EXHAUSTED, "RATE_LIMITED",
                "rate limit exceeded", retryAfter,
                Map.of("limit", "200", "burst", "400"));
    }

    public static StatusRuntimeException deadlineExceeded(String detail) {
        return error(Status.Code.DEADLINE_EXCEEDED, "DEADLINE_EXCEEDED",
                detail, null, Map.of());
    }

    public static StatusRuntimeException upstreamUnavailable(String detail) {
        return error(Status.Code.UNAVAILABLE, "UPSTREAM_UNAVAILABLE",
                detail, null, Map.of());
    }

    public static StatusRuntimeException tenantForbidden(String tenant) {
        return error(Status.Code.PERMISSION_DENIED, "TENANT_FORBIDDEN",
                "tenant forbidden", null, Map.of("tenant", tenant));
    }

    private static StatusRuntimeException error(Status.Code code, String reason,
                                                String message, Duration retryAfter,
                                                Map<String, String> metadata) {
        ErrorInfo.Builder info = ErrorInfo.newBuilder()
                .setReason(reason)
                .setDomain(DOMAIN)
                .putAllMetadata(metadata);
        com.google.rpc.Status.Builder status = com.google.rpc.Status.newBuilder()
                .setCode(code.value())
                .setMessage(message)
                .addDetails(Any.pack(info.build()));
        if (retryAfter != null) {
            com.google.protobuf.Duration delay = com.google.protobuf.Duration.newBuilder()
                    .setSeconds(retryAfter.getSeconds())
                    .setNanos(retryAfter.getNano())
                    .build();
            status.addDetails(Any.pack(RetryInfo.newBuilder()
                    .setRetryDelay(delay)
                    .build()));
        }
        return StatusProto.toStatusRuntimeException(status.build());
    }

    public static int httpStatus(Status.Code code) {
        return switch (code) {
            case OK -> 200;
            case INVALID_ARGUMENT -> 400;
            case UNAUTHENTICATED -> 401;
            case PERMISSION_DENIED -> 403;
            case NOT_FOUND -> 404;
            case ALREADY_EXISTS, ABORTED -> 409;
            case FAILED_PRECONDITION -> 412;
            case RESOURCE_EXHAUSTED -> 429;
            case CANCELLED -> 499;
            case UNIMPLEMENTED -> 501;
            case UNAVAILABLE -> 503;
            case DEADLINE_EXCEEDED -> 504;
            default -> 500;
        };
    }

    public static Status.Code fromHttp(int status) {
        return switch (status) {
            case 400 -> Status.Code.INVALID_ARGUMENT;
            case 401 -> Status.Code.UNAUTHENTICATED;
            case 403 -> Status.Code.PERMISSION_DENIED;
            case 404 -> Status.Code.NOT_FOUND;
            case 409 -> Status.Code.ABORTED;
            case 412 -> Status.Code.FAILED_PRECONDITION;
            case 429 -> Status.Code.RESOURCE_EXHAUSTED;
            case 500 -> Status.Code.INTERNAL;
            case 501 -> Status.Code.UNIMPLEMENTED;
            case 502, 503 -> Status.Code.UNAVAILABLE;
            case 504 -> Status.Code.DEADLINE_EXCEEDED;
            default -> status >= 500 ? Status.Code.UNAVAILABLE : Status.Code.UNKNOWN;
        };
    }

    public static String reason(Throwable failure) {
        ErrorInfo info = detail(failure, ErrorInfo.class);
        return info == null ? "" : info.getReason();
    }

    public static long retryAfterSeconds(Throwable failure) {
        RetryInfo info = detail(failure, RetryInfo.class);
        if (info == null) {
            return 0L;
        }
        com.google.protobuf.Duration delay = info.getRetryDelay();
        long nanos = delay.getSeconds() * 1_000_000_000L + delay.getNanos();
        return Math.max(1L, (nanos + 999_999_999L) / 1_000_000_000L);
    }

    private static <T extends com.google.protobuf.Message> T detail(
            Throwable failure, Class<T> type) {
        com.google.rpc.Status status = StatusProto.fromThrowable(failure);
        if (status == null) {
            return null;
        }
        for (Any any : status.getDetailsList()) {
            if (!any.is(type)) {
                continue;
            }
            try {
                return any.unpack(type);
            } catch (InvalidProtocolBufferException e) {
                return null;
            }
        }
        return null;
    }
}

public void getBook(GetBookRequest request, StreamObserver<Book> observer) {
    try {
        Book book = repository.find(request.getIsbn());
        if (book == null) {
            throw GrpcErrors.bookNotFound(request.getIsbn());
        }
        observer.onNext(book);
        observer.onCompleted();
    } catch (StatusRuntimeException e) {
        observer.onError(e);
    }
}

try {
    return stub.getBook(request);
} catch (StatusRuntimeException e) {
    com.google.rpc.Status status = StatusProto.fromThrowable(e);
    String reason = status == null ? "" : reasonOf(status);
    if ("BOOK_NOT_FOUND".equals(reason)) {
        throw new BookMissingException(request.getIsbn(), e);
    }
    throw e;
}

package com.plume.linkd.v3.gateway;

import com.plume.linkd.v3.api.GrpcErrors;
import com.sun.net.httpserver.HttpExchange;
import io.grpc.Status;
import io.grpc.StatusRuntimeException;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.charset.StandardCharsets;

public final class HttpErrorMapper {

    public void write(HttpExchange exchange, Throwable failure) throws IOException {
        StatusRuntimeException error = failure instanceof StatusRuntimeException sre
                ? sre
                : Status.INTERNAL.withDescription("internal error").asRuntimeException();
        Status.Code code = error.getStatus().getCode();
        String reason = GrpcErrors.reason(error);
        if (reason.isEmpty()) {
            reason = code.name();
        }
        long retryAfter = GrpcErrors.retryAfterSeconds(error);
        String body = "{\"error\":\"" + reason + "\",\"code\":\"" + code.name() + "\"}";
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().set("Content-Type", "application/json; charset=utf-8");
        if (retryAfter > 0) {
            exchange.getResponseHeaders().set("Retry-After", Long.toString(retryAfter));
        }
        exchange.sendResponseHeaders(GrpcErrors.httpStatus(code), bytes.length);
        try (OutputStream out = exchange.getResponseBody()) {
            out.write(bytes);
        }
    }
}