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

     1  English | [中文](README.zh_CN.md)
     2  
     3  The `codec` package can support any third-party business communication protocol by simply implementing the relevant interfaces.
     4  The following introduces the related interfaces of the `codec` package with the server-side protocol processing flow as an example.
     5  The client-side protocol processing flow is the reverse of the server-side protocol processing flow, and is not described here.
     6  For information on how to develop third-party business communication protocol plugins, please refer to [here](/docs/developer_guide/develop_plugins/protocol.md).
     7  
     8  ## Related Interfaces
     9  
    10  The following diagram shows the server-side protocol processing flow, which includes the related interfaces in the `codec` package.
    11  
    12  ```ascii
    13                                package                     req body                                                       req struct
    14  +-------+        +-------+    []byte     +--------------+  []byte    +-----------------------+    +----------------------+
    15  |       +------->+ Framer +------------->| Codec-Decode +----------->| Compressor-Decompress +--->| Serializer-Unmarshal +------------+
    16  |       |        +-------+               +--------------+            +-----------------------+    +----------------------+            |
    17  |       |                                                                                                                        +----v----+
    18  |network|                                                                                                                        | Handler |
    19  |       |                                                 rsp body                                                               +----+----+
    20  |       |                                                  []byte                                                         rsp struct  |
    21  |       |                                +---------------+           +---------------------+       +--------------------+             |
    22  |       <--------------------------------+  Codec-Encode +<--------- + Compressor-Compress + <-----+ Serializer-Marshal +-------------+
    23  +-------+                                +---------------+           +---------------------+       +--------------------+
    24  ```
    25  
    26  - `codec.Framer` reads binary data from the network.
    27  
    28  ```go
    29  // Framer defines how to read a data frame.
    30  type Framer interface {
    31      ReadFrame() ([]byte, error)
    32  }
    33  ```
    34  
    35  - `code.Codec`: Provides the `Decode` and `Encode` interfaces, which parse the binary request body from the complete binary network data package and package the binary response body into a complete binary network data package, respectively.
    36  
    37  ```go
    38  // Codec defines the interface of business communication protocol,
    39  // which contains head and body. It only parses the body in binary,
    40  // and then the business body struct will be handled by serializer.
    41  // In common, the body's protocol is pb, json, etc. Specially,
    42  // we can register our own serializer to handle other body type.
    43  type Codec interface {
    44      // Encode pack the body into binary buffer.
    45      // client: Encode(msg, reqBody)(request-buffer, err)
    46      // server: Encode(msg, rspBody)(response-buffer, err)
    47      Encode(message Msg, body []byte) (buffer []byte, err error)
    48  
    49      // Decode unpack the body from binary buffer
    50      // server: Decode(msg, request-buffer)(reqBody, err)
    51      // client: Decode(msg, response-buffer)(rspBody, err)
    52      Decode(message Msg, buffer []byte) (body []byte, err error)
    53  }
    54  ```
    55  
    56  - `codec.Compressor`: Provides the `Decompress` and `Compress` interfaces. 
    57  Currently, gzip and snappy type `Compressor` are supported. 
    58  You can define your own `Compressor` and register it to the `codec` package.
    59  
    60  ```go
    61  // Compressor is body compress and decompress interface.
    62  type Compressor interface {
    63  	Compress(in []byte) (out []byte, err error)
    64  	Decompress(in []byte) (out []byte, err error)
    65  }
    66  ```
    67  
    68  - `codec.Serializer`: Provides the `Unmarshal` and `Marshal` interfaces. 
    69  Currently, protobuf, json, fb, and xml types of `Serializer` are supported. 
    70  You can define your own `Serializer` and register it to the `codec` package.
    71  
    72  ```go
    73  // Serializer defines body serialization interface.
    74  type Serializer interface {
    75      // Unmarshal deserialize the in bytes into body
    76      Unmarshal(in []byte, body interface{}) error
    77  
    78      // Marshal returns the bytes serialized from body.
    79      Marshal(body interface{}) (out []byte, err error)
    80  }
    81  ```