devkuma – GRPC

gRPCとは？

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

gRPCとは？

gRPCはGoogleが開発した、高性能で汎用的なオープンソースRPC（Remote Procedure Call）フレームワークです。サービス間で高速かつ効率的に通信するために使用します。

ネットワーク上の関数を、自分のコード内の関数のように呼び出せます。リモート関数呼び出しを標準化し、高速で型安全な通信を実現します。

HTTP/1.1とJSONを主に使用する従来のREST通信とは異なり、gRPCはHTTP/2とバイナリシリアライズ形式のProtocol Buffers（ProtoBuf）を使用します。これにより、低レイテンシー、高スループット、小さいメッセージサイズを実現します。

サービスAPIは.protoファイルで定義します。サーバーとクライアントは同じインターフェース定義を共有し、複数のプログラミング言語向けにStubコードを自動生成できます。多言語環境での開発を容易にし、サービス境界を明確にします。

出典: https://appmaster.io/ko/blog/grpcneun-mueosibnigga

gRPCの主要要素

1. Protocol Buffersベース

gRPCはJSONの代わりに、バイナリ形式のProtocol Buffersを使用します。

JSONより小さく高速
protobufファイルによる明確なスキーマ
各言語向けのクライアントとサーバーのStubコードを自動生成

例: hello.proto

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

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

2. HTTP/2通信

gRPCは内部でHTTP/2を使用するため、次の機能を利用できます。

Multiplexing: 1つの接続で複数のリクエスト
Server Push
ヘッダー圧縮
双方向を含むストリーミング

適切な用途ではRESTより高速で効率的です。

gRPCの4つの通信方式

種類	説明
Unary	1リクエストと1レスポンス
Server Streaming	サーバーが複数のメッセージをストリームとして配信
Client Streaming	クライアントが複数のメッセージを送り、サーバーが1回応答
Bidirectional Streaming	クライアントとサーバーが複数のメッセージを同時に送受信

チャット、リアルタイムログ処理、ストリーミングデータ処理に適しています。

gRPCの長所と短所

長所

Protocol BuffersとHTTP/2による高速で軽量な通信
protoスキーマに基づくコンパイル時検証による強い型安全性
Go、Java、Kotlin、Python、Rust、C#、Node、Rubyなどをサポート
双方向ストリーミングを標準サポート
マイクロサービスの内部通信に適している

短所

gRPC-WebやWebAssemblyなしではブラウザーから直接呼び出しにくい
protoの作成とコンパイルへの理解が必要
RESTよりデバッグが難しい

gRPCを使用するタイミング

適したケース

マイクロサービスの内部通信
高性能が重要なトラフィック
リアルタイムストリーミングサービス
JavaサーバーとGoクライアントなどの多言語サービス
IoT、ゲームサーバー、リアルタイムイベント処理

RESTが適したケース

ブラウザーから直接呼び出すAPI
シンプルな公開API
JSONなど人間が読みやすい形式が必要な場合

gRPCとRESTの比較

項目	gRPC	REST
通信プロトコル	HTTP/2	通常はHTTP/1.1。HTTP/2も可能
データ形式	バイナリのProtocol Buffers	JSONやXMLなどのテキスト形式
速度	非常に高速で小さく、解析も効率的	比較的低速
ストリーミング	双方向を含め完全にサポート	制限あり。SSEやWebSocketが別途必要
インターフェース定義	`.proto`ファイルで型とスキーマを定義	必須スキーマなし。OpenAPIを推奨
型安全性	コンパイル時に検証	実行時に検証される場合が多い
コード生成	クライアントとサーバーのStubを自動生成	Swagger/OpenAPIで文書化可能。Stubは任意
使いやすさ	ブラウザー呼び出しにはgRPC-Webが必要	ブラウザーとJavaScriptから直接利用可能
人間の可読性	バイナリ形式のため低い	JSONで高い
デバッグ	難しい	curlやPostmanで容易
セキュリティ	TLSとHTTP/2の強力な組み合わせ	標準的なTLS
適したサービス	内部マイクロサービス、高性能、リアルタイムストリーミング	公開API、外部連携、ブラウザー中心のサービス
言語サポート	ほぼすべての主要言語を公式サポート	HTTPを扱えれば言語を問わない
長所の要約	高速、効率的、型安全、強力なストリーミング	シンプル、デバッグ容易、高い互換性
短所の要約	複雑、ブラウザーから利用しにくい	性能と型安全性で不利

