«

gRPC之proto及Maven插件怎么使用

时间:2024-6-11 13:49     作者:韩俊     分类: Java


这篇文章主要讲解了“gRPC之proto及Maven插件怎么使用”,文中的讲解内容简单清晰,易于学习与理解,下面请大家跟着小编的思路慢慢深入,一起来研究和学习“gRPC之proto及Maven插件怎么使用”吧!

    一. 前言

    protobuf 是 gRPC 中生成 API Service 的方式,在 Maven 编译时就可以快速生成对应的Class类。

    二. proto 的概念和使用

    以 Maven 为例,在 gRPC 中通常使用 protobuf-maven-plugin 插件,根据一个 .proto 文件生成对应的 Java 代码。 其本身是基于 Google 的 Protocol Buffers 工具链实现的。

    2.1 具体的执行流程

      S1 : 创建一个 .proto 文件,按照规范要求定义元数据内容

      S2 : 通过

      protobuf-maven-plugin
      插件进行 compile 操作

      S3 :

      protobuf-maven-plugin
      调用
      protoc
      命令行工具,生成对应的 Java 代码

      S4 : 生成的 Java 代码会被编译,并打包成 Jar 包 , 最终生成可执行文件给项目使用

    .proto 文件格式

    syntax = "proto3"; // 定义使用的语法版本,这里是proto3
    package com.example.grpc; // 定义package,用于在其他文件中引用该文件定义的类型
    // 定义配置项 
    // - java_package :定义生成的Java类的包名
    // - java_outer_classname  : 定义生成的Java类的类名
    option java_multiple_files = true;
    // 接口类
    service UserService {
      rpc query (UserRequest) returns (UserResponse);
    }
    // 定义消息类型
    message UserRequest {
      string name = 1; // 字段类型和名称,以及字段标识符,用于序列化和反序列化
    }
    // 这里的消息类型是返回值
    message UserResponse {
      string name = 1;
      int32 age = 2;
      string address = 3;
      // 这里定义一个枚举
      enum PhoneType { MOBILE = 0; HOME = 1; WORK = 2; } 
      // 这里定义一个内部对象
      repeated PhoneNumber phones = 4;
      message PhoneNumber {
        string number = 1;
        PhoneType type = 2;
      }
    }

    通常一个 proto 文件中会包含以下主要内容

      package: 包名,用于区分不同模块的数据结构定义。

      message: 消息体,包含多个字段,每个字段都有一个名称和类型。

      enum: 枚举类型,定义多个枚举值。

      service: 定义 RPC 服务接口,包含多个方法,每个方法都有一个请求消息和一个响应消息。

    生成一个 .class 文件

    这里就可以看到,其实生成了很多文件,最重要的包括 :UserServiceGrpc ,HelloRequest 和 HelloResponse 这几个。

    使用文件

    使用文件和平时使用 Class 是一致的,引入 Maven 依赖然后直接调用就行了

    @Resource
    UserServiceGrpc.UserServiceBlockingStub userService;
    UserRequest userRequest = UserRequest.newBuilder().setName("test").build();
    UserResponse user = userService.query(userRequest);

    三. 生成Java文件的核心类

    上面看了插件的使用,后面就来详细看看它生成的几个 Class 到底包含了什么 :

    3.1 grpc 类

    以 UserServiceGrpc 为例 ,整个类包含这些核心方法 :

    getQueryMethod : 这个对应 proto 文件中的 query 方法

    // 注解中就标注了请求的路径和请求体,返回体
    // 没看 grpc 源码,但是猜测里面会通过这个注解构建请求
    @io.grpc.stub.annotations.RpcMethod(
        fullMethodName = SERVICE_NAME + '/' + "query",
        // 这个就对应着 .proto 中配置的 message 对象
        requestType = com.example.grpc.UserRequest.class,
        responseType = com.example.grpc.UserResponse.class,
        methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
    // 这里返回的实际上是一个 MethodDescriptor 对象
    public static io.grpc.MethodDescriptor getQueryMethod() {
      io.grpc.MethodDescriptor getQueryMethod;
      // Spring 注入的时候应该是没有多线程风险的,这个可能是为了其他加载方式准备,上了一把锁
      // PS : 这里是一个经典的单例模式,不过代码太长被我屏蔽了
      synchronized (UserServiceGrpc.class) {
          // 省略具体的build逻辑,这里设置了很多内部参数,方法名等等
          UserServiceGrpc.getQueryMethod = getQueryMethod =
                io.grpc.MethodDescriptor.<....>newBuilder()
                // ... 省略
                .build();
          }
      return getQueryMethod;
    }

    MethodDescriptor 是 gRPC 中的专属对象,用于表示一个gRPC方法的描述。 其中包含了方法名,输入输出,请求流和响应流等信息。

    后续很多流程中都会通过该对象进行请求Client的创建,和RPC方法的注册。

    其他 stub 对象

    除了核心方法,其他比较主要的就是 stub 对象了。stub 对象用于向服务端发起 RPC 调用。

    使用 gRPC 时,客户端通过创建一个与服务端相同的 stub 对象来发起远程调用,封装了底层的网络通信细节。

    UserServiceGrpc 中有一个 newStub 方法,同时对应的还有 newBlockingStub 和 newFutureStub 。这些对象用于创建阻塞,异步回调的请求类型。

    //  对应的class对象里面方法大同小异
    public static final class UserServiceStub extends io.grpc.stub.AbstractAsyncStub<UserServiceStub> {
      // 简单的构造器,这里传入了一个 channel ,表示与服务端通信的通道  
      private UserServiceStub(
          io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
        super(channel, callOptions);
      }
      // 调用 new 完成 build
      protected UserServiceStub build
      // 发起具体的 query 请求
      public void query(com.example.grpc.UserRequest request,
          io.grpc.stub.StreamObserver<com.example.grpc.UserResponse> responseObserver)

    3.2 DTO 和 Build 类

    这里倒没太多东西,主要是 DTO 和 DTOOrBuilder 。

    DTO 类 (HelloRequest)

    这个类比我们想的要大的多,一般我们认为 DTO 里面主要是 Getter / Setter 这些方法 ,但是 proto 生成的 DTO 要复杂得多

    // 容易让人迷惑的方法 :
    - getUnknownFields : 获取消息中的未知字段 (解析器未知的字段)
    - internalGetFieldAccessorTable : 获取特定protobuf消息类型的字段访问器表格
    - isInitialized : 用于判断一个对象是否已经被完全初始化的方法 (避免字段未被初始化完全)
    - getSerializedSize : 用于计算当前消息的序列化后的大小 , 用于预留缓冲空间
    - parseFrom : 用于将二进制数据解析成 Protobuf 消息对象
        - parseFrom(byte[] data):从字节数组解析 Protobuf 消息对象
        - parseFrom(byte[] data, int off, int len):从字节数组的指定位置和长度解析 Protobuf 消息对象
        - parseFrom(InputStream input):从输入流解析 Protobuf 消息对象
        - parseFrom(CodedInputStream input):从 CodedInputStream 对象解析 Protobuf 消息对象
    - newBuilderForType : 创建当前消息类型的 Builder 对象,用于构建该类型的消息
    - toBuilder :用于返回一个可以修改消息的构建器对象 , 配合 newBuilder 一起使用
    - parser : 接收一个字节数组或者一个输入流作为参数,并返回一个对应的消息对象

    DTOOrBuilder (HelloRequestOrBuilder)

    在不需要修改消息属性的场景下,提供一种更轻量级的消息访问方式

    public interface UserRequestOrBuilder extends
        // @@protoc_insertion_point(interface_extends:com.example.grpc.UserRequest)
        com.google.protobuf.MessageOrBuilder {
      /**
       * <code>string name = 1;</code>
       */
      java.lang.String getName();
      /**
       * <code>string name = 1;</code>
       */
      com.google.protobuf.ByteString
          getNameBytes();
    }

    UserServiceOuterClass

    OuterClass 是 proto 文件中定义的一个特殊类,用于包含所有其他消息和服务定义,可以作为访问对应类的入口点。

    example.OuterClass.Person person = example.OuterClass.Person.newBuilder() .setName("Alice") .setId(123) .build();

    标签: java maven

    热门推荐