Java gRPC Server服务暴露异常：添加顺序影响服务可用性

问题背景 #

我正在构建一个需要暴露多个服务的gRPC Server，启动代码如下：

Server server = ServerBuilder
        .forPort(8980)
        .addService(new GrpcService1())
        .addService(new GrpcService2())
        .addService(new GrpcService3())
        .addService(ProtoReflectionService.newInstance())
        .build();

遇到的异常情况：GrpcService1和GrpcService2存在覆盖冲突——先添加GrpcService1再添加GrpcService2时，后者无法被正常调用；反之前者无法调用，GrpcService3始终正常工作。

具体表现 #

• grpcurl调用报错：调用后添加的服务RPC时提示服务未暴露：

$ grpcurl -plaintext \
  localhost:8980 \
  specs.grpc_service2.GrpcService2/someRpc
Error invoking method "specs.grpc_service2.GrpcService2/someRpc": target server does not expose service "specs.grpc_service2.GrpcService2"

• 服务列表显示正常：执行grpcurl list能列出所有服务：

$ grpcurl -plaintext localhost:8980 list
grpc.reflection.v1alpha.ServerReflection
specs.grpc_service3.GrpcService3
specs.grpc_service2.GrpcService2
specs.grpc_service1.GrpcService1

• gRPC UI无服务展示：后添加的服务不会出现在gRPC UI的可用服务列表中。

冲突服务的Proto定义 #

src/main/proto/grpc_service1/services.proto（GrpcService1使用）：

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.service.internal_query_api";
option java_outer_classname = "InternalQueryGrpcProto";

package specs.grpc_service1;

service GrpcService1 {
...

src/main/proto/grpc_service2/services.proto（GrpcService2使用）：

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.service.matform.api";
option java_outer_classname = "MatformGrpcProto";

package specs.grpc_service2;

service GrpcService2 {
...

核心原因分析 #

gRPC Java中，ServerBuilder.addService默认以服务描述符的名称作为唯一标识，若两个服务的描述符名称重复，后添加的服务会直接覆盖先添加的。从Proto定义看包名和服务名均不重复，大概率是Java代码生成环节或服务实现类存在问题：

1. 自动生成的服务ImplBase类返回了重复的服务描述符
2. Protobuf编译插件配置错误，导致两个服务的生成类被互相覆盖
3. 反射服务未正确识别所有服务的元数据

排查与解决步骤 #

步骤1：验证服务描述符名称 #

在服务启动前打印两个服务的描述符名称，确认是否重复：

GrpcService1 service1 = new GrpcService1();
GrpcService2 service2 = new GrpcService2();
System.out.println("Service1 descriptor name: " + service1.bindService().getServiceDescriptor().getName());
System.out.println("Service2 descriptor name: " + service2.bindService().getServiceDescriptor().getName());

若输出名称相同，说明代码生成环节存在问题，需重新检查Proto文件和编译配置。

步骤2：检查Protobuf编译配置 #

• 确认Maven/Gradle的Protobuf插件是否正确识别所有Proto文件，避免编译时遗漏或覆盖：
  以Gradle为例，确保配置包含所有子目录的Proto文件：

  sourceSets {
      main {
          proto {
              srcDir 'src/main/proto'
              include '**/*.proto'
          }
      }
  }
  

• 清理项目编译目录（如target/build），重新编译生成Java代码，避免旧文件残留覆盖新生成类。

步骤3：手动构建服务定义（强制区分） #

若服务描述符名称重复，可手动构建ServerServiceDefinition，指定唯一服务名称：

Server server = ServerBuilder
        .forPort(8980)
        // 手动构建GrpcService1的服务定义
        .addService(ServerServiceDefinition.builder(specs.grpc_service1.GrpcService1Grpc.SERVICE_NAME)
                .addMethod(specs.grpc_service1.GrpcService1Grpc.getSomeMethod(), service1::someMethod)
                // 依次添加该服务的所有RPC方法
                .build())
        // 手动构建GrpcService2的服务定义
        .addService(ServerServiceDefinition.builder(specs.grpc_service2.GrpcService2Grpc.SERVICE_NAME)
                .addMethod(specs.grpc_service2.GrpcService2Grpc.getSomeRpcMethod(), service2::someRpc)
                // 依次添加该服务的所有RPC方法
                .build())
        .addService(new GrpcService3())
        .addService(ProtoReflectionService.newInstance())
        .build();

步骤4：修复反射服务配置 #

手动将所有服务传入反射服务，确保它能正确识别所有服务元数据：

List<ServerServiceDefinition> services = Arrays.asList(
        new GrpcService1().bindService(),
        new GrpcService2().bindService(),
        new GrpcService3().bindService()
);
Server server = ServerBuilder
        .forPort(8980)
        .addAllServices(services)
        .addService(ProtoReflectionService.newInstance(services))
        .build();

内容的提问来源于stack exchange，提问作者Gerardo Figueroa