Building a gRPC Microservice: Contract-First Implementation Guide

Core Architecture & Communication Flow

gRPC is a modern, high-performance remote procedure call framework originally developed by Google. By utilizing HTTP/2 for multiplexed transport and Protocol Buffers for efficient binary serialization, it drastically reduces network overhead compared to traditional REST/JSON paradigms. This makes it particularly suitable for low-latency microservice communication, service mesh traffic, and distributed systems requiring strict type safety.

The integration lifecycle adheres to a strict contract-first methodology:

Schema Definition: Services, methods, and message structures are declared in a .proto file.
Stub Generation: The Protocol Buffer compiler (protoc) processes the schema to produce language-specific client proxies and server base classes.
Server Implementation: Developers extend the generated base class, inject business logic, and expose endpoints via the gRPC runtime.
Client Invocation: Applications establish a managed channel, instantiate a stub, and invoke remote methods as if they were local functions.

Project Initialization & Maven Configuration

A standard gRPC implementation benefits from a multi-module Maven structure, isolating the API contract from the provider and consumer implementations. The project consists of three modules: grpc-contract (contains the .proto definition and generated code), grpc-provider (hosts the server logic), and grpc-consumer (handles client requests).

Parent Module Configuration

The root POM centralizes dependency versions and configures the protobuf compilation lifecycle.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.12</version>
        <relativePath/>
    </parent>

    <groupId>com.example.grpc</groupId>
    <artifactId>grpc-fundamentals</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    <modules>
        <module>grpc-contract</module>
        <module>grpc-provider</module>
        <module>grpc-consumer</module>
    </modules>

    <properties>
        <java.version>11</java.version>
        <grpc.version>1.54.1</grpc.version>
        <protobuf.version>3.22.2</protobuf.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-netty-shaded</artifactId>
            <version>${grpc.version}</version>
        </dependency>
        <dependency>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-protobuf</artifactId>
            <version>${grpc.version}</version>
        </dependency>
        <dependency>
            <groupId>io.grpc</groupId>
            <artifactId>grpc-stub</artifactId>
            <version>${grpc.version}</version>
        </dependency>
    </dependencies>

    <build>
        <extensions>
            <extension>
                <groupId>kr.motd.maven</groupId>
                <artifactId>os-maven-plugin</artifactId>
                <version>1.7.1</version>
            </extension>
        </extensions>
        <plugins>
            <plugin>
                <groupId>org.xolstice.maven.plugins</groupId>
                <artifactId>protobuf-maven-plugin</artifactId>
                <version>0.6.1</version>
                <configuration>
                    <protocArtifact>com.google.protobuf:protoc:${protobuf.version}:exe:${os.detected.classifier}</protocArtifact>
                    <pluginId>grpc-java</pluginId>
                    <pluginArtifact>io.grpc:protoc-gen-grpc-java:${grpc.version}:exe:${os.detected.classifier}</pluginArtifact>
                    <outputDirectory>${project.build.directory}/generated-sources/grpc</outputDirectory>
                    <clearOutputDirectory>false</clearOutputDirectory>
                </configuration>
                <executions>
                    <execution>
                        <goals>
                            <goal>compile</goal>
                            <goal>compile-custom</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>build-helper-maven-plugin</artifactId>
                <version>3.3.0</version>
                <executions>
                    <execution>
                        <id>add-generated-sources</id>
                        <phase>generate-sources</phase>
                        <goals>
                            <goal>add-source</goal>
                        </goals>
                        <configuration>
                            <sources>
                                <source>${project.build.directory}/generated-sources/grpc</source>
                            </sources>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Contract Module Dependencies

This module solely handles protocol compilation.

<project xmlns="http://maven.apache.org/POM/4.0.0">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.example.grpc</groupId>
        <artifactId>grpc-fundamentals</artifactId>
        <version>1.0.0</version>
    </parent>

    <artifactId>grpc-contract</artifactId>
    <build>
        <plugins>
            <!-- Inherits protobuf compilation from parent -->
        </plugins>
    </build>
</project>

