devkuma – GRPC

What Is gRPC?

kc@example.com (kc kim) — Sat, 15 Nov 2025 17:05:00 +0900

What Is gRPC?

gRPC is a high-performance, general-purpose open source RPC (Remote Procedure Call) framework developed by Google for fast and efficient communication between services.

It lets you call a function across a network as though it were a function in your own code. It standardizes remote function calls and enables fast, type-safe communication.

Unlike traditional REST communication, which commonly uses HTTP/1.1 and JSON, gRPC uses HTTP/2 and the binary Protocol Buffers (ProtoBuf) serialization format. This provides low latency, high throughput, and compact messages.

Service APIs are specified in .proto files. Servers and clients share the same interface definitions, and Stub code can be generated automatically for multiple programming languages. This improves development in polyglot environments and makes service boundaries easier to maintain.

Source: https://appmaster.io/ko/blog/grpcneun-mueosibnigga

Core gRPC Elements

1. Based on Protocol Buffers

gRPC uses the binary Protocol Buffers format instead of JSON.

Smaller and faster than JSON
Based on an explicit schema in a protobuf file
Automatically generates Stub code for clients and servers in each language

Example: hello.proto

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

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

2. HTTP/2 Communication

gRPC uses HTTP/2 internally, enabling:

Multiplexing: multiple requests over one connection
Server Push
Header compression
Streaming, including bidirectional streaming

This makes it faster and more efficient than REST for suitable workloads.

Four gRPC Communication Types

Type	Description
Unary	One request and one response
Server Streaming	The server delivers multiple messages as a stream
Client Streaming	The client sends multiple messages and the server responds once
Bidirectional Streaming	The client and server exchange multiple messages concurrently

Suitable for chat, real-time log processing, and streaming data processing.

Advantages and Disadvantages

Advantages

Fast, lightweight communication through Protocol Buffers and HTTP/2
Strong type safety with compile-time validation based on proto schemas
Support for languages including Go, Java, Kotlin, Python, Rust, C#, Node, and Ruby
Built-in bidirectional streaming
Well suited to internal microservice communication

Disadvantages

Difficult to call directly from browsers without gRPC-Web or WebAssembly
Developers must understand proto authoring and compilation
More difficult to debug than REST

When Should You Use gRPC?

Suitable Cases

Internal microservice communication
High-performance traffic
Real-time streaming services
Polyglot services, such as a Java server and Go client
IoT, game servers, and real-time event processing

When REST Is Better

APIs called directly by browsers
Simple public APIs
Cases that require human-readable formats such as JSON

gRPC vs REST

Category	gRPC	REST
Communication protocol	HTTP/2	Usually HTTP/1.1, although HTTP/2 is possible
Data format	Binary Protocol Buffers	Text formats such as JSON and XML
Speed	Very fast, compact, and efficient to parse	Relatively slower
Streaming	Full support, including bidirectional streaming	Limited; requires SSE or WebSocket separately
Interface definition	Types and schemas defined in `.proto` files	No required schema; OpenAPI is recommended
Type safety	Compile-time validation	Often validated at runtime
Code generation	Automatic client and server Stub generation	Documentation through Swagger/OpenAPI; Stubs are optional
Ease of use	Browser calls require gRPC-Web	Directly usable from browsers and JavaScript
Human readability	Low due to binary format	High with readable JSON
Debugging	More difficult	Easier with curl and Postman
Security	Strong TLS and HTTP/2 combination	Standard TLS security
Best suited for	Internal microservices, high performance, real-time streaming	Public APIs, external integrations, browser-centric services
Language support	Official support for nearly every major language	Language-neutral when HTTP is supported
Summary of advantages	Fast, efficient, type-safe, strong streaming	Simple, easy to debug, highly compatible
Summary of disadvantages	Complex, limited browser accessibility	Lower performance, weaker type safety

Conclusion

gRPC: Best for internal communication, high performance, and streaming.
REST: Best for browsers, public APIs, and convenient debugging.

Comparing gRPC Libraries for Spring

kc@example.com (kc kim) — Sat, 15 Nov 2025 21:37:00 +0900

Overview

There are two major libraries for applying gRPC in a Spring environment:

net.devh:grpc-server-spring-boot-starter
org.springframework.grpc:spring-grpc-spring-boot-starter

