使用grpc的好处是提供高效的序列化能力,能够跨语言进行调用。这一节我们来学习grpc的入门应用,整篇文章分成3部分:
- 接口定义,使用grpc的IDL,创建proto文件,编译/生成grpc文件
- 服务端开发,处理客户端请求,并返回响应
- 客户端开发,发送请求,并接收服务端响应
根据上面的拆分,我们将grpc的项目拆分为3个工程,分别是:
- demo-grpc-proto,用于存放.proto文件,生成jar包供其他工程使用
- demo-grpc-server,引用proto,创建grpc的server
- demo-grpc-client,引用proto,调用grpc的server端
1. 接口定义
1. 初始化项目
先通过mvn archetype:generate从quickstart生成一个极简的Maven项目
mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DgroupId=org.keyniu -DartifactId=DemoGrpcProto -Dversion=0.1 -Dpackage=org.keyniu -DinteractiveMode=false
引入grpc的Maven依赖以及打包插件,插件略复杂,主要的目的是为了将grpc生成的代码直接打包进当前工程的jar,暂时忽略具体含义即可。
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"><modelVersion>4.0.0</modelVersion><groupId>org.keyniu.proto</groupId><artifactId>demo-grpc-proto</artifactId><version>1.0-SNAPSHOT</version><packaging>jar</packaging><name>DemoGrpcProto</name><properties><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><maven.compiler.source>1.8</maven.compiler.source><maven.compiler.target>1.8</maven.compiler.target></properties><dependencies><dependency><groupId>junit</groupId><artifactId>junit</artifactId><version>3.8.1</version><scope>test</scope></dependency><dependency><groupId>io.grpc</groupId><artifactId>grpc-netty-shaded</artifactId><version>1.64.0</version><scope>runtime</scope></dependency><dependency><groupId>io.grpc</groupId><artifactId>grpc-protobuf</artifactId><version>1.64.0</version></dependency><dependency><groupId>io.grpc</groupId><artifactId>grpc-stub</artifactId><version>1.64.0</version></dependency><dependency> <!-- necessary for Java 9+ --><groupId>org.apache.tomcat</groupId><artifactId>annotations-api</artifactId><version>6.0.53</version><scope>provided</scope></dependency></dependencies><build><sourceDirectory>${basedir}/src/main/java</sourceDirectory><testSourceDirectory>${basedir}/src/test/java</testSourceDirectory><extensions><extension><groupId>kr.motd.maven</groupId><artifactId>os-maven-plugin</artifactId><version>1.7.1</version></extension></extensions><plugins><plugin><groupId>org.xolstice.maven.plugins</groupId><artifactId>protobuf-maven-plugin</artifactId><version>0.6.1</version><configuration><protocArtifact>com.google.protobuf:protoc:3.25.1:exe:${os.detected.classifier}</protocArtifact><pluginId>grpc-java</pluginId><pluginArtifact>io.grpc:protoc-gen-grpc-java:1.64.0:exe:${os.detected.classifier}</pluginArtifact></configuration><executions><execution><goals><goal>compile</goal><goal>compile-custom</goal></goals></execution></executions></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>${maven.compiler.source}</source><target>${maven.compiler.target}</target><generatedSourcesDirectory>${project.build.directory}/generated-sources/protobuf/grpc-java</generatedSourcesDirectory><generatedSourcesDirectory>${project.build.directory}/generated-sources/protobuf/java</generatedSourcesDirectory></configuration></plugin><plugin><artifactId>maven-jar-plugin</artifactId><version>3.2.0</version><configuration><archive><addMavenDescriptor>false</addMavenDescriptor></archive></configuration></plugin><plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-source-plugin</artifactId><version>3.2.1</version><executions><execution><id>attach-sources</id><goals><goal>jar-no-fork</goal></goals></execution></executions></plugin></plugins></build>
</project>
2. 编辑proto文件
proto文件定义了grpc的接口、出参、入参,这里我们定义了4个接口,分别是对应grpc basic tutorial的4种模式:
- 基本调用
- Server端Streaming
- Client端Streaming
- 双向Streaming
文件名是helloworld.proto,路径是 src/main/proto/helloworld.proto,文件内容:
syntax = "proto3";option java_multiple_files = true;
option java_package = "org.keyniu.grpc.generate";
//option java_outer_classname = "HelloWorldProto";
//option objc_class_prefix = "HLW";// The greeting service definition.
service Greeter {rpc sayHello (HelloRequest) returns (HelloReply) {}rpc sayHelloClientStream (stream HelloRequest) returns (HelloReply) {}rpc sayHelloServerStream (HelloRequest) returns (stream HelloReply) {}rpc sayHelloBiStream (stream HelloRequest) returns (stream HelloReply) {}
}// The request message containing the user's name.
message HelloRequest {string name = 1;
}// The response message containing the greetings
message HelloReply {string message = 1;
}
3. 编译proto文件
通过Maven命令,生成grpc的请求/响应对象,以及grpc调用对象
mvn protobuf:compile protobuf:compile-custom
生成的文件结构如下
4. 打包代码
protobuff-maven-plugin生成的代码默认在target/generated-source/protobuff/java下,该代码不会打包到当前工程的jar中,解决方案有两种
1. 换生成目录
可以将生成代码的目录放到src/main/java下,这样我们在package的时候就会包含这部分代码。通过pom.xml指定生成目录
<plugin> <groupId>org.xolstice.maven.plugins</groupId> <artifactId>protobuf-maven-plugin</artifactId> <version>0.6.1</version> <configuration> <protocArtifact>com.google.protobuf:protoc:3.25.1:exe:${os.detected.classifier}</protocArtifact> <pluginId>grpc-java</pluginId> <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.64.0:exe:${os.detected.classifier}</pluginArtifact> <outputDirectory>src/main/java</outputDirectory> </configuration> <executions> <execution> <goals> <goal>compile</goal> <goal>compile-custom</goal> </goals> </execution> </executions>
</plugin>
2. 改编译插件
直接将代码生成到src/main/java下的问题是生成的代码和手动编辑的代码冲突,而且我们无法分辨哪些是生成的,哪些自己编辑的。前面我们给出的完整配置,目的就是打包的时候将generated-source种protobuff的代码包含在jar中
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-compiler-plugin</artifactId><version>3.8.1</version><configuration><source>${maven.compiler.source}</source><target>${maven.compiler.target}</target><generatedSourcesDirectory>${project.build.directory}/generated-sources/protobuf/grpc-java</generatedSourcesDirectory><generatedSourcesDirectory>${project.build.directory}/generated-sources/protobuf/java</generatedSourcesDirectory></configuration>
</plugin>
正常的执行mvn clean package就能完成打包,打包后的文件结构如下图所示
2. 服务端
1. 初始化项目
通过achetype:generate生成一个最简单的项目
mvn archetype:generate -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DgroupId=org.keyniu.server-DartifactId=demo-grpc-server -Dversion=0.1 -Dpackage=org.keyniu.server-DinteractiveMode=false
之前我们创建了接口定义的项目demo-grpc-proto,在demo-grpc-server要引入它的依赖
<dependency><groupId>org.keyniu.proto</groupId><artifactId>demo-grpc-proto</artifactId><version>1.0-SNAPSHOT</version>
</dependency>
2. 实现Server
proto生成的时候,根据我们定义的service名称(例子中是Greeter), 自动生成了一个GreeterGrpc类
要实现service Greeter服务端的逻辑,需要继承Greeter.GreeterImplBase类,下面我们来看一下每个方法的具体实现
public class GreeterServer extends GreeterGrpc.GreeterImplBase {public void sayHello(HelloRequest request, StreamObserver<HelloReply> observer) {super.sayHello(request, observer);}public StreamObserver<HelloRequest> sayHelloClientStream(StreamObserver<HelloReply> responseObserver) {return super.sayHelloClientStream(responseObserver);}public void sayHelloServerStream(HelloRequest request, StreamObserver<HelloReply> responseObserver) {super.sayHelloServerStream(request, responseObserver);}public StreamObserver<HelloRequest> sayHelloBiStream(StreamObserver<HelloReply> responseObserver) {return super.sayHelloBiStream(responseObserver);}
}
1. 基本调用
基本调用的实现逻辑清晰,通过处理入参HelloRequest,生成响应HelloReply,StreamObserver.onNext返回响应,onCompleted通知框架grpc调用结束。
public void sayHello(HelloRequest request, StreamObserver<HelloReply> observer) {String message = "hello " + request.getName();observer.onNext(HelloReply.newBuilder().setMessage(message).build());observer.onCompleted();}
2. Server端Streaming
Server端Streaming和基本调用类似,只是多个响应时要多次调用onNext,onCompleted同样是在grpc请求完整结束之后调用
public void sayHelloServerStream(HelloRequest request, StreamObserver<HelloReply> observer) {String name = request.getName();for(char c : name.toCharArray()) {String message = "hello " + String.valueOf(c);observer.onNext(HelloReply.newBuilder().setMessage(message).build());}observer.onCompleted();}
3. Client端Streaming
Client端Streaming是通过返回一个StreamObserver回调对象给框架实现的,每收到一个请求框架就回调返回对象的onNext方法,客户端发送参数结束之后会调用onCompleted方法,详细的流程看代码会更清晰。
public StreamObserver<HelloRequest> sayHelloClientStream(StreamObserver<HelloReply> observer) {return new StreamObserver<HelloRequest>() {private List<String> names = new ArrayList<String>();public void onNext(HelloRequest request) {names.add(request.getName());}public void onError(Throwable t) {t.printStackTrace();}public void onCompleted() {String message = "hello " + String.join(",", names);observer.onNext(HelloReply.newBuilder().setMessage(message).build());observer.onCompleted();}};}
4. 双向Streaming
我们已经看到过Client和Server端各自的Streaming实现了,双向Streaming其实就是两者的结合,应该说StreamObserver的抽象还是很实用的。
public StreamObserver<HelloRequest> sayHelloBiStream(StreamObserver<HelloReply> observer) {return new StreamObserver<HelloRequest>() {public void onNext(HelloRequest request) {String message = "hello " + request.getName();observer.onNext(HelloReply.newBuilder().setMessage(message).build());}public void onError(Throwable t) {t.printStackTrace();}public void onCompleted() {observer.onCompleted();}};}
3. 启动服务
通过ServerBuilder创建服务,将我们的GreeterServer作为服务注册
public class Main {public static void main(String[] args) throws IOException {Server server = ServerBuilder.forPort(2333).addService(new GreeterServer()).build();server.start();System.out.println("server started....");}
}
启动后发现server started服务就算启动完成了。
3. 客户端
首先是创建和grpc服务的Channel,通过ManagedChannel创建,后续的调用都是通Stub完成的,支持的Stub有两种
- BlockingStub,同步调用
- async Stub,异步调用
ManagedChannel channel = ManagedChannelBuilder.forAddress("127.0.0.1", 2333).usePlaintext().build();
GreeterGrpc.GreeterBlockingStub stub = GreeterGrpc.newBlockingStub(channel);
GreeterGrpc.GreeterStub async = GreeterGrpc.newStub(channel);
如果不是Client端不是Stream,都可以通过BlockingStub实现,我们来分别看一下
1. 基本调用
HelloRequest request = HelloRequest.newBuilder().setName("randy").build();
HelloReply reply = stub.sayHello(request);
System.out.println(reply.getMessage());
2. Server端Streaming
直接响应一个Iterator,Iterator中是服务器的多个响应值
Iterator<HelloReply> replies = stub.sayHelloServerStream(request);
while (replies.hasNext()) {HelloReply aReply = replies.next();System.out.println(aReply.getMessage());
}
3. Client端Streaming
Client端Streaming需要接着async stub完成,我们曾经看到过两个StreamObserver,在客户端的时候,客户端的StreamObserver是用来发送数据的,服务端的StreamObserver用来接收服务器数据;在服务端的时候则相反。
StreamObserver<HelloReply> serverObserver = new StreamObserver<HelloReply>() { // 接收服务端响应的回调public void onNext(HelloReply helloReply) {System.out.println(helloReply.getMessage());}public void onError(Throwable t) {t.printStackTrace();}public void onCompleted() {System.out.println("server complete");}
};
StreamObserver<HelloRequest> requestObserver = async.sayHelloClientStream(serverObserver); // 返回客户端StreamObserver
requestObserver.onNext(HelloRequest.newBuilder().setName("randy").build()); // 客户端StreamObserver.onNext用来发送数据
requestObserver.onNext(HelloRequest.newBuilder().setName("zhangsan").build());
requestObserver.onCompleted();
4. 双向Streaming
理解了Client端Streaming,双向Streaming就好理解了,唯一的不同是serverObserver的onNext方法会有多次回调
StreamObserver<HelloReply> serverObserver = new StreamObserver<HelloReply>() { // 接收服务端响应的回调public void onNext(HelloReply helloReply) {System.out.println(helloReply.getMessage());}public void onError(Throwable t) {t.printStackTrace();}public void onCompleted() {System.out.println("server complete");}
};
requestObserver = async.sayHelloBiStream(serverObserver);
requestObserver.onNext(HelloRequest.newBuilder().setName("randy").build());
requestObserver.onNext(HelloRequest.newBuilder().setName("zhangsan").build());
requestObserver.onCompleted();
A. 参考资料
- what is grpc
- https://grpc.io/docs/what-is-grpc/introduction/
- basic tutorial
- https://grpc.io/docs/languages/java/basics/
- proto buff overview
- https://protobuf.dev/overview/
- proto3 guide
- https://protobuf.dev/programming-guides/proto3/
- Java Generated
- https://protobuf.dev/reference/java/java-generated/
- Github
- https://github.com/grpc/grpc-java