Skip to content

Commit dddc165

Browse files
ppzqhppzqh
authored
docs: add description of breaking changes of kitex v0.15.1 (#1430)
1 parent 3db90b1 commit dddc165

File tree

2 files changed

+203
-0
lines changed

2 files changed

+203
-0
lines changed

‎content/en/blog/releases/Kitex/release-v0_15_1.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,107 @@ Kitex will ensure compatibility with normal usage patterns of internal users. Ho
6262

6363
This version has made minor adjustments to non-standard usage of `remote.Message`, `rpcinfo.RPCInfo` or `generic.Generic` interfaces. If there are special usages, they need to be adjusted to conform to the new version's interface definition.
6464

65+
1. `rpcinfo.RPCInfo().Invocation()` added `MethodInfo()` method, returning MethodInfo for the current RPC:
66+
```diff
67+
commit 62979e4b95e5a5ed73d0bfd9e218cfc61c5ce253
68+
type Invocation interface {
69+
PackageName() string
70+
ServiceName() string
71+
MethodName() string
72+
+ MethodInfo() serviceinfo.MethodInfo
73+
StreamingMode() serviceinfo.StreamingMode
74+
SeqID() int32
75+
BizStatusErr() kerrors.BizStatusErrorIface
76+
}
77+
```
78+
79+
2. `remote.Message` interface removed some redundant interfaces:
80+
```diff
81+
// Message is the core abstraction for Kitex message.
82+
type Message interface {
83+
RPCInfo() rpcinfo.RPCInfo
84+
- ServiceInfo() *serviceinfo.ServiceInfo
85+
- SpecifyServiceInfo(svcName, methodName string) (*serviceinfo.ServiceInfo, error)
86+
Data() interface{}
87+
NewData(method string) (ok bool)
88+
MessageType() MessageType
89+
SetPayloadLen(size int)
90+
TransInfo() TransInfo
91+
Tags() map[string]interface{}
92+
- ProtocolInfo() ProtocolInfo
93+
- SetProtocolInfo(ProtocolInfo)
94+
PayloadCodec() PayloadCodec
95+
SetPayloadCodec(pc PayloadCodec)
96+
Recycle()
97+
}
98+
```
99+
Dependencies on `ProtocolInfo()` should be modified to rely on `remote.Message().RPCInfo().Config().TransportProtocol()`.
100+
101+
3. `generic.Generic` interface underwent significant adjustments:
102+
```diff
103+
commit 024fedbc2da33956cd81cd0a8226f817e5eac777
104+
// Generic ...
105+
type Generic interface {
106+
Closer
107+
- // PayloadCodec return codec implement
108+
- // this is used for generic which does not need IDL
109+
- PayloadCodec() remote.PayloadCodec
110+
// PayloadCodecType return the type of codec
111+
PayloadCodecType() serviceinfo.PayloadCodec
112+
- // RawThriftBinaryGeneric must be framed
113+
- Framed() bool
114+
- // GetMethod is to get method name if needed
115+
- GetMethod(req interface{}, method string) (*Method, error)
116+
+ // GenericMethod return generic method func
117+
+ GenericMethod() serviceinfo.GenericMethodFunc
118+
// IDLServiceName returns idl service name
119+
IDLServiceName() string
120+
- // MessageReaderWriter returns reader and writer
121+
- // this is used for generic which needs IDL
122+
- MessageReaderWriter() interface{}
123+
+ // GetExtra returns extra info by key
124+
+ GetExtra(key string) interface{}
125+
}
126+
```
127+
- The `PayloadCodec()` interface was completely removed. This adjustment was made because, after Kitex generic interface supported the multi-service feature, it no longer relies on hijacking PayloadCodec to inject the generic codec; instead, it's implemented by hijacking Args/Results structs. Currently, only `generic.BinaryThriftGeneric()` relies on the old method, but this interface has been marked as deprecated. Please migrate to using `generic.BinaryThriftGenericV2()`, refer to [Generic Call User Guide](/docs/kitex/tutorials/advanced-feature/generic-call/basic_usage).
128+
- `Framed() bool` is a deprecated interface because Kitex has defaulted to framed mode for clients since v0.13.*.
129+
- `MessageReaderWriter` and `GetMethod` interfaces are merged into a unified `GenericMethod()` interface. The new unified interface returns a closure function that accepts context and method name as arguments and returns the corresponding method info. This method info includes the hijacked Args/Results parameters, thus implementing different types of generic call codec logic.
130+
131+
4. `remote.ServiceSearcher` Get/Set method changes, `codec.SetOrCheckMethodName` parameter adjustment:
132+
```diff
133+
commit a1008887b9ab4553a79ce82cf6d3db324c344977
134+
-const keyServiceSearcher = "rpc_info_service_searcher"
135+
+type keyServiceSearcher struct{}
136+
137+
-// GetServiceSearcher returns the service searcher from rpcinfo.RPCInfo.
138+
-func GetServiceSearcher(ri rpcinfo.RPCInfo) ServiceSearcher {
139+
- svcInfo, _ := ri.Invocation().Extra(keyServiceSearcher).(ServiceSearcher)
140+
- return svcInfo
141+
+// GetServiceSearcher returns the service searcher from context.
142+
+func GetServiceSearcher(ctx context.Context) ServiceSearcher {
143+
+ svcSearcher, _ := ctx.Value(keyServiceSearcher{}).(ServiceSearcher)
144+
+ return svcSearcher
145+
}
146+
147+
-// SetServiceSearcher sets the service searcher to rpcinfo.RPCInfo.
148+
-func SetServiceSearcher(ri rpcinfo.RPCInfo, svcSearcher ServiceSearcher) {
149+
- setter := ri.Invocation().(rpcinfo.InvocationSetter)
150+
- setter.SetExtra(keyServiceSearcher, svcSearcher)
151+
+// WithServiceSearcher sets the service searcher to context.
152+
+func WithServiceSearcher(ctx context.Context, svcSearcher ServiceSearcher) context.Context {
153+
+ return context.WithValue(ctx, keyServiceSearcher{}, svcSearcher)
154+
}
155+
```
156+
- The old version set `ServiceSearcher` on rpcinfo; the new version moves it to context to optimize Get/Set performance.
157+
```diff
158+
commit a1008887b9ab4553a79ce82cf6d3db324c344977
159+
// SetOrCheckMethodName is used to set method name to invocation.
160+
-func SetOrCheckMethodName(methodName string, message remote.Message) error {
161+
+func SetOrCheckMethodName(ctx context.Context, methodName string, message remote.Message) error {
162+
```
163+
- This simultaneously affects the definition of `codec.SetOrCheckMethodName`, adding `context.Context` as a parameter.
164+
165+
65166
## **Full Change**
66167

67168
### Feature

‎content/zh/blog/releases/Kitex/release-v0_15_1.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,108 @@ Kitex 会保证内部用户正常使用方式的兼容性。但个别用户可
6262

6363
本版本对 `remote.Message`、`rpcinfo.RPCInfo` 或 `generic.Generic` 接口非普通使用方式做了微调，如果有特殊的使用需要调整至符合新版本的接口定义。
6464

65+
1. `rpcinfo.RPCInfo().Invocation()` 新增了 `MethodInfo()` 方法，返回当前 rpc 的 MethodInfo：
66+
```diff
67+
commit 62979e4b95e5a5ed73d0bfd9e218cfc61c5ce253
68+
type Invocation interface {
69+
PackageName() string
70+
ServiceName() string
71+
MethodName() string
72+
+ MethodInfo() serviceinfo.MethodInfo
73+
StreamingMode() serviceinfo.StreamingMode
74+
SeqID() int32
75+
BizStatusErr() kerrors.BizStatusErrorIface
76+
}
77+
```
78+
79+
2. `remote.Message` 接口删除了部分冗余接口：
80+
```diff
81+
// Message is the core abstraction for Kitex message.
82+
type Message interface {
83+
RPCInfo() rpcinfo.RPCInfo
84+
- ServiceInfo() *serviceinfo.ServiceInfo
85+
- SpecifyServiceInfo(svcName, methodName string) (*serviceinfo.ServiceInfo, error)
86+
Data() interface{}
87+
NewData(method string) (ok bool)
88+
MessageType() MessageType
89+
SetPayloadLen(size int)
90+
TransInfo() TransInfo
91+
Tags() map[string]interface{}
92+
- ProtocolInfo() ProtocolInfo
93+
- SetProtocolInfo(ProtocolInfo)
94+
PayloadCodec() PayloadCodec
95+
SetPayloadCodec(pc PayloadCodec)
96+
Recycle()
97+
}
98+
```
99+
对 `ProtocolInfo()` 接口的依赖请修改为依赖 `remote.Message().RPCInfo().Config().TransportProtocol()`。
100+
101+
3. `generic.Generic` 接口做了大幅调整：
102+
```diff
103+
commit 024fedbc2da33956cd81cd0a8226f817e5eac777
104+
// Generic ...
105+
type Generic interface {
106+
Closer
107+
- // PayloadCodec return codec implement
108+
- // this is used for generic which does not need IDL
109+
- PayloadCodec() remote.PayloadCodec
110+
// PayloadCodecType return the type of codec
111+
PayloadCodecType() serviceinfo.PayloadCodec
112+
- // RawThriftBinaryGeneric must be framed
113+
- Framed() bool
114+
- // GetMethod is to get method name if needed
115+
- GetMethod(req interface{}, method string) (*Method, error)
116+
+ // GenericMethod return generic method func
117+
+ GenericMethod() serviceinfo.GenericMethodFunc
118+
// IDLServiceName returns idl service name
119+
IDLServiceName() string
120+
- // MessageReaderWriter returns reader and writer
121+
- // this is used for generic which needs IDL
122+
- MessageReaderWriter() interface{}
123+
+ // GetExtra returns extra info by key
124+
+ GetExtra(key string) interface{}
125+
}
126+
```
127+
- 完全删除了 `PayloadCodec()` 接口，这一调整是因为 kitex generic 接口支持了 multi service 功能后，已经不再依赖此接口劫持 PayloadCodec 的方式注入泛化编解码器，而是通过劫持 Args/Results 结构体实现。当前仅 `generic.BinaryThriftGeneric()` 接口依赖此方式，但该接口已经标注为废弃，请迁移至使用 `generic.BinaryThriftGenericV2()`，参考 [泛化调用使用指南](/zh/docs/kitex/tutorials/advanced-feature/generic-call/basic_usage)
128+
- `Framed() bool` 是废弃接口，因为 kitex 自 v0.13.* 开始已经默认对 client 启用 framed；
129+
- `MessageReaderWriter` 和 `GetMethod` 接口整合为一个统一的 `GenericMethod()` 接口。统一后的新接口返回一个闭包函数，该函数接受 context 和 method name 入参，返回对应的 method info，其中 metainfo info 就包含了劫持的 Args/Results 参数，从而实现不同类型的泛化调用编解码逻辑。
130+
131+
132+
4. `remote.ServiceSearcher` 的 Get/Set 方式变更，`codec.SetOrCheckMethodName` 参数调整：
133+
```diff
134+
commit a1008887b9ab4553a79ce82cf6d3db324c344977
135+
-const keyServiceSearcher = "rpc_info_service_searcher"
136+
+type keyServiceSearcher struct{}
137+
138+
-// GetServiceSearcher returns the service searcher from rpcinfo.RPCInfo.
139+
-func GetServiceSearcher(ri rpcinfo.RPCInfo) ServiceSearcher {
140+
- svcInfo, _ := ri.Invocation().Extra(keyServiceSearcher).(ServiceSearcher)
141+
- return svcInfo
142+
+// GetServiceSearcher returns the service searcher from context.
143+
+func GetServiceSearcher(ctx context.Context) ServiceSearcher {
144+
+ svcSearcher, _ := ctx.Value(keyServiceSearcher{}).(ServiceSearcher)
145+
+ return svcSearcher
146+
}
147+
148+
-// SetServiceSearcher sets the service searcher to rpcinfo.RPCInfo.
149+
-func SetServiceSearcher(ri rpcinfo.RPCInfo, svcSearcher ServiceSearcher) {
150+
- setter := ri.Invocation().(rpcinfo.InvocationSetter)
151+
- setter.SetExtra(keyServiceSearcher, svcSearcher)
152+
+// WithServiceSearcher sets the service searcher to context.
153+
+func WithServiceSearcher(ctx context.Context, svcSearcher ServiceSearcher) context.Context {
154+
+ return context.WithValue(ctx, keyServiceSearcher{}, svcSearcher)
155+
}
156+
```
157+
- 旧版本将 `ServiceSearcher` 设置在 rpcinfo，新版本为优化 Get/Set 的性能将其设置到 context。
158+
159+
```diff
160+
commit a1008887b9ab4553a79ce82cf6d3db324c344977
161+
// SetOrCheckMethodName is used to set method name to invocation.
162+
-func SetOrCheckMethodName(methodName string, message remote.Message) error {
163+
+func SetOrCheckMethodName(ctx context.Context, methodName string, message remote.Message) error {
164+
```
165+
- 同时影响到 `codec.SetOrCheckMethodName` 的定义，添加 `context.Context` 作为入参。
166+
`
65167
## **详细变更**
66168

67169
### Feature

0 commit comments

Comments
 (0)