Both integrate gRPC with Spring, but differ significantly in origin, design, support model, and future direction.

Library Comparison

Item	`net.devh`	Spring gRPC
Origin	Community third-party library	Official Spring project
Stability	Widely used for a long time	Early stage and evolving quickly
Modern Spring support	Limited Spring Boot 3 and Native support	Spring Boot 3, AOT, and Native support
Architecture	Wraps gRPC server and client features	Provides Spring-oriented gRPC abstractions
Client style	Generated Stubs with annotation-based injection	Channel factory and Spring Beans
Extensibility	Traditional gRPC patterns	Spring ecosystem integrations
Long-term direction	Stable maintenance	Likely to become the Spring standard

Background

net.devh

Long-standing third-party library created by the community
Started during the Spring Boot 1.x and 2.x era
Mature and used in many production systems
Not developed by the Spring team
Maintained, but with fewer new features

Spring gRPC

Official Spring project
Designed for Spring Framework 6 and Spring Boot 3
Managed by the Spring team
Integrates with AOT, Native Image, and Observability

Architecture

net.devh

Wraps the original Netty-based gRPC server in a Spring style
Provides @GrpcService and @GrpcClient
Manages Stubs and channels directly

@GrpcService
public class HelloServiceImpl extends HelloServiceGrpc.HelloServiceImplBase { ... }

@GrpcClient("myService")
private HelloServiceGrpc.HelloServiceBlockingStub stub;

Spring gRPC

Reinterprets gRPC through Spring concepts
Uses channel abstractions, server abstractions, and Bean configuration
Designed to work with Spring AOT, GraalVM, Observability, and other ecosystem features

@Service
class HelloServiceImpl : HelloServiceGrpcKt.HelloServiceCoroutineImplBase()

@Bean
fun helloStub(factory: GrpcChannelFactory) =
    HelloServiceGrpcKt.HelloServiceCoroutineStub(factory.createChannel("local"))

Operational Considerations

Item	net.devh	Spring gRPC
Maturity	Very high	Early stage
Enterprise usage	Common	Increasing
Spring Boot 3 and AOT	Partially limited	Fully supported
Documentation	Primarily GitHub wiki	Official Spring documentation
Extensibility	Traditional gRPC mechanisms	Spring-native extensions

Which Should You Choose?

Choose net.devh When Immediate Stability Matters

Strong compatibility with existing and large-scale projects
Extensive documentation and examples
Proven approach

Choose Spring gRPC for Modern Spring Projects

Optimized for Spring Boot 3.x and Spring Framework 6.x
Evolves closely with the Spring ecosystem
Suitable for AOT and GraalVM Native Image

Do Not Mix Them

The libraries manage servers and Stubs differently and should not coexist in one application.

Conclusion

net.devh

Third-party project
Mature and stable
A solution from the Spring Boot 1.x and 2.x era

Spring gRPC

Official Spring project
Supports modern Boot 3, Spring 6, Native, and Observability features
Likely to become the standard Spring gRPC solution

Spring에 net.devh 라이브러리를 활용한 gRPC 구현

kc@example.com (kc kim) — Sat, 15 Nov 2025 17:05:00 +0900

개요

Spring에 Kotlin와 커뮤니티/오픈소스(3rd-party) 라이브러리인 net.devh를 활용한 간단한 gRPC 구현을 해보겠다.

목표

Spring Boot 프로젝트에 커뮤니티/오픈소스(3rd-party) 라이브러리인 net.devh를 활용하여 gRPC 서버를 연동
.proto 파일 작성 및 Stub 자동 생성
gRPC 서비스 구현
gRPC 클라이언트 작성 및 호출

프로젝트 생성

프로젝트 생성은 Spirng ininitializr으로 생성할 수 있다.

화면 아래 부근에 “GENERATE” 버튼을 누르면, 설정한 프로젝트 파일을 다운로드를 받을 수 있다.

또는, 다음과 같이 curl 명령어를 사용하여 Spring Boot 초기 프로젝트를 생성할 수도 있다.

curl https://start.spring.io/starter.tgz \
-d bootVersion=3.5.7 \
-d baseDir=spring-grpc-1 \
-d groupId=com.devkuma \
-d artifactId=spring-grpc \
-d packageName=com.devkuma.grpc \
-d applicationName=GrpcApplication \
-d packaging=jar \
-d language=kotlin \
-d javaVersion=21 \
-d description="Demo project for Spring gRPC" \
-d type=gradle-project-kotlin | tar -xzvf -

