使用 Protobuf 设计 REST API

淩亂°似流年 2023-02-26 09:29 9阅读 0赞

关于数据序列化与传输格式的选型：[https://www.jianshu.com/p/3504d4643dba][https_www.jianshu.com_p_3504d4643dba]

![20200922113644430.png][]

# 概述 #

一个设计的好的 REST API 接口，需要一个严格的接口定义。本文试图使用 Protobuf 作为接口设计语言，设计 API。

创建文件，`main/proto/Login.proto`

syntax = "proto3";
    package org.wcy123.api;
    option java_outer_classname = "Protos";
    message LoginRequest {
        string name = 1;
        string password = 2;
    }
    message LoginResponse {
        enum LoginResult {
            DEFAULT = 0;
            OK = 1;
            FAIL = 2;
        }
        LoginResult result  = 1;
    }

然后创建一个 Bean 用于转换 JSON 到 Java 对象

@Bean
    ProtobufHttpMessageConverter protobufHttpMessageConverter() {
      return new ProtobufHttpMessageConverter();
    }

然后创建 Controller

@RestController
    @Slf4j
    public class MyRestController {
        @RequestMapping(path = "/login", method = POST)
        public ResponseEntity<Protos.LoginResponse> login(HttpServletRequest request,
                HttpServletResponse response, @RequestBody Protos.LoginRequest command) {
            log.info("input is {}", new JsonFormat().printToString(command));
            return ResponseEntity.ok().body(Protos.LoginResponse.newBuilder()
                    .setResult(Protos.LoginResponse.LoginResult.OK)
                    .build());
        }
    }

`Protos.LoginRequest` 和 `Protos.LoginResponse` 是自动生成的

测试程序

curl -v -s -H 'Content-Type: application/json' -H 'Accept: application/json' http://127.0.0.1:8080/login -d '{"name":"wcy123", "password":"123456"}'
    *   Trying 127.0.0.1...
    * Connected to 127.0.0.1 (127.0.0.1) port 8080 (#0)
    > POST /login HTTP/1.1
    > Host: 127.0.0.1:8080
    > User-Agent: curl/7.43.0
    > Content-Type: application/json
    > Accept: application/json
    > Content-Length: 39
    >
    * upload completely sent off: 39 out of 39 bytes
    < HTTP/1.1 200
    < Content-Type: application/json
    < Transfer-Encoding: chunked
    < Date: Tue, 22 Nov 2016 10:03:43 GMT
    <
    * Connection #0 to host 127.0.0.1 left intact
    {"result": "OK"}

从外部看开，请求和响应都是 JSON，PB 只是内部实现。注意要加 `Content-Type:application/json` 和 `Accept: application/json` 两个 header。

## Protobuf 支持的常用数据类型和 JSON之间的转换关系。 ##

syntax = "proto3";
    package org.wcy123.api;
    message Root {
        Obj1 obj1 = 1;
        bytes base64 = 2;
        enum AnEnum { FOO_BAR = 0 ; GOOD = 2; BYE = 3;};
        AnEnum anEnum = 3;
        repeated string anArray = 4;
        bool aBoolean = 5;
        string aString = 6;
        int32 aInt32 = 7;
        uint32 aUint32 = 8;
        fixed32 aFixed = 9;
        int64 aInt64 = 10;
        uint64 aUint64 = 11;
        fixed64 aFixed64 = 12;
        float aFloat = 13;
        double aDouble = 14;
        //Timestamp aTimestamp = 15;
        //Duration aDuaration = 16;
        oneof anOneOf {
            string eitherString = 17;
            int32 orAnInt = 18;
        }
    }
    message Obj1{
        string name = 1;
    }

我写了一个例子，用于实验所有的改动，具体文档，参考 [https://developers.google.com/protocol-buffers/docs/proto3\#json][https_developers.google.com_protocol-buffers_docs_proto3_json]  
这个转换成 JSON 是下面这个样子。

{
      "obj1": {
        "name": "YourName"
      },
      "base64": "abc123!?$*&()'-=@~",
      "aBoolean": true,
      "aString": "hello world",
      "aInt32": -32,
      "aUint32": 32,
      "aFixed": 64,
      "aInt64": -64,
      "aUint64": 64,
      "aFixed64": 128,
      "aFloat": 1,
      "aDouble": 2,
      "eitherString": "Now It is a String, not an integer"
    }

注意到 `oneOf` 使用字段名称来表示哪一个字段被选择了。

## 细节 ##

### 依赖关系 ###

<dependency>
      <groupId>com.google.protobuf</groupId>
      <artifactId>protobuf-java</artifactId>
      <version>3.0.0-beta-1</version>
    </dependency>

需要插件

<plugin>
      <groupId>org.xolstice.maven.plugins</groupId>
      <artifactId>protobuf-maven-plugin</artifactId>
      <version>0.5.0</version>
      <configuration>
        <protocExecutable>/usr/local/bin/protoc</protocExecutable>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>compile</goal>
            <goal>test-compile</goal>
          </goals>
        </execution>
      </executions>
    </plugin>

### 默认值的处理 ###

注意到在 `OK` 和 `FAIL` 前面，我放了一个无用的 `DEFAULT` 值。如果没有这个值，那么 JSON 转换的时候，认为 `result` 是默认值，那么就不会包含这个字段。

*  如果要强制包含这个字段，那么填一个无用的默认值，占位，永远不用这个默认值。
 *  如果想节省带宽，默认值就不传输的话，那么就保留这个行为。接收端需要判断如果字段不存在，就使用默认值。

### 不能识别的 JSON 字段 ###

PB 忽略不能识别的字段。

[https_www.jianshu.com_p_3504d4643dba]: https://www.jianshu.com/p/3504d4643dba
[20200922113644430.png]: /images/20230209/5b6c527b32c3469b946356450e8a91e3.png
[https_developers.google.com_protocol-buffers_docs_proto3_json]: https://link.jianshu.com/?t=https://developers.google.com/protocol-buffers/docs/proto3#json