README.md

Survey - gRPC/Spring

Dear gRPC/Spring users, in order to enhance the user experience of grpc-ecosystem/grpc-spring, we have developed this survey as a means of establishing a direct line of communication. Your feedback is highly appreciated.

gRPC Spring Boot Starter

README: English | 中文

Documentation: English | 中文

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 StubFactorys
    Currently build-in support:
    • grpc-java
    • (Please report missing ones, so we can add support for them)

• Supports Spring-Security

• Supports Spring Cloud

  • Server-side: Adds grpc-port information to the service registration details
    Currently natively supported:
    • Consul
    • Eureka
    • Nacos
    • (Please report missing ones, so we can add support for them)
  • Client-side: Reads the service's target addresses from spring's DiscoveryClient (all flavors)

• 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 3.1.0.RELEASE it was compiled with spring-boot 3.2.4 and spring-cloud 2023.0.0 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>3.1.0.RELEASE</version>
</dependency>

To add a dependency using Gradle:

dependencies {
  implementation 'net.devh:grpc-spring-boot-starter:3.1.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>3.1.0.RELEASE</version>
</dependency>

To add a dependency using Gradle:

dependencies {
  implementation 'net.devh:grpc-server-spring-boot-starter:3.1.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>3.1.0.RELEASE</version>
</dependency>

To add a dependency using Gradle:

dependencies {
  compile 'net.devh:grpc-client-spring-boot-starter:3.1.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.