빌드 스크립트 설정

빌드 스크립트에 gRPC 관련 라이브러리를 추가하고, protobuf 설정을 작성한다.

build.gradle

plugins {
	kotlin("jvm") version "1.9.25"
	kotlin("plugin.spring") version "1.9.25"
	id("org.springframework.boot") version "3.5.7"
	id("io.spring.dependency-management") version "1.1.7"

    // gRPC
    id("com.google.protobuf") version "0.9.5"
}

group = "com.devkuma"
version = "0.0.1-SNAPSHOT"
description = "Demo project for Spring gRPC"

java {
	toolchain {
		languageVersion = JavaLanguageVersion.of(21)
	}
}

repositories {
	mavenCentral()
}

dependencies {
	implementation("org.springframework.boot:spring-boot-starter")
	implementation("org.jetbrains.kotlin:kotlin-reflect")
	testImplementation("org.springframework.boot:spring-boot-starter-test")
	testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
	testRuntimeOnly("org.junit.platform:junit-platform-launcher")

    // gRPC + protobuf
    implementation("io.grpc:grpc-kotlin-stub:1.4.3")
    implementation("io.grpc:grpc-protobuf:1.75.0")
    implementation("io.grpc:grpc-stub:1.75.0")
    implementation("io.grpc:grpc-netty-shaded:1.75.0")
    implementation("com.google.protobuf:protobuf-kotlin:3.22.3")

    // Spring gRPC Starter
    implementation("net.devh:grpc-server-spring-boot-starter:3.1.0.RELEASE")
}