Server & Client Modules

Both implementations inherit the parent configuration and depend on the contract module. The provider adds the Spring Boot gRPC server starter, while the consumer remains lightweight.

<!-- grpc-provider pom.xml -->
<dependencies>
    <dependency>
        <groupId>com.example.grpc</groupId>
        <artifactId>grpc-contract</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>net.devh</groupId>
        <artifactId>grpc-server-spring-boot-starter</artifactId>
        <version>2.15.0.RELEASE</version>
    </dependency>
</dependencies>

<!-- grpc-consumer pom.xml -->
<dependencies>
    <dependency>
        <groupId>com.example.grpc</groupId>
        <artifactId>grpc-contract</artifactId>
        <version>${project.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
</dependencies>

Defining the Service Contract

Place the schema file in grpc-contract/src/main/proto. The definition declares the service namespace, data types, and RPC signatures.

syntax = "proto3";

option java_package = "com.example.grpc.contract";
option java_multiple_files = true;

service Messaging {
  rpc Greet (QueryRequest) returns (ReplyResponse) {}
}

message QueryRequest {
  string target_name = 1;
}

message ReplyResponse {
  string acknowledgment = 1;
  int64 timestamp = 2;
}

Executing mvn clean compile triggers the protbouf plugin, automatically generating Java data classes, service interfaces, and client/server stubs in the target/generated-sources/grpc directory.

Implementing the Server Endpoint

Inside the provider module, create a Spring component that extends the generated base class. The runtime handles threading and serialization, allowing developers to focus on payload transformation.

package com.example.grpc.provider;

import com.example.grpc.contract.MessagingGrpc;
import com.example.grpc.contract.QueryRequest;
import com.example.grpc.contract.ReplyResponse;
import io.grpc.stub.StreamObserver;
import net.devh.boot.grpc.server.service.GrpcService;

import java.time.Instant;

@GrpcService
public class GreetingEndpoint extends MessagingGrpc.MessagingImplBase {

    @Override
    public void greet(QueryRequest request, StreamObserver<replyresponse> responseObserver) {
        String formattedPayload = "Greetings, " + request.getTargetName();
        ReplyResponse response = ReplyResponse.newBuilder()
                .setAcknowledgment(formattedPayload)
                .setTimestamp(Instant.now().toEpochMilli())
                .build();

        responseObserver.onNext(response);
        responseObserver.onCompleted();
    }
}</replyresponse>

Runtime Configuration

Configure the listening port in application.yml within the provider module.

grpc:
  server:
    port: 8090
    address: 0.0.0.0

Constructing the Client Consumer

The consumer establishes a persistent channel and utilizes a blocking stub to execute synchronous calls. While asynchronous stubs and reactive patterns are available for high-throughput scenarios, a blocking approach simplifies initial verification.

package com.example.grpc.consumer;

import com.example.grpc.contract.MessagingGrpc;
import com.example.grpc.contract.QueryRequest;
import com.example.grpc.contract.ReplyResponse;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class GrpcInvoker {

    public static void main(String[] args) {
        ManagedChannel connection = ManagedChannelBuilder
                .forAddress("localhost", 8090)
                .usePlaintext()
                .build();

        MessagingGrpc.MessagingBlockingStub proxy = MessagingGrpc.newBlockingStub(connection);
        QueryRequest query = QueryRequest.newBuilder().setTargetName("Architect").build();

        try {
            ReplyResponse result = proxy.greet(query);
            System.out.println("Payload: " + result.getAcknowledgment());
            System.out.println("Server Time: " + result.getTimestamp());
        } finally {
            connection.shutdownNow();
        }
    }
}

Launch the provider application first to initialize the gRPC listener. Subsequently, run the consumer's main class. The channel establishes a TCP connnection, transmits the binary-encoded request over HTTP/2, and deserializes the server's response directly into the ReplyResponse object.

Tags: gRPC Protocol Buffers Spring Boot http/2 rpc

Posted on Thu, 11 Jun 2026 17:28:45 +0000 by bals28mjk

Freaks City