如何在ScalaPB的gRPC封装中处理自定义错误报告

ScalaPB完全支持通过io.grpc.Status传递自定义错误信息，核心是用失败的异步结果包装StatusRuntimeException，而非直接抛出不符合方法签名的异常，具体实现如下：

1. 构建自定义错误Status #

先通过Status类创建包含错误码、描述甚至附加信息的实例：

import io.grpc.{Status, StatusRuntimeException}
import com.google.rpc.Status as GrpcStatus

// 示例：构造参数错误的Status
val invalidArgStatus = Status.INVALID_ARGUMENT
  .withDescription("参数校验失败：用户ID必须为正整数")
  .withCause(new IllegalArgumentException("Invalid user ID"))

2. 在服务方法中返回错误结果 #

ScalaPB生成的gRPC服务方法分两种场景，对应不同的返回方式：

异步（Future/IO）场景 #

如果是基于Future或Fs2 IO的异步服务，直接返回失败的包装结果即可：

import scala.concurrent.Future
import your.generated.api.*
import cats.effect.IO

// Fs2 gRPC服务示例
class UserServiceImpl extends UserServiceFs2Grpc[IO, Unit] {
  override def getUser(request: GetUserRequest): IO[GetUserResponse] = {
    if (request.userId <= 0) {
      // 抛出包装了Status的异常
      val statusEx = Status.INVALID_ARGUMENT
        .withDescription("用户ID必须大于0")
        .asRuntimeException()
      IO.raiseError(statusEx)
    } else {
      // 正常业务逻辑
      IO.pure(GetUserResponse(id = request.userId, name = "张三"))
    }
  }
}

// 传统Future gRPC服务示例
class LegacyUserServiceImpl extends LegacyUserServiceGrpc.LegacyUserService {
  override def getUser(request: GetUserRequest): Future[GetUserResponse] = {
    if (request.userId <= 0) {
      val statusEx = Status.INVALID_ARGUMENT
        .withDescription("用户ID必须大于0")
        .asRuntimeException()
      Future.failed(statusEx)
    } else {
      Future.successful(GetUserResponse(id = request.userId, name = "张三"))
    }
  }
}

同步场景（较少使用） #

如果是同步服务方法，可以直接抛出StatusRuntimeException——虽然方法签名是返回响应类型，但gRPC底层会捕获该异常并转换为对应的错误响应：

class SyncUserServiceImpl extends SyncUserServiceGrpc.SyncUserService {
  override def getUser(request: GetUserRequest): GetUserResponse = {
    if (request.userId <= 0) {
      throw Status.INVALID_ARGUMENT
        .withDescription("用户ID必须大于0")
        .asRuntimeException()
    }
    GetUserResponse(id = request.userId, name = "张三")
  }
}

3. 客户端提取错误信息 #

客户端调用时，捕获StatusRuntimeException即可拿到完整的错误细节：

import io.grpc.StatusRuntimeException

// Future客户端示例
userClient.getUser(GetUserRequest(userId = -1)).onComplete {
  case Success(resp) => println(s"查询成功：${resp.name}")
  case Failure(ex: StatusRuntimeException) =>
    val status = ex.getStatus
    println(s"错误码：${status.getCode}，描述：${status.getDescription}")
    // 若有附加的结构化错误详情，可进一步解析
    val grpcStatus = io.grpc.protobuf.StatusProto.fromThrowable(ex)
    grpcStatus.getDetailsList.forEach(detail => println(s"错误详情：$detail"))
}

调试与生产环境建议 #

• 调试阶段可以返回详细的错误描述甚至堆栈信息，方便定位问题；
• 生产环境需避免泄露服务器内部细节（如具体异常类型、堆栈），仅保留业务相关的错误提示；
• 如需区分业务错误类型，可在withDescription中嵌入自定义错误码，或通过withMetadata携带结构化元数据。

内容的提问来源于stack exchange，提问作者Ayhon Iron