kotlin {
	compilerOptions {
		freeCompilerArgs.addAll("-Xjsr305=strict")
	}
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc:3.24.4"
    }

    plugins {
        register("grpc") {
            artifact = "io.grpc:protoc-gen-grpc-java:1.75.0"
        }
    }

    generateProtoTasks {
        all().forEach { task ->
            task.plugins {
                create("grpc")
            }
        }
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

Protobuf 파일 작성

src/main/proto 디렉토리에 gRPC 서비스와 메시지를 정의한 .proto 파일을 작성한다.

**src/main/proto/hello.proto

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.devkuma.grpc";
option java_outer_classname = "HelloProto";

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

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

gRPC 서버 구현

Service 객체 생성

src/main/kotlin/com/devkuma/grpc/service/HelloServiceImpl.kt

package com.devkuma.grpc.service

import com.devkuma.grpc.HelloRequest
import com.devkuma.grpc.HelloResponse
import com.devkuma.grpc.HelloServiceGrpc
import net.devh.boot.grpc.server.service.GrpcService
import io.grpc.stub.StreamObserver

@GrpcService
class HelloServiceImpl : HelloServiceGrpc.HelloServiceImplBase() {

    override fun sayHello(
        request: HelloRequest,
        responseObserver: StreamObserver<HelloResponse>
    ) {
        val reply = "Hello, ${request.name}!"

        val response = HelloResponse.newBuilder()
            .setMessage(reply)
            .build()

        responseObserver.onNext(response)
        responseObserver.onCompleted()
    }
}

서버 설정

기본 gRPC 포트는 9090이다.
원하면 application.yml로 변경 가능하다.

src/main/kotli/resources/application.yml

grpc:
  server:
    port: 9090

gRPC 클라이언트 구현

같은 프로젝트에서 테스트를 하기 위해, 클라이언트 설정 Bean을 추가한다.

클라이언 설정

src/main/kotlin/com/devkuma/grpc/client/GrpcClientConfig.kt

package com.devkuma.grpc.client

import com.devkuma.grpc.HelloServiceGrpc
import io.grpc.ManagedChannel
import io.grpc.ManagedChannelBuilder
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class GrpcClientConfig {

    @Bean
    fun helloChannel(): ManagedChannel =
        ManagedChannelBuilder
            .forAddress("localhost", 9090)
            .usePlaintext()
            .build()

    @Bean
    fun helloStub(channel: ManagedChannel): HelloServiceGrpc.HelloServiceBlockingStub =
        HelloServiceGrpc.newBlockingStub(channel)
}

gRPC Stub을 호출하는 Service 생성

단순히 stub을 호출하는 Service를 생성한다.

src/main/kotlin/com/devkuma/grpc/client/HelloGrpcClientService.kt

package com.devkuma.grpc.client

import com.devkuma.grpc.HelloRequest
import com.devkuma.grpc.HelloServiceGrpc
import org.springframework.stereotype.Service

@Service
class HelloGrpcClientService(
    private val helloStub: HelloServiceGrpc.HelloServiceBlockingStub,
) {

    fun sayHello(name: String): String {
        val request = HelloRequest.newBuilder()
            .setName(name)
            .build()

        val response = helloStub.sayHello(request)
        return response.message
    }
}

테스트

서버와 클라이언트를 하나의 프로젝트에 넣었기에, 테스트 파일 1개로 테스트가 가능하다.

package com.devkuma.grpc

import com.devkuma.grpc.client.HelloGrpcClientService
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest
import kotlin.text.contains

@SpringBootTest
class GrpcIntegrationTest {

    @Autowired
    lateinit var client: HelloGrpcClientService

    @Test
    fun testSayHello() {
        val result = client.sayHello("devkuma")
        assert(result.contains("devkuma"))

        println(result)
    }
}

output:

Hello, devkuma!

참고

위에 예제 코드는 GitHub에서 확인해 볼 수 있다.

Spring 공식 프로젝트 라이브러리를 활용한 gRPC 구현

kc@example.com (kc kim) — Sat, 15 Nov 2025 17:05:00 +0900

개요

Spring 공식 프로젝트(Spring Team이 개발) gRPC 라이브러리를 활용한 gRPC 구현을 해보겠다.

목표

Spring Boot 프로젝트에 Spring 공식 프로젝트 gRPC 라이브러리를 활용한 gRPC 서버를 연동
.proto 파일 작성 및 Stub 자동 생성
gRPC 서비스 구현
gRPC 클라이언트 작성 및 호출

프로젝트 생성

프로젝트 생성은 Spirng ininitializr으로 생성할 수 있다.

화면 아래 부근에 “GENERATE” 버튼을 누르면, 설정한 프로젝트 파일을 다운로드를 받을 수 있다.

또는, 다음과 같이 curl 명령어를 사용하여 Spring Boot 초기 프로젝트를 생성할 수도 있다.

curl https://start.spring.io/starter.tgz \
-d bootVersion=3.5.7 \
-d dependencies=spring-grpc \
-d baseDir=spring-grpc-2 \
-d groupId=com.devkuma \
-d artifactId=spring-grpc \
-d packageName=com.devkuma.grpc \
-d applicationName=GrpcApplication \
-d packaging=jar \
-d language=kotlin \
-d javaVersion=21 \
-d description="Demo project for Spring gRPC" \
-d type=gradle-project-kotlin | tar -xzvf -

빌드 스크립트 설정

빌드 스크립트에 gRPC 관련 라이브러리를 추가하고, protobuf 설정을 작성한다.

build.gradle

import com.google.protobuf.gradle.id

plugins {
    kotlin("jvm") version "1.9.25"
    kotlin("plugin.spring") version "1.9.25"
    id("org.springframework.boot") version "3.5.7"
    id("io.spring.dependency-management") version "1.1.7"

    // gRPC
    id("com.google.protobuf") version "0.9.5"
}

group = "com.devkuma"
version = "0.0.1-SNAPSHOT"
description = "Demo project for Spring gRPC"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

extra["springGrpcVersion"] = "0.12.0"

dependencies {
    implementation("io.grpc:grpc-services")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    implementation("org.springframework.grpc:spring-grpc-spring-boot-starter") // Spring gRPC Starter
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testImplementation("org.jetbrains.kotlin:kotlin-test-junit5")
    testImplementation("org.springframework.grpc:spring-grpc-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")

    // Kotlin coroutines
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.3")

    // gRPC + protobuf
    implementation("io.grpc:grpc-kotlin-stub:1.4.3")
    implementation("io.grpc:grpc-protobuf:1.75.0")
    implementation("io.grpc:grpc-stub:1.75.0")
    implementation("io.grpc:grpc-netty-shaded:1.75.0")
}

dependencyManagement {
    imports {
        mavenBom("org.springframework.grpc:spring-grpc-dependencies:${property("springGrpcVersion")}")
    }
}

kotlin {
    compilerOptions {
        freeCompilerArgs.addAll("-Xjsr305=strict")
    }
}

protobuf {
    protoc {
        artifact = "com.google.protobuf:protoc"
    }
    plugins {
        id("grpc") {
            artifact = "io.grpc:protoc-gen-grpc-java"
        }
        id("grpckt") {
            artifact = "io.grpc:protoc-gen-grpc-kotlin:1.4.3:jdk8@jar"
        }
    }
    generateProtoTasks {
        all().forEach {
            it.plugins {
                id("grpc") {
                    option("@generated=omit")
                }
                id("grpckt") {
                    option("@generated=omit")
                }
            }
        }
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

Protobuf 파일 작성

src/main/proto 디렉토리에 gRPC 서비스와 메시지를 정의한 .proto 파일을 작성한다.

**src/main/proto/hello.proto

syntax = "proto3";

option java_multiple_files = true;
option java_package = "com.devkuma.grpc";
option java_outer_classname = "HelloProto";

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

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

gRPC 서버 구현

Service 객체 생성

src/main/kotlin/com/devkuma/grpc/service/HelloServiceImpl.kt

package com.devkuma.grpc.service

import com.devkuma.grpc.HelloRequest
import com.devkuma.grpc.HelloResponse
import com.devkuma.grpc.HelloServiceGrpcKt
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.withContext
import org.springframework.stereotype.Service

@Service
class HelloServiceImpl : HelloServiceGrpcKt.HelloServiceCoroutineImplBase() {

    override suspend fun sayHello(request: HelloRequest): HelloResponse =
        withContext(Dispatchers.Default) {
            val message = "Hello, ${request.name}! (from Spring gRPC Kotlin)"

            HelloResponse.newBuilder()
                .setMessage(message)
                .build()
        }
}

서버 설정

기본 gRPC 포트는 9090이다.
원하면 application.yml로 변경 가능하다.

src/main/kotli/resources/application.yml

spring:
  grpc:
    server:
      port: 9090

gRPC 클라이언트 구현

같은 프로젝트에서 테스트를 하기 위해, 클라이언트 설정 Bean을 추가한다.

클라이언 설정

src/main/kotlin/com/devkuma/grpc/client/GrpcClientConfig.kt

package com.devkuma.grpc.client

import com.devkuma.grpc.HelloServiceGrpcKt
import io.grpc.ManagedChannel
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.grpc.client.GrpcChannelFactory

@Configuration
class GrpcClientConfig {

    @Bean
    fun helloStub(channelFactory: GrpcChannelFactory): HelloServiceGrpcKt.HelloServiceCoroutineStub {
        val channel: ManagedChannel = channelFactory.createChannel("local")
        return HelloServiceGrpcKt.HelloServiceCoroutineStub(channel)
    }
}

gRPC Stub을 호출하는 Service 생성

단순히 stub을 호출하는 Service를 생성한다.

src/main/kotlin/com/devkuma/grpc/client/HelloGrpcClientService.kt

package com.devkuma.grpc.client

import com.devkuma.grpc.HelloRequest
import com.devkuma.grpc.HelloServiceGrpcKt
import org.springframework.stereotype.Service

@Service
class MyGrpcClientService(
    private val helloStub: HelloServiceGrpcKt.HelloServiceCoroutineStub
) {

    suspend fun sayHello(name: String): String {
        val request = HelloRequest.newBuilder()
            .setName(name)
            .build()

        val response = helloStub.sayHello(request)
        return response.message
    }
}

테스트

서버와 클라이언트를 하나의 프로젝트에 넣었기에, 테스트 파일 1개로 테스트가 가능하다.

package com.devkuma.grpc

import com.devkuma.grpc.client.MyGrpcClientService
import kotlinx.coroutines.runBlocking
import org.junit.jupiter.api.Test
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.context.SpringBootTest

@SpringBootTest
class GrpcIntegrationTest {

    @Autowired
    lateinit var client: MyGrpcClientService

    @Test
    fun testSayHello() = runBlocking {
        val result = client.sayHello("devkuma")
        assert(result.contains("devkuma"))

        println(result)
    }
}

output:

Hello, devkuma!

참고

위에 예제 코드는 GitHub에서 확인해 볼 수 있다.