Spring Boot 如何整合 gRPC 实现高效 RPC 调用？

同样是内部服务调用，REST 接口返回 1KB 的 JSON 包体，gRPC 使用 Protobuf 往往只需几百字节，而且请求头压缩和二进制传输进一步降低了网络开销。在 Spring Boot 技术栈中，社区维护的 grpc-spring-boot-starter 已经把 gRPC Server 和 Client 的生命周期管理封装成自动配置，开发者可以把精力集中在 proto 契约和业务实现上。

下面从协议选型、工程搭建、核心代码到生产配置几个维度展开，目标是跑通一个可运行的 Spring Boot gRPC 示例。

一、为什么微服务内部调用值得从 REST 迁移到 gRPC

gRPC 并不是要取代所有 HTTP API，它在延迟敏感、吞吐要求高的内部服务间调用中优势更明显。HTTP/1.1 下的 REST 通常采用文本 JSON，每个请求都要重新经历 TCP 慢启动、头部未压缩、连接无法复用等问题；而 gRPC 基于 HTTP/2，支持多路复用、头部压缩和服务器推送，同一个 TCP 连接可以并发承载多个请求和响应，减少了握手和阻塞。

序列化层面，Protocol Buffers 的编码体积比 JSON 小得多。比如一个包含用户姓名和年龄的对象，JSON 要保留字段名、引号和逗号，而 Protobuf 使用字段编号和类型标记，同样的数据可能只有 JSON 的 30% 到 50%。同时 proto 文件即接口契约，生成代码后服务端和客户端都会在编译期检查类型和方法签名，避免很多手写 HTTP 调用时的拼写错误。

当然，gRPC 也有代价：浏览器不能直接调用、调试需要 grpcurl 等工具、文本可读性不如 JSON。因此一般建议网关对外保留 REST，内部 RPC 使用 gRPC，形成南北向 HTTP、东西向 gRPC 的混合架构。

二、Spring Boot 集成 gRPC 的基础工程搭建

首先在 Maven 工程中引入两个 starter，一个用于服务端，一个用于客户端。以 Spring Boot 2.x 与 grpc-spring-boot-starter 2.15.0 为例，核心依赖如下。

<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-server-spring-boot-starter</artifactId>
    <version>2.15.0.RELEASE</version>
</dependency>
<dependency>
    <groupId>net.devh</groupId>
    <artifactId>grpc-client-spring-boot-starter</artifactId>
    <version>2.15.0.RELEASE</version>
</dependency>

接着需要定义 .proto 文件，它是整个调用的唯一契约。下面创建一个 hello.proto，放在 src/main/proto 目录下。

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.example.grpc.demo";
option java_outer_classname = "HelloServiceProto";

