gRPC tutorial introduction
In this tutorial, you'll learn how to build a gRPC service with Armeria. This tutorial is based on a sample service, a minimal blog service, with which you can create, read, update, and delete blog posts.
Follow this tutorial to write a service yourself or try running the sample service right away.
Background
Before we get our hands on the tutorial, let's swiftly go over Armeria's gRPC features. Armeria supports features that the upstream (gRPC-Java) does not support.
- Protocol
- HTTP/1.1
- HTTP/2 (upstream)
- Serialization format - Framed
- gRPC protobuf: application/grpc+proto (upstream)
- gRPC JSON: application/grpc+json
- gRPC Web: application/grpc-web+proto
- gRPC Web JSON: application/grpc-web+json
- gRPC Web Text: application/grpc-web-text+proto
- Serialization format - Unframed
- Protobuf: application/protobuf
- JSON: application/json
- HTTP level decorator
- Richer error handling
- HTTP-to-JSON transcoding
- Customizing service method paths
- gRPC documentation service
- gRPC status monitoring with
MetricCollectingService
Assumptions
This tutorial assumes that you have:
- Experience in building services in Java
- Experience in Java frameworks for server-side programming
- Understanding of gRPC and experience in implementing gRPC services
Prerequisites
To run and develop the sample service, you need JDK 11 or higher.
Sample service
The sample service provides implementations of CRUD operations as specified below.
| Operation | Method |
|---|---|
| Create | createBlogPost() |
| Read | getBlogPost(), listBlogPosts() |
| Update | updateBlogPost() |
| Delete | deleteBlogPost() |
The sample service code consists of the following folders and files.
grpc/
├─ src/
│ ├─ main/
│ │ ├─ java/
│ │ │ ├─ example.armeria.server.blog.grpc/
│ │ │ │ ├─ BlogNotFoundException.java
│ │ │ │ ├─ BlogService.java
│ │ │ │ ├─ GrpcExceptionHandler.java
│ │ │ │ └─ Main.java
│ │ ├─ proto/
│ │ │ └─ blog.proto
│ └─ test/
│ └─ java/
│ └─ example.armeria.server.blog.grpc/
│ └─ BlogServiceTest.java
└─ build.gradle
To keep our focus on Armeria, this tutorial and the sample service implement memory-based operations instead of using a database.
Build and run sample service
The sample service provides you implementations of CRUD operations with corresponding service methods. Have a go at running the sample gRPC service and see the outcome of this tutorial. Using Armeria's Documentation Service, you can easily verify a server is running, receiving requests and sending responses.
- Download the code from here.
- Build the sample service using the Gradle Wrapper.
$ ./gradlew build
- Run the sample service again, using the Gradle Wrapper.
$ ./gradlew run
- Open the Documentation service page on your web browser at http://127.0.0.1:8080/docs.
Try writing blog service yourself
Use the sample service's build.gradle file to start building the service from scratch.
Below is a part of the build.gradle file for the sample service.
This tutorial uses protobuf-gradle-plugin to generate stubs from proto files.
apply plugin: 'java'
apply plugin: 'idea'
apply plugin: 'eclipse'
repositories {
mavenCentral()
}
dependencies {
implementation "com.linecorp.armeria:armeria:1.42.0"
implementation "com.linecorp.armeria:armeria-grpc:1.42.0"
// Logging
runtimeOnly "ch.qos.logback:logback-classic:1.5.38"
testImplementation "org.junit.jupiter:junit-jupiter:5.14.4"
testImplementation "com.linecorp.armeria:armeria-junit5:1.42.0"
testImplementation "org.assertj:assertj-core:3.27.7"
}
Start writing the blog service yourself by following the tutorial step by step: