gRPC Java服务端需主动抛StatusRuntimeException或用ServerInterceptor转换异常，否则unchecked异常默认转为INTERNAL且丢失信息；客户端可直接解析StatusRuntimeException获取精准状态码与描述。
在 gRPC Java 服务端（基于 io.grpc），直接用 throw new RuntimeException() 或其他 unchecked 异常，**不会自动转成 StatusRuntimeException 透传给客户端**。gRPC 默认会把未捕获的 unchecked 异常包装为 INTERNAL 状态（500）并丢失原始异常信息。要实现「按需将特定异常精准转为指定 gRPC Status 并透传」，核心方式是：**在业务逻辑中主动 throw StatusRuntimeException，或通过 ServerInterceptor 统一拦截转换。**
手动抛出 StatusRuntimeException（推荐，最直接可控）
这是最清晰、最易调试的方式。你在 service 实现方法里，根据业务逻辑判断异常情况，直接构造并抛出 StatusRuntimeException。
示例：
public class UserServiceImpl extends UserGrpc.UserImplBase {
@Override
public void getUser(GetUserRequest request, StreamObserver<User> responseObserver) {
try {
if (request.getId() <= 0) {
// 主动抛出 INVALID_ARGUMENT，并附带详细消息
throw Status.INVALID_ARGUMENT
.withDescription("user id must be positive")
.augmentDescription("received: " + request.getId())
.asRuntimeException();
}
User user = loadUser(request.getId());
responseObserver.onNext(user);
responseObserver.onCompleted();
} catch (UserNotFoundException e) {
// 转换为 NOT_FOUND
responseObserver.onError(
Status.NOT_FOUND.withDescription(e.getMessage()).asRuntimeException()
);
} catch (Exception e) {
// 兜底：记录日志后转为 INTERNAL
log.error("Unexpected error in getUser", e);
responseObserver.onError(
Status.INTERNAL.withDescription("internal server error").asRuntimeException()
);
}
}
}
关键点：
立即学习“Java免费学习笔记（深入）”；
- 使用
Status.xxx.withDescription(...).asRuntimeException()构造，确保客户端收到的是标准StatusRuntimeException； - 务必调用
responseObserver.onError(...)（异步模式下）或直接throw（同步阻塞模式下，gRPC 框架会自动捕获并转为 onError）； - 避免在
try块外 throw 普通异常，否则会被框架兜底为INTERNAL。
使用 ServerInterceptor 统一异常翻译（适合全局策略）
如果你希望集中管理异常映射（比如所有 IllegalArgumentException → INVALID_ARGUMENT），可实现 ServerInterceptor：
deep-java-review
下载
Java项目代码review工具。分析Git变更+完整调用链路上下文，推断业务需求，进行多维度评分和分类汇总，生成完整PRD文档。包含细粒度Java代码审查清单（Null安全、异常处理、Streams、并发、equals/hashCode、资源管理、API设计、性能、MyBatis/ORM、事务边界、SQL/DD...
public class ExceptionToStatusInterceptor implements ServerInterceptor {
@Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
ServerCall<ReqT, RespT> call,
Metadata headers,
ServerCallHandler<ReqT, RespT> next) {
ServerCall.Listener<ReqT> delegate = next.startCall(call, headers);
return new ForwardingServerCallListener.SimpleForwardingServerCallListener<>(delegate) {
@Override
public void onHalfClose() {
try {
super.onHalfClose();
} catch (Exception e) {
handleError(call, e);
}
}
@Override
public void onCancel() {
super.onCancel();
}
@Override
public void onComplete() {
super.onComplete();
}
@Override
public void onReady() {
super.onReady();
}
private void handleError(ServerCall<?, ?> call, Throwable t) {
Status status = Status.INTERNAL;
if (t instanceof IllegalArgumentException || t instanceof NullPointerException) {
status = Status.INVALID_ARGUMENT.withDescription(t.getMessage());
} else if (t instanceof UserNotFoundException) {
status = Status.NOT_FOUND.withDescription(t.getMessage());
} else if (t instanceof StatusRuntimeException) {
status = ((StatusRuntimeException) t).getStatus();
}
call.close(status, new Metadata()); // 主动关闭 call 并返回状态
}
};
}
}
注册方式（以 NettyServerBuilder 为例）：
Server server = NettyServerBuilder.forPort(8080)
.addService(new UserServiceImpl())
.intercept(new ExceptionToStatusInterceptor())
.build();
注意：
- 该拦截器需在所有业务逻辑执行完毕后才捕获异常（例如在
onHalfClose中），实际更稳妥的做法是包装ServerCallHandler的startCall返回的 listener，重写其onError方法； - 拦截器中不要吞掉异常而不 close call，否则客户端会 hang；
- 优先级低于手动 throw —— 如果你已在业务方法里 throw 了
StatusRuntimeException，拦截器通常无需再处理它。
不建议依赖的“自动转换”行为
以下做法**不可靠或不推荐**：
- 直接
throw new IllegalArgumentException("xxx")：gRPC 默认转为INTERNAL，且无 stack trace 透传（除非开启 debug 模式）； - 使用
@ExceptionHandler（Spring Boot 场景）：gRPC 不走 Spring MVC 的异常处理器链，无效； - 试图在
ServerCall.close()之外抛异常：可能被线程池吞掉或触发未定义行为。
客户端如何接收和解析
客户端收到的始终是 StatusRuntimeException，可安全 cast 并提取状态：
try {
User user = blockingStub.getUser(GetUserRequest.newBuilder().setId(-1).build());
} catch (StatusRuntimeException e) {
Status status = e.getStatus();
System.out.println("Code: " + status.getCode()); // INVALID_ARGUMENT
System.out.println("Desc: " + status.getDescription()); // "user id must be positive"
// 可选：检查是否为预期错误
if (status.getCode() == Status.Code.INVALID_ARGUMENT) {
handleInvalidInput(e);
}
}
gRPC 客户端天然支持这种状态透传，无需额外配置。
