Skip to content

Commit 326716c

Browse files
xiaostxiaost
committed
chore: updated README for latest kitex
1 parent 0e0a99c commit 326716c

File tree

2 files changed

+71
-22
lines changed

2 files changed

+71
-22
lines changed

‎README.md‎

Lines changed: 35 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,11 @@ If you don't want any Thrift files, and you want serialize or deserialize a cust
5757

5858
### Using with Kitex
5959

60-
#### 1. Update Kitex to v0.4.2 or higher version
60+
#### 1. Update Kitex and Frugal
6161

6262
```shell
6363
go get github.com/cloudwego/kitex@latest
64+
go get github.com/cloudwego/frugal@latest
6465
```
6566

6667
#### 2. Generate code with `-thrift frugal_tag` option
@@ -71,18 +72,22 @@ Example:
7172
kitex -thrift frugal_tag -service a.b.c my.thrift
7273
```
7374

74-
If you don't need codec code, you can use `-thrift template=slim` option.
75+
If you don't need codec code, you can use `-thrift template=slim` option to reduce generated code significantly.
7576

7677
```shell
7778
kitex -thrift frugal_tag,template=slim -service a.b.c my.thrift
7879
```
7980

80-
#### 3. Init clients and servers with `WithPayloadCodec(thrift.NewThriftFrugalCodec())` option
81+
Note: Latest thriftgo (>= v0.3.0) generates `thrift` struct tags that are compatible with Frugal by default, so `frugal_tag` is optional for structs without `list`, `set` or `enum` fields.
82+
83+
#### 3. Init clients and servers with Frugal codec
84+
85+
Use `thrift.NewThriftCodecWithConfig` to enable Frugal. Codec type priority: Frugal > FastCodec > Apache Thrift.
8186

8287
Client example:
8388

8489
```go
85-
package client
90+
package main
8691

