trpc.group/trpc-go/trpc-go@v1.0.3/codec/README.zh_CN.md (about)

     1  [English](README.md) | 中文
     2  
     3  # codec
     4  
     5  `codec` 包可以支持任意的第三方业务通信协议，只需要实现相关接口即可。
     6  下面以服务端的协议处理流程为例介绍 `codec` 的相关接口， 客户端的协议处理流程与服务端的协议处理流程相反，这里不再赘述。
     7  关于怎么开发第三方业务通信协议的插件， 可参考[这里](/docs/developer_guide/develop_plugins/protocol.zh_CN.md)。
     8  
     9  ## 相关接口
    10  
    11  下图展示了服务端的协议处理流程，其中包含了`codec`包中的相关接口。
    12  
    13  ```ascii
    14                                package                     req body                                                       req struct
    15  +-------+        +-------+    []byte     +--------------+  []byte    +-----------------------+    +----------------------+
    16  |       +------->+ Framer +------------->| Codec-Decode +----------->| Compressor-Decompress +--->| Serializer-Unmarshal +------------+
    17  |       |        +-------+               +--------------+            +-----------------------+    +----------------------+            |
    18  |       |                                                                                                                        +----v----+
    19  |network|                                                                                                                        | Handler |
    20  |       |                                                 rsp body                                                               +----+----+
    21  |       |                                                  []byte                                                         rsp struct  |
    22  |       |                                +---------------+           +---------------------+       +--------------------+             |
    23  |       <--------------------------------+  Codec-Encode +<--------- + Compressor-Compress + <-----+ Serializer-Marshal +-------------+
    24  +-------+                                +---------------+           +---------------------+       +--------------------+
    25  ```
    26  
    27  - `codec.Framer` 读取来自网络的的二进制数据。
    28  
    29  ```go
    30  // Framer defines how to read a data frame.
    31  type Framer interface {
    32      ReadFrame() ([]byte, error)
    33  }
    34  ```
    35  
    36  - `code.Codec`：提供 `Decode` 和 `Encode` 接口， 分别从完整的二进制网络数据包解析出二进制请求包体，和把二进制响应包体打包成一个完整的二进制网络数据。
    37  
    38  ```go
    39  // Codec defines the interface of business communication protocol,
    40  // which contains head and body. It only parses the body in binary,
    41  // and then the business body struct will be handled by serializer.
    42  // In common, the body's protocol is pb, json, etc. Specially,
    43  // we can register our own serializer to handle other body type.
    44  type Codec interface {
    45      // Encode pack the body into binary buffer.
    46      // client: Encode(msg, reqBody)(request-buffer, err)
    47      // server: Encode(msg, rspBody)(response-buffer, err)
    48      Encode(message Msg, body []byte) (buffer []byte, err error)
    49  
    50      // Decode unpack the body from binary buffer
    51      // server: Decode(msg, request-buffer)(reqBody, err)
    52      // client: Decode(msg, response-buffer)(rspBody, err)
    53      Decode(message Msg, buffer []byte) (body []byte, err error)
    54  }
    55  ```
    56  
    57  - `codec.Compressor`：提供 `Decompress` 和 `Compress` 接口，目前支持 gzip 和 snappy 类型的 `Compressor`，你可以定义自己需要的 `Compressor` 注册到 `codec` 包
    58  
    59  ```go
    60  // Compressor is body compress and decompress interface.
    61  type Compressor interface {
    62  	Compress(in []byte) (out []byte, err error)
    63  	Decompress(in []byte) (out []byte, err error)
    64  }
    65  ```
    66  
    67  - `codec.Serializer`：提供 `Unmarshal` 和 `Marshal` 接口，目前支持 protobuf、json、fb 和 xml 类型的 `Serializer`，你可以定义自己需要的 `Serializer` 注册到 `codec` 包。
    68  
    69  ```go
    70  // Serializer defines body serialization interface.
    71  type Serializer interface {
    72      // Unmarshal deserialize the in bytes into body
    73      Unmarshal(in []byte, body interface{}) error
    74  
    75      // Marshal returns the bytes serialized from body.
    76      Marshal(body interface{}) (out []byte, err error)
    77  }
    78  ```