Introduction

Spring Boot works well with gRPC when you treat HTTP and RPC as separate concerns: Spring Boot manages application wiring, configuration, and lifecycle, while gRPC and Protobuf define the contract and transport for service-to-service calls. The basic integration pattern is to generate Java classes from a .proto file, implement the service in a Spring-managed bean, and run a gRPC server alongside the rest of the Boot application.

Define the Contract in Protobuf First

With gRPC, the API contract starts in a .proto file rather than a controller interface.

1syntax = "proto3";
2
3option java_multiple_files = true;
4option java_package = "com.example.hello";
5
6service GreetingService {
7  rpc SayHello (HelloRequest) returns (HelloReply);
8}
9
10message HelloRequest {
11  string name = 1;
12}
13
14message HelloReply {
15  string message = 1;
16}

This file does two jobs:

• defines the request and response schema
• defines the gRPC service method signatures

The generated Java code becomes the common contract between server and client.

Generate Java Stubs from the .proto File

A common Maven setup uses the protobuf and gRPC code generation plugins.

1<dependencies>
2  <dependency>
3    <groupId>org.springframework.boot</groupId>
4    <artifactId>spring-boot-starter</artifactId>
5  </dependency>
6  <dependency>
7    <groupId>io.grpc</groupId>
8    <artifactId>grpc-netty-shaded</artifactId>
9    <version>1.63.0</version>
10  </dependency>
11  <dependency>
12    <groupId>io.grpc</groupId>
13    <artifactId>grpc-protobuf</artifactId>
14    <version>1.63.0</version>
15  </dependency>
16  <dependency>
17    <groupId>io.grpc</groupId>
18    <artifactId>grpc-stub</artifactId>
19    <version>1.63.0</version>
20  </dependency>
21</dependencies>

The exact plugin block can vary by project, but the goal is always the same: compile .proto definitions into Java message classes and service stubs during the build.

Implement the gRPC Service as a Spring Bean

Once the stubs are generated, implement the server side. The generated base class gives you strongly typed request and response objects.

1package com.example.hello;
2
3import io.grpc.stub.StreamObserver;
4import net.devh.boot.grpc.server.service.GrpcService;
5
6@GrpcService
7public class GreetingServiceImpl extends GreetingServiceGrpc.GreetingServiceImplBase {
8    @Override
9    public void sayHello(HelloRequest request, StreamObserver<HelloReply> responseObserver) {
10        HelloReply reply = HelloReply.newBuilder()
11                .setMessage("Hello, " + request.getName())
12                .build();
13
14        responseObserver.onNext(reply);
15        responseObserver.onCompleted();
16    }
17}

This example uses a Spring Boot gRPC starter annotation to register the service. That keeps the implementation aligned with the rest of the Boot app instead of wiring the gRPC server manually.

Configure Spring Boot and gRPC Side by Side

Spring Boot still manages configuration through application.yml or application.properties. A simple setup might look like this:

1grpc:
2  server:
3    port: 9090
4
5spring:
6  application:
7    name: greeting-service

This lets the Boot application own environment-specific settings while gRPC listens on its own port.

If the same app also exposes REST endpoints, it is common to run Spring MVC on one port and gRPC on another so the protocols stay clearly separated.

Call the Service from a Client

The generated blocking or async stubs make client calls straightforward.

1import io.grpc.ManagedChannel;
2import io.grpc.ManagedChannelBuilder;
3
4public class GreetingClient {
5    public static void main(String[] args) {
6        ManagedChannel channel = ManagedChannelBuilder
7                .forAddress("localhost", 9090)
8                .usePlaintext()
9                .build();
10
11        GreetingServiceGrpc.GreetingServiceBlockingStub stub =
12                GreetingServiceGrpc.newBlockingStub(channel);
13
14        HelloReply reply = stub.sayHello(
15                HelloRequest.newBuilder().setName("Spring Boot").build()
16        );
17
18        System.out.println(reply.getMessage());
19        channel.shutdown();
20    }
21}

That is one of the main benefits of Protobuf contracts: the client and server stay type-safe without handwritten JSON parsing.

Keep Responsibilities Clean

Spring Boot and gRPC complement each other best when their responsibilities stay clear:

• Spring Boot handles dependency injection, configuration, metrics, and application lifecycle
• Protobuf defines schemas and contracts
• gRPC handles RPC transport and generated client or server APIs

Trying to force gRPC into a controller-like REST mental model usually makes the design harder, not easier.

Common Pitfalls

The biggest mistake is treating .proto files as a side detail instead of the source of truth for the service contract. Another common issue is forgetting that gRPC uses its own transport and port, so a Spring MVC setup does not automatically expose those services. Developers also sometimes mix generated code into source control awkwardly instead of letting the build create it reliably. Finally, if REST and gRPC live in the same app, keep the interfaces clearly separated so clients do not have to guess which protocol a given endpoint uses.

Summary

• Use Protobuf to define the service contract first.
• Generate Java stubs during the build rather than writing request or response classes by hand.
• Implement the generated gRPC base class in a Spring-managed service.
• Let Spring Boot handle application wiring and configuration while gRPC handles RPC transport.
• Keep REST and gRPC concerns separate even if they live inside the same Boot application.