Spring boot starter for gRPC framework.
![bintray badge color](https://camo.githubusercontent.com/bec5ea79552d34f0970c0adff468bc28b3372b88c099e82cac28207a971d5c50/68747470733a2f2f7777772e62696e747261792e636f6d2f646f63732f696d616765732f62696e747261795f62616467655f636f6c6f722e706e67)
Auto-configures and runs the embedded gRPC server with @GRpcService-enabled beans as part of spring-boot application.
repositories {
jcenter()
// maven { url "http://oss.jfrog.org/oss-snapshot-local" } //for snashot builds
}
dependencies {
compile('org.lognet:grpc-spring-boot-starter:2.0.1')
}
Note
|
If you are using protobuf version lower than 3.0.0 , please use org.lognet:grpc-spring-boot-starter:0.0.3
|
-
Start by generating stub and server interface(s) from your
.proto
file(s). -
Annotate your server interface implementation(s) with
@org.lognet.springboot.grpc.GRpcService
-
Optionally configure the server port in your
application.yml/properties
. Default port is6565
grpc: port : 6565
In the 'grpc-spring-boot-starter-demo' project you can find fully functional example with integration test.
The service definition from .proto
file looks like this :
service Greeter {
rpc SayHello ( HelloRequest) returns ( HelloReply) {}
}
Note the generated io.grpc.examples.GreeterGrpc.GreeterImplBase
class that extends io.grpc.BindableService
.(The generated classes were intentionally committed for demo purposes).
All you need to do is to annotate your service implementation with @org.lognet.springboot.grpc.GRpcService
@GRpcService
public static class GreeterService extends GreeterGrpc.GreeterImplBase{
@Override
public void sayHello(GreeterOuterClass.HelloRequest request, StreamObserver<GreeterOuterClass.HelloReply> responseObserver) {
final GreeterOuterClass.HelloReply.Builder replyBuilder = GreeterOuterClass.HelloReply.newBuilder().setMessage("Hello " + request.getName());
responseObserver.onNext(replyBuilder.build());
responseObserver.onCompleted();
}
}
The starter supports the registration of two kinds of interceptors: Global and Per Service.
In both cases the interceptor has to implement io.grpc.ServerInterceptor
interface.
-
Per service
@GRpcService(interceptors = { LogInterceptor.class })
public class GreeterService extends GreeterGrpc.GreeterImplBase{
// ommited
}
LogInterceptor
will be instantiated via spring factory if there is bean of type LogInterceptor
, or via no-args constructor otherwise.
-
Global
@GRpcGlobalInterceptor
public class MyInterceptor implements ServerInterceptor{
// ommited
}
The annotation on java config factory method is also supported :
@Configuration
public class MyConfig{
@Bean
@GRpcGlobalInterceptor
public ServerInterceptor globalInterceptor(){
return new ServerInterceptor(){
@Override
public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
// your logic here
return next.startCall(call, headers);
}
};
}
}
The particular service also has the opportunity to disable the global interceptors :
@GRpcService(applyGlobalInterceptors = false)
public class GreeterService extends GreeterGrpc.GreeterImplBase{
// ommited
}
To intercept the io.grpc.ServerBuilder
instance used to build the io.grpc.Server
, you can add bean that inherits from org.lognet.springboot.grpc.GRpcServerBuilderConfigurer
to your context and override the configure
method.
By the time of invocation of configure
method, all discovered services, including theirs interceptors, had been added to the passed builder.
In your implementation of configure
method, you can add your custom configuration:
@Component
public class MyGRpcServerBuilderConfigurer extends GRpcServerBuilderConfigurer(){
@Override
public void configure(ServerBuilder<?> serverBuilder){
serverBuilder
.executor(YOUR EXECUTOR INSTANCE)
.compressorRegistry(YOUR COMPRESSION REGISTRY)
.decompressorRegistry(YOUR DECOMPRESSION REGISTRY)
.useTransportSecurity(YOUR TRANSPORT SECURITY SETTINGS);
}
};
}
When building production-ready services, the advise is to have separate project for your service(s) gRPC API that holds only proto-generated classes both for server and client side usage.
You will then add this project as compile
dependency to your gRPC client
and gRPC server
projects.
To integrate Eureka
simply follow the great guide from Spring.
Below are the essential parts of configurations for both server and client projects.
-
Add eureka starter as dependency of your server project together with generated classes from
proto
files:
dependencies {
compile('org.springframework.cloud:spring-cloud-starter-eureka')
compile project(":yourProject-api")
}
-
Configure gRPC server to register itself with Eureka.
spring:
application:
name: my-service-name (1)
-
Eureka’s
ServiceId
by default is the spring application name, provide it before the service registers itself with Eureka.
grpc:
port: 6565 (1)
eureka:
instance:
nonSecurePort: ${grpc.port} (2)
client:
serviceUrl:
defaultZone: http://${eureka.host:localhost}:${eureka.port:8761}/eureka/ (3)
-
Specify the port number the gRPC is listening on.
-
Register the eureka service port to be the same as
grpc.port
so client will know where to send the requests to. -
Specify the registry URL, so the service will register itself with.
-
Expose the gRPC service as part of Spring Boot Application.
-
@SpringBootApplication
@EnableEurekaClient
public class EurekaGrpcServiceApp {
@GRpcService
public static class GreeterService extends GreeterGrpc.GreeterImplBase {
@Override
public void sayHello(GreeterOuterClass.HelloRequest request, StreamObserver<GreeterOuterClass.HelloReply> responseObserver) {
}
}
public static void main(String[] args) {
SpringApplication.run(DemoApp.class,args);
}
}
-
Add eureka starter as dependency of your client project together with generated classes from
proto
files:
dependencies {
compile('org.springframework.cloud:spring-cloud-starter-eureka')
compile project(":yourProject-api")
}
-
Configure client to find the eureka service registry:
eureka:
client:
register-with-eureka: false (1)
service-url:
defaultZone: http://${eureka.host:localhost}:${eureka.port:8761}/eureka/ (2)
-
false
if this project is not meant to act as a service to another client. -
Specify the registry URL, so this client will know where to look up the required service.
@EnableEurekaClient
@SpringBootApplication
public class GreeterServiceConsumerApplication {
public static void main(String[] args) {
SpringApplication.run(GreeterServiceConsumerApplication.class, args);
}
}
-
Use EurekaClient to get the coordinates of gRPC service instance from Eureka and consume the service :
@EnableEurekaClient
@Component
public class GreeterServiceConsumer {
@Autowired
private EurekaClient client;
public void greet(String name) {
final InstanceInfo instanceInfo = client.getNextServerFromEureka("my-service-name", false);(1)
final ManagedChannel channel = ManagedChannelBuilder.forAddress(instanceInfo.getIPAddr(), instanceInfo.getPort())
.usePlaintext(true)
.build(); (2)
final GreeterServiceGrpc.GreeterServiceFutureStub stub = GreeterServiceGrpc.newFutureStub(channel); (3)
stub.greet(name); (4)
}
}
-
Get the information about the
my-service-name
instance. -
Build
channel
accordingly. -
Create stub using the
channel
. -
Invoke the service.