A Guide to Spring gRPC Project

1. Overview

In this tutorial, we’ll explore how to utilize the Spring gRPC project to build a Spring application that includes a gRPC server. Using this project provides us with all the usual Spring benefits, such as fast development and dependency injection, as well as a straightforward way to build gRPC servers, messages, and clients.

2. Project Setup

First, we’ll use the Spring Initializr to get an example project. We only need to select Spring gRPC from the list of dependencies. After opening up the downloaded folder in our development environment, we should find a pom.xml with the dependencies we need. There’ll also be an Application.java file, which contains our application’s main method. Helpfully, there’s also a folder called proto created for us, which we’ll use in the next section.

If we wanted to add a gRPC server to an existing application, we’d need to add the following dependencies:

<dependency>
    <groupId>io.grpc</groupId>
    <artifactId>grpc-services</artifactId>
    <version>1.72.0</version>
</dependency>
<dependency>
    <groupId>org.springframework.grpc</groupId>
    <artifactId>spring-grpc-spring-boot-starter</artifactId>
    <version>0.8.0</version>
</dependency>

We should also keep in mind that Spring gRPC currently supports Spring Boot 3.4.x and 3.5.x.

On top of the dependencies, we’ll need a build plugin to generate classes and interfaces from our Proto file. The tool provided automatically by the Spring Initializr is protobuf-maven-plugin, but others are available and would also work.

Let’s add the plugin to our pom:

<plugin>
    <groupId>org.xolstice.maven.plugins</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>
    <version>0.6.1</version>
    <configuration>
        <protocArtifact>com.google.protobuf:protoc:4.30.2:exe:${os.detected.classifier}</protocArtifact>
        <pluginId>grpc-java</pluginId>
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.72.0:exe:${os.detected.classifier}</pluginArtifact>
    </configuration>
    <executions>
        <execution>
            <id>compile</id>
            <goals>
                <goal>compile</goal>
                <goal>compile-custom</goal>
            </goals>
            <configuration>
                <pluginParameter>jakarta_omit,@generated=omit</pluginParameter>
            </configuration>
        </execution>
    </executions>
</plugin>

3. Defining a Proto File

Now we’ve got our basic application structure, let’s start creating our gRPC server and messages. We’ll create a basic calculator that performs only one operation: multiplying two numbers.

To get started, in our proto folder generated in step 2, let’s create a new file called calculator.proto. At the top, we need to set the syntax and a few options:

syntax = "proto3";

option java_multiple_files = true;
option java_package = "org.springframework.grpc.calculator.proto";
option java_outer_classname = "CalculatorProto";

The syntax line specifies that we want to use the proto3 revision of the Protocol Buffers language.

The options are all instructions for how we want our generated Java code to be named and structured. The java_multiple_files line tells the compiler to create a separate Java file for each service and message we describe. The java_package option states where to put the generated files. Finally, the java_outer_classname option determines the name of the Wrapper class, which will be the Java representation of our Proto file.

Following on from that, we can now define a Request message that’ll contain the two numbers we’ll multiply:

message Request {
  int32 firstValue = 1;
  int32 secondValue = 2;
}

We then need a Response message to send back after we perform the calculation. This should only have one field, the result:

message Response {
  int32 result = 1;
}

Finally, now we’ve got our inputs and outputs, we can define our service:

service Calculator {
  rpc Multiply(Request) returns (Response) {}
}

This service is called Calculator; it has one method called Multiply, which takes a Request and returns a Result.

4. Using the Proto File to Generate Service and Message Interfaces

We’ve defined the basic outline of our gRPC functionality. Now, we can generate the required source files from our Proto file by running:

./mvnw clean package

Within a target folder, this will generate concrete implementations of our messages in classes called Request and Response. It’ll also create an abstract class we can extend for our service called CalculatorGrpc.CalculatorImplBase. Within this abstract class, we have a stubbed version of our Multiply method that we’ll need to override and implement fully.

5. Implementing a Concrete Service

The next step is to extend the generated base class and properly implement our Multiply method. Let’s create a Service class named GrpcCalculatorService that extends CalculatorGrpc.CalculatorImplBase:

@Service
public class GrpcCalculatorService extends CalculatorGrpc.CalculatorImplBase {}

We can now override the Multiply method and add the code to do the multiplication:

@Override
public void multiply(Request req, StreamObserver<Response> responseObserver) {
    Response reply = Response.newBuilder().setResult(req.getFirstValue() * req.getSecondValue()).build();
    responseObserver.onNext(reply);
    responseObserver.onCompleted();
}

The method signature gives us a Request, which is the object we defined in our Proto file. It also gives us a StreamObserver to pass our Response into.

The first step is to build a Response object that contains the result of the calculation. We’ve done that using the automatically provided builder methods to create the object and put the correct number into the result field. Secondly, we use the onNext() method to send the Response. Finally, we can tell the StreamObserver that we are finished with the onCompleted() method.

6. Running and Testing the Service

We have the usual options to run our service. We can run it through our IDE using the main method in Application.java. Alternatively, we can run it from the command line:

./mvnw spring-boot:run

Once the application is successfully up and running, we can call our service and check that it works. The simplest way to do that is through the command line again. We need a gRPC tool for this. The option that we’ll use here is gRPCurl, but other options are available. An example call to our Calculator service looks like this:

grpcurl -d '{"firstValue":7, "secondValue":6}' -plaintext localhost:9090 Calculator.Multiply

Here we’re using the -d flag to pass in our Request message with the two values we want to multiply. We’ve also passed in the URL, in this case localhost on port 9090, but we could change that in our application.properties file if desired. And finally, we’ve specified the service and method we want to use to process our request. The service should respond:

{
  "result": 42
}

5. Conclusion

In this tutorial, we’ve explored the basic usage of the Spring gRPC project. We started by setting up a small project using the Spring Initializr and used a Proto file to define the structure of our services and messages. We then automatically built the majority of the required code and interfaces using a Maven build plugin.

Following on from that, we implemented the generated interface to create a fully functional instance of our Calculator service. Finally, we tested the gRPC server from the command line and successfully multiplied two numbers.

This is a quick and easy way to get a gRPC server up and running with minimal code and full integration into the Spring ecosystem.