まとめ

gRPC: 内部通信、高性能、ストリーミングに最適です。
REST: ブラウザー、公開API、デバッグのしやすさに最適です。

Springに適用するgRPCライブラリの比較

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

概要

Spring環境にgRPCを適用する主要なライブラリは2つあります。

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

どちらもSpringへgRPCを統合しますが、出自、設計、サポート方式、将来性が大きく異なります。

ライブラリ比較

項目	`net.devh`	Spring gRPC
出自	コミュニティのサードパーティー	Spring公式プロジェクト
安定性	長期間広く使用	初期段階で急速に発展
最新Spring対応	Spring Boot 3とNative対応に制限	Spring Boot 3、AOT、Native対応
アーキテクチャー	gRPCサーバーとクライアントをラップ	Spring指向のgRPC抽象化
クライアント方式	Stub生成とアノテーション注入	チャネルファクトリーとSpring Bean
拡張性	従来のgRPC方式	Springエコシステムとの連携
長期的方向性	安定した保守	Spring標準になる可能性

背景

net.devh

コミュニティが作成した長年利用されているサードパーティーライブラリ
Spring Boot 1.xと2.xの時代に開始
多くの本番環境で使用され、成熟している
Springチームによる開発ではない
保守は続くが、新機能は少ない

Spring gRPC

Spring公式プロジェクト
Spring Framework 6とSpring Boot 3向けに設計
Springチームが管理
AOT、Native Image、Observabilityと連携

アーキテクチャー

net.devh

NettyベースのgRPCサーバーをSpring方式でラップ
@GrpcServiceと@GrpcClientを提供
Stubとチャネルを直接管理

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

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

Spring gRPC

Springの概念でgRPCを再構成
チャネル抽象化、サーバー抽象化、Bean設定を使用
Spring AOT、GraalVM、Observabilityなどとの連携を考慮

@Service
class HelloServiceImpl : HelloServiceGrpcKt.HelloServiceCoroutineImplBase()

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

運用上の比較

項目	net.devh	Spring gRPC
成熟度	非常に高い	初期段階
企業での利用	多い	増加中
Spring Boot 3とAOT	一部制限	完全対応
ドキュメント	主にGitHub wiki	Spring公式ドキュメント
拡張性	従来のgRPC方式	Springネイティブな拡張

どちらを選ぶべきか

即時の安定性が重要ならnet.devh

既存システムや大規模プロジェクトとの高い互換性
豊富なドキュメントと例
実績のある方式

混在させない

サーバーとStubの管理方式が異なるため、同じアプリケーションで共存させないでください。

まとめ

net.devh

サードパーティー
成熟して安定
Spring Boot 1.xと2.x時代のソリューション

Spring gRPC

Spring公式プロジェクト
Boot 3、Spring 6、Native、Observabilityなどの現代的機能をサポート
Springにおける標準gRPCソリューションになる可能性が高い

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에서 확인해 볼 수 있다.

devkuma – GRPC

gRPCとは？

gRPCとは？

gRPCの主要要素

1. Protocol Buffersベース

2. HTTP/2通信

gRPCの4つの通信方式

gRPCの長所と短所

長所

短所

gRPCを使用するタイミング

適したケース

RESTが適したケース

gRPCとRESTの比較

まとめ

Springに適用するgRPCライブラリの比較

概要

ライブラリ比較

背景

net.devh

Spring gRPC

アーキテクチャー

net.devh

Spring gRPC

運用上の比較

どちらを選ぶべきか

即時の安定性が重要ならnet.devh

最新のSpring技術を使うならSpring gRPC

混在させない

まとめ

net.devh

Spring gRPC

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

개요

목표

프로젝트 생성

빌드 스크립트 설정

Protobuf 파일 작성

gRPC 서버 구현

Service 객체 생성

서버 설정

gRPC 클라이언트 구현

클라이언 설정

gRPC Stub을 호출하는 Service 생성

테스트

참고

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

개요

목표

프로젝트 생성

빌드 스크립트 설정

Protobuf 파일 작성

gRPC 서버 구현

Service 객체 생성

서버 설정

gRPC 클라이언트 구현

클라이언 설정

gRPC Stub을 호출하는 Service 생성

테스트

참고