8792
import (
8893
"context"
@@ -92,8 +97,8 @@ import (
9297
"github.com/cloudwego/kitex/pkg/remote/codec/thrift"
9398
)
9499

95-
func Echo() {
96-
code := thrift.NewThriftCodecWithConfig(thrift.FastRead | thrift.FastWrite | thrift.FrugalRead | thrift.FrugalWrite)
100+
func main() {
101+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite)
97102
cli := echo.MustNewClient("a.b.c", client.WithPayloadCodec(codec))
98103
...
99104
}
@@ -113,8 +118,8 @@ import (
113118
)
114119

115120
func main() {
116-
code := thrift.NewThriftCodecWithConfig(thrift.FastRead | thrift.FastWrite | thrift.FrugalRead | thrift.FrugalWrite)
117-
svr := c.NewServer(new(EchoImpl), server.WithPayloadCodec(code))
121+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite)
122+
svr := c.NewServer(new(EchoImpl), server.WithPayloadCodec(codec))
118123

119124
err := svr.Run()
120125
if err != nil {
@@ -123,6 +128,25 @@ func main() {
123128
}
124129
```
125130

131+
Note: Kitex automatically falls back to FastCodec or Apache Thrift for types that don't have `frugal` struct tags, so it's safe to enable Frugal globally.
132+
133+
#### Codec type options
134+
135+
| Option | Description |
136+
|--------|-------------|
137+
| `thrift.FrugalRead` | Use Frugal for deserialization |
138+
| `thrift.FrugalWrite` | Use Frugal for serialization |
139+
| `thrift.FrugalReadWrite` | Shorthand for `FrugalRead \| FrugalWrite` |
140+
| `thrift.FastRead` | Use FastCodec for deserialization |
141+
| `thrift.FastWrite` | Use FastCodec for serialization |
142+
| `thrift.EnableSkipDecoder` | Required when using Buffered transport (no Framed/TTHeader) |
143+
144+
For Framed or TTHeader transport, `FrugalRead | FrugalWrite` is sufficient. For Buffered (PurePayload) transport, add `EnableSkipDecoder`:
145+
146+
```go
147+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite | thrift.EnableSkipDecoder)
148+
```
149+
126150
### Using with Thrift IDL
127151

128152
#### Prepare Thrift file
@@ -140,15 +164,15 @@ struct MyStruct {
140164

141165
#### Use Thriftgo to generate code
142166

143-
Now we have thrift file, we can use Thriftgo with `frugal_tag` option to generate Go code.
167+
Now we have thrift file, we can use Thriftgo to generate Go code.
144168

145-
Example:
169+
Latest thriftgo (>= v0.3.0) generates `thrift` struct tags that are compatible with Frugal by default. For structs containing `list`, `set` or `enum` fields, add `frugal_tag` to generate explicit Frugal tags:
146170

147171
```shell
148172
thriftgo -r -o thrift -g go:frugal_tag,package_prefix=example.com/kitex_test/thrift my.thrift
149173
```
150174

151-
If you don't need codec code, you can use `template=slim` option
175+
If you don't need codec code, you can use `template=slim` option to reduce generated code:
152176

153177
```shell
154178
thriftgo -r -o thrift -g go:frugal_tag,template=slim,package_prefix=example.com/kitex_test/thrift my.thrift

‎README_cn.md‎

Lines changed: 36 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -57,10 +57,11 @@ Unmarshal_Frugal/large-4 5838 197987 ns/op 1533.69
5757

5858
### 配合 Kitex 使用
5959

60-
#### 1. 更新 Kitex 到 v0.4.2 以上版本
60+
#### 1. 更新 Kitex 和 Frugal
6161

6262
```shell
6363
go get github.com/cloudwego/kitex@latest
64+
go get github.com/cloudwego/frugal@latest
6465
```
6566

6667
#### 2. 带上 `-thrift frugal_tag` 参数重新生成一次代码
@@ -71,18 +72,22 @@ go get github.com/cloudwego/kitex@latest
7172
kitex -thrift frugal_tag -service a.b.c my.thrift
7273
```
7374

74-
如果不需要编解码代码，可以带上 `-thrift template=slim` 参数
75+
如果不需要编解码代码，可以带上 `-thrift template=slim` 参数，大幅减少生成的代码量。
7576

7677
```shell
7778
kitex -thrift frugal_tag,template=slim -service a.b.c my.thrift
7879
```
7980

80-
#### 3. 初始化 client 和 server 时使用 `WithPayloadCodec(thrift.NewThriftFrugalCodec())` option
81+
注：最新版本的 thriftgo（>= v0.3.0）默认生成的 `thrift` struct tag 已兼容 Frugal，因此对于不含 `list`、`set`、`enum` 字段的结构体，`frugal_tag` 参数是可选的。
82+
83+
#### 3. 初始化 client 和 server 时启用 Frugal 编解码
84+
85+
使用 `thrift.NewThriftCodecWithConfig` 启用 Frugal。编解码器优先级：Frugal > FastCodec > Apache Thrift。
8186

8287
client 示例：
8388

8489
```go
85-
package client
90+
package main
8691

8792
import (
8893
"context"
@@ -92,8 +97,8 @@ import (
9297
"github.com/cloudwego/kitex/pkg/remote/codec/thrift"
9398
)
9499

95-
func Echo() {
96-
code := thrift.NewThriftCodecWithConfig(thrift.FastRead | thrift.FastWrite | thrift.FrugalRead | thrift.FrugalWrite)
100+
func main() {
101+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite)
97102
cli := echo.MustNewClient("a.b.c", client.WithPayloadCodec(codec))
98103
...
99104
}
@@ -113,8 +118,8 @@ import (
113118
)
114119

115120
func main() {
116-
code := thrift.NewThriftCodecWithConfig(thrift.FastRead | thrift.FastWrite | thrift.FrugalRead | thrift.FrugalWrite)
117-
svr := c.NewServer(new(EchoImpl), server.WithPayloadCodec(code))
121+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite)
122+
svr := c.NewServer(new(EchoImpl), server.WithPayloadCodec(codec))
118123

119124
err := svr.Run()
120125
if err != nil {
@@ -123,6 +128,25 @@ func main() {
123128
}
124129
```
125130

131+
注：对于没有 `frugal` struct tag 的类型，Kitex 会自动 fallback 到 FastCodec 或 Apache Thrift，因此可以放心全局启用 Frugal。
132+
133+
#### 编解码器选项
134+
135+
| 选项 | 说明 |
136+
|------|------|
137+
| `thrift.FrugalRead` | 使用 Frugal 进行反序列化 |
138+
| `thrift.FrugalWrite` | 使用 Frugal 进行序列化 |
139+
| `thrift.FrugalReadWrite` | `FrugalRead \| FrugalWrite` 的简写 |
140+
| `thrift.FastRead` | 使用 FastCodec 进行反序列化 |
141+
| `thrift.FastWrite` | 使用 FastCodec 进行序列化 |
142+
| `thrift.EnableSkipDecoder` | 使用 Buffered 传输协议（无 Framed/TTHeader）时需要 |
143+
144+
使用 Framed 或 TTHeader 传输协议时，`FrugalRead | FrugalWrite` 即可。使用 Buffered（PurePayload）传输协议时，需额外添加 `EnableSkipDecoder`：
145+
146+
```go
147+
codec := thrift.NewThriftCodecWithConfig(thrift.FrugalRead | thrift.FrugalWrite | thrift.EnableSkipDecoder)
148+
```
149+
126150
### 配合 Thriftgo 做 Thrift IDL 的编解码
127151

128152
#### 编写 Thrift 文件
@@ -139,14 +163,15 @@ struct MyStruct {
139163

140164
#### 使用 Thriftgo 生成代码
141165

142-
定义好需要的 Thrift 文件后，在使用 Thriftgo 生成 Go 语言代码时使用 `frugal_tag` 参数。
143-
示例：
166+
定义好需要的 Thrift 文件后，使用 Thriftgo 生成 Go 语言代码。
167+
168+
最新版本的 thriftgo（>= v0.3.0）默认生成的 `thrift` struct tag 已兼容 Frugal。对于包含 `list`、`set`、`enum` 字段的结构体，需添加 `frugal_tag` 参数生成显式的 Frugal tag：
144169

145170
```shell
146171
thriftgo -r -o thrift -g go:frugal_tag,package_prefix=example.com/kitex_test/thrift my.thrift
147172
```
148173

149-
如果不需要编解码代码，可以带上 `template=slim` 参数
174+
如果不需要编解码代码，可以带上 `template=slim` 参数减少生成的代码量：
150175

151176
```shell
152177
thriftgo -r -o thrift -g go:frugal_tag,template=slim,package_prefix=example.com/kitex_test/thrift my.thrift

0 commit comments

Comments
 (0)