service HelloService {
    rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

要让 Maven 在构建时生成对应的 Java 类，需要配置 protobuf 插件。常见的 protobuf-maven-plugin 会把生成代码输出到 target/generated-sources/protobuf/java，并被 IDE 自动识别。生成后的核心类包括 HelloServiceGrpc、HelloRequest 和 HelloReply。

在 application.yml 中给 gRPC 服务端指定监听端口，并为客户端定义目标地址。示例配置如下。

grpc:
  server:
    port: 9090
  client:
    helloService:
      address: static://localhost:9090
      negotiationType: PLAINTEXT

这里 negotiationType: PLAINTEXT 表示测试阶段不使用 TLS，生产环境建议改为 TLS 并配置证书。客户端地址中的 static:// 表示固定地址，也可以使用 discovery:// 对接注册中心做服务发现。

三、服务端与客户端的核心实现

服务端只需要继承生成的 HelloServiceGrpc.HelloServiceImplBase，并用 @GrpcService 注解暴露。这个注解会被 starter 扫描并注册到 gRPC Server 中，省去了手动 new Server 和 addService 的样板代码。

import net.devh.boot.grpc.server.service.GrpcService;
import com.example.grpc.demo.HelloRequest;
import com.example.grpc.demo.HelloReply;
import com.example.grpc.demo.HelloServiceGrpc;

@GrpcService
public class HelloServiceImpl extends HelloServiceGrpc.HelloServiceImplBase {

    @Override
    public void sayHello(HelloRequest request,
                         io.grpc.stub.StreamObserver<HelloReply> responseObserver) {
        String name = request.getName();
        HelloReply reply = HelloReply.newBuilder()
                .setMessage("Hello " + name + ", this is gRPC.")
                .build();
        responseObserver.onNext(reply);
        responseObserver.onCompleted();
    }
}

客户端通过 @GrpcClient 注解注入 Stub，这里的 helloService 对应配置文件中 grpc.client.helloService 的名称。BlockingStub 会同步阻塞直到返回结果，适合传统请求响应模式；如果需要异步，可以注入 FutureStub 或基于 StreamObserver 的异步 Stub。

import net.devh.boot.grpc.client.inject.GrpcClient;
import com.example.grpc.demo.HelloRequest;
import com.example.grpc.demo.HelloReply;
import com.example.grpc.demo.HelloServiceGrpc;
import org.springframework.stereotype.Service;

@Service
public class GrpcClientService {

    @GrpcClient("helloService")
    private HelloServiceGrpc.HelloServiceBlockingStub helloServiceStub;

    public String sendHello(String name) {
        HelloReply reply = helloServiceStub.sayHello(HelloRequest.newBuilder()
                .setName(name)
                .build());
        return reply.getMessage();
    }
}

启动 Spring Boot 后，服务端会在 9090 端口监听 gRPC 请求，客户端 Bean 初始化时自动创建 Channel 并连接目标地址。调用 sendHello 方法即可看到返回的字符串。整个流程不需要手动管理连接池和生命周期，starter 已通过 GrpcChannelFactory 完成这些工作。

四、拦截器、错误处理与生产注意事项

gRPC 的异常和 HTTP 状态码不同，使用 io.grpc.Status 表示调用结果。服务端如果直接抛出 RuntimeException，客户端只会收到 UNKNOWN 状态，丢失详细的错误信息。正确的做法是通过拦截器或业务代码主动关闭连接时传入状态描述。

下面是一个鉴权拦截器示例，它从 Metadata 中读取 authorization 请求头，验证失败时返回 UNAUTHENTICATED。

import io.grpc.*;

public class AuthInterceptor implements ServerInterceptor {
    @Override
    public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
            ServerCall<ReqT, RespT> call,
            Metadata headers,
            ServerCallHandler<ReqT, RespT> next) {
        String token = headers.get(Metadata.Key.of("authorization", Metadata.ASCII_STRING_MARSHALLER));
        if (token == null || !token.equals("secret-token")) {
            call.close(Status.UNAUTHENTICATED.withDescription("Invalid token"), new Metadata());
            return new ServerCall.Listener<ReqT>() {};
        }
        return next.startCall(call, headers);
    }
}

将这个拦截器注册到服务端也很简单，通常实现 GlobalServerInterceptorConfigurer 接口并返回拦截器列表，或者使用 @GrpcGlobalServerInterceptor 注解。

生产环境还需要关注 keepalive 参数、消息大小限制和死锁超时。例如在 application.yml 中可配置 grpc.server.keep-alive-time、grpc.server.max-inbound-message-size 等，避免长期空闲连接被防火墙断开或大消息被拒绝。另外 proto 文件一旦上线，字段编号不能随意修改，新增字段要使用新的编号并保持向后兼容。通过 grpc-health 探针可以接入 Kubernetes 健康检查，这些都是在真实部署中需要提前规划的内容。

从工程搭建到服务调用，Spring Boot 整合 gRPC 的关键在于 starter 自动配置和 proto 契约管理。相比手写 Netty 或直接使用 grpc-java，社区 starter 明显降低了接入成本。内部微服务如果正面临 REST 调用延迟高、接口文档漂移等问题，不妨按本文步骤搭建一个原型，用压测数据验证 gRPC 带来的收益。

Spring BootgRPCRPC修改时间：2026-10-05 02:08:09