gRPC Spring Boot Starter
Features
-
Automatically configures and runs the gRPC server with your
@GrpcServiceimplementations -
Automatically creates and manages your grpc channels and stubs with
@GrpcClient -
Supports other grpc-java flavors (e.g. Reactive gRPC (RxJava), grpc-kotlin, ...)
- Server-side: Should work for all grpc-java flavors (
io.grpc.BindableServicebased) - Client-side: Requires custom
StubFactorys
Currently build-in support:- grpc-java
- (Please report missing ones, so we can add support for them)
- Server-side: Should work for all grpc-java flavors (
-
Supports Spring-Security
-
Supports Spring Cloud
-
Supports Spring Sleuth as distributed tracing solution
(If brave-instrumentation-grpc is present) -
Supports global and custom gRPC server/client interceptors
-
Automatic metric support (micrometer/actuator based)
-
Also works with (non-shaded) grpc-netty
Versions
2.x.x.RELEASE supports Spring Boot 2.1.x/2.2.x & Spring Cloud Greenwich/Hoxton.
The latest version: 2.11.0.RELEASE
(Use 2.4.0.RELEASE for Spring Boot 2.0.x & Spring Cloud Finchley).
1.x.x.RELEASE support Spring Boot 1 & Spring Cloud Edgware, Dalston, Camden.
The latest version: 1.4.2.RELEASE
Note: This project can also be used without Spring-Boot, however that requires some manual bean configuration.
Usage
gRPC Server + Client
To add a dependency using Maven, use the following:
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-spring-boot-starterartifactId>
<version>2.11.0.RELEASEversion>
dependency>
To add a dependency using Gradle:
dependencies {
implementation 'net.devh:grpc-spring-boot-starter:2.11.0.RELEASE'
}
gRPC Server
To add a dependency using Maven, use the following:
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-server-spring-boot-starterartifactId>
<version>2.11.0.RELEASEversion>
dependency>
To add a dependency using Gradle:
dependencies {
implementation 'net.devh:grpc-server-spring-boot-starter:2.11.0.RELEASE'
}
Annotate your server interface implementation(s) with @GrpcService
@GrpcService
public class GrpcServerService extends GreeterGrpc.GreeterImplBase {
@Override
public void sayHello(HelloRequest req, StreamObserver<HelloReply> responseObserver) {
HelloReply reply = HelloReply.newBuilder().setMessage("Hello ==> " + req.getName()).build();
responseObserver.onNext(reply);
responseObserver.onCompleted();
}
}
By default, the grpc server will listen to port 9090. These and other settings can be changed via Spring's property mechanism. The server uses the grpc.server. prefix.
Refer to our documentation for more details.
gRPC Client
To add a dependency using Maven, use the following:
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-client-spring-boot-starterartifactId>
<version>2.11.0.RELEASEversion>
dependency>
To add a dependency using Gradle:
dependencies {
compile 'net.devh:grpc-client-spring-boot-starter:2.11.0.RELEASE'
}
Annotate a field of your grpc client stub with @GrpcClient(serverName)
-
Do not use in conjunction with
@Autowiredor@Inject@GrpcClient("gRPC server name") private GreeterGrpc.GreeterBlockingStub greeterStub;
Note: You can use the same grpc server name for multiple channels and also different stubs (even with different interceptors).
Then you can send queries to your server just like this:
HelloReply response = stub.sayHello(HelloRequest.newBuilder().setName(name).build());
It is possible to configure the target address for each client individually. However in some cases, you can just rely on the default configuration. You can customize the default url mapping via NameResolver.Factory beans. If you don't configure that bean, then the default uri will be guessed using the default scheme and the name (e.g.: dns:/):
These and other settings can be changed via Spring's property mechanism. The clients use the grpc.client.(serverName). prefix.
Refer to our documentation for more details.
Running with (non-shaded) grpc-netty
This library supports both grpc-netty and grpc-netty-shaded. The later one might prevent conflicts with incompatible grpc-versions or conflicts between libraries that require different versions of netty.
Note: If the shaded netty is present on the classpath, then this library will always favor it over the non-shaded grpc-netty one.
You can use it with Maven like this:
<dependency>
<groupId>io.grpcgroupId>
<artifactId>grpc-nettyartifactId>
<version>${grpcVersion}version>
dependency>
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-spring-boot-starterartifactId>
<version>...version>
<exclusions>
<exclusion>
<groupId>io.grpcgroupId>
<artifactId>grpc-netty-shadedartifactId>
exclusion>
exclusions>
dependency>
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-server-spring-boot-starterartifactId>
<version>...version>
<exclusions>
<exclusion>
<groupId>io.grpcgroupId>
<artifactId>grpc-netty-shadedartifactId>
exclusion>
exclusions>
dependency>
<dependency>
<groupId>net.devhgroupId>
<artifactId>grpc-client-spring-boot-starterartifactId>
<version>...version>
<exclusions>
<exclusion>
<groupId>io.grpcgroupId>
<artifactId>grpc-netty-shadedartifactId>
exclusion>
exclusions>
dependency>
and like this when using Gradle:
implementation "io.grpc:grpc-netty:${grpcVersion}"
implementation 'net.devh:grpc-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For both
implementation 'net.devh:grpc-client-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For the client (only)
implementation 'net.devh:grpc-server-spring-boot-starter:...' exclude group: 'io.grpc', module: 'grpc-netty-shaded' // For the server (only)
Example-Projects
Read more about our example projects here.
Troubleshooting
Refer to our documentation for help.
Contributing
Contributions are always welcomed! Please see CONTRIBUTING.md for detailed guidelines.
4.5k Dec 30, 2022
24.8k Jan 6, 2023
65 Dec 12, 2022
358 Jan 3, 2023
8 Jan 9, 2023
37 Dec 26, 2022
5 Jun 23, 2022
3 Mar 23, 2022
11 Sep 13, 2022
442 Jan 3, 2023
3 Feb 2, 2022
58 Jan 5, 2023
1 Jan 24, 2022
1 Nov 24, 2021
28.3k Jan 1, 2023
15.2k Jan 5, 2023
2.3k Dec 31, 2022
6 Dec 6, 2022