Awesome
The Repo transfer to grpc-ecosystem/grpc-spring
Record this moment
gRPC Spring Boot Starter
Features
-
Automatically configures and runs the gRPC server with your
@GrpcService
implementations -
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.BindableService
based) - Client-side: Requires custom
StubFactory
s
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
The latest version is 2.15.0.RELEASE
it was compiled with spring-boot 2.7.16
and spring-cloud 2021.0.8
but it is also compatible with a large variety of other versions.
An overview of all versions and their respective library versions can be found in our documentation.
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.devh</groupId>
<artifactId>grpc-spring-boot-starter</artifactId>
<version>2.15.0.RELEASE</version>
</dependency>
To add a dependency using Gradle:
dependencies {
implementation 'net.devh:grpc-spring-boot-starter:2.15.0.RELEASE'
}
gRPC Server
To add a dependency using Maven, use the following:
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-server-spring-boot-starter</artifactId>
<version>2.15.0.RELEASE</version>
</dependency>
To add a dependency using Gradle:
dependencies {
implementation 'net.devh:grpc-server-spring-boot-starter:2.15.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.devh</groupId>
<artifactId>grpc-client-spring-boot-starter</artifactId>
<version>2.15.0.RELEASE</version>
</dependency>
To add a dependency using Gradle:
dependencies {
compile 'net.devh:grpc-client-spring-boot-starter:2.15.0.RELEASE'
}
Annotate a field of your grpc client stub with @GrpcClient(serverName)
-
Do not use in conjunction with
@Autowired
or@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:/<name>
):
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.grpc</groupId>
<artifactId>grpc-netty</artifactId>
<version>${grpcVersion}</version>
</dependency>
<!-- For both -->
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-spring-boot-starter</artifactId>
<version>...</version>
<exclusions>
<exclusion>
<groupId>io.grpc</groupId>
<artifactId>grpc-netty-shaded</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- For the server (only) -->
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-server-spring-boot-starter</artifactId>
<version>...</version>
<exclusions>
<exclusion>
<groupId>io.grpc</groupId>
<artifactId>grpc-netty-shaded</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- For the client (only) -->
<dependency>
<groupId>net.devh</groupId>
<artifactId>grpc-client-spring-boot-starter</artifactId>
<version>...</version>
<exclusions>
<exclusion>
<groupId>io.grpc</groupId>
<artifactId>grpc-netty-shaded</artifactId>
</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.