mirror of
https://github.com/tiennm99/zfoo.git
synced 2026-08-19 06:24:16 +00:00
doc[protocol]: update doc
This commit is contained in:
godotg
+40
-11
@@ -149,6 +149,7 @@ your protocol number a little more compactly, so that your protocol number will
|
||||
- The third use: Register the protocol through ProtocolManager.initProtocol(xmlProtocols) in the protocol.xml file
|
||||
```
|
||||
<protocols>
|
||||
<!-- Use class path -->
|
||||
<module id="1" name="common">
|
||||
<protocol id="100" location="com.zfoo.protocol.packet.ComplexObject"/>
|
||||
<protocol id="101" location="com.zfoo.protocol.packet.NormalObject"/>
|
||||
@@ -158,11 +159,38 @@ your protocol number a little more compactly, so that your protocol number will
|
||||
<protocol id="105" location="com.zfoo.protocol.packet.VeryBigObject"/>
|
||||
<protocol id="106" location="com.zfoo.protocol.packet.EmptyObject"/>
|
||||
</module>
|
||||
<!-- Use a package name scans all protocol classes under the package path -->
|
||||
<module id="2" name="native">
|
||||
<protocol location="com.zfoo.net.packet.common"/>
|
||||
<protocol location="com.zfoo.tank.common.protocol.common"/>
|
||||
</module>
|
||||
</protocols>
|
||||
```
|
||||
```
|
||||
|
||||
- The fourth use: generate a protocol with a protocol number by defining a proto file, so that the protocol can be
|
||||
easily registered
|
||||
```
|
||||
syntax = "proto3";
|
||||
package test.message;
|
||||
// start_protocol_id = 500
|
||||
// The above starting ID indicates which protocol number of the entire file starts with
|
||||
|
||||
message SimpleObject {
|
||||
int64 aa = 1;
|
||||
}
|
||||
|
||||
// If the tag of a field exceeds 1000, the field is considered to be a compatible protocol field
|
||||
message OneMessage {
|
||||
// This is a comment on the field
|
||||
int64 id = 1;
|
||||
// This is equivalent to adding a @Compatible annotation to this field
|
||||
string name = 1001;
|
||||
}
|
||||
```
|
||||
|
||||
- If you add a field for version compatibility, you need to add a Compatible annotation, and the order needs to be
|
||||
naturally increased, so as to ensure that the old and new protocols can be compatible with each other
|
||||
naturally increased, so as to ensure that the old and new protocols can be compatible with each other, Protocol
|
||||
nesting is also still compatible
|
||||
- In order to be compatible with versions and avoid modifying field names, default uses field names to read and write
|
||||
in the natural order of strings (can also be customized), so it will cause exceptions in serialization
|
||||
- The official environment does not necessarily have to delete an unwanted field in order to be version compatible and
|
||||
@@ -171,17 +199,18 @@ your protocol number a little more compactly, so that your protocol number will
|
||||
modification. The design of the protocol should also adhere to this principle when it comes to functionality,
|
||||
prioritizing the addition of new protocols over modifying existing ones
|
||||
|
||||
### Ⅷ. Use Protobuf in zfoo
|
||||
### Ⅷ. The difference between zfoo and Protobuf
|
||||
|
||||
- zfoo provides a proto file parsing tool to convert the proto file of protobuf into a pojo object for use by zfoo
|
||||
- Protobuf can delete fields, but ZFOO does not support deleting fields, which improves performance by 1x and reduces
|
||||
the size by 1x at the expense
|
||||
|
||||
- Generate pojo objects through proto files for client
|
||||
use, [Parse proto configuration](https://github.com/zfoo-project/zfoo/blob/main/protocol/src/test/java/com/zfoo/protocol/generate/GenerateProtobufTesting.java)
|
||||
|
||||
### Ⅸ. The difference between zfoo and Protobuf
|
||||
|
||||
- Abandoning the deletion field of protobuf can also be compatible with the protocol, improving the performance by 1
|
||||
times and reducing the size by 1 times.
|
||||
```
|
||||
In fact, the officially launched project almost did not encounter anyone who would delete the field,
|
||||
and if this field was deleted, the server had to change the code not to reference the deleted field,
|
||||
and the client had to change the code not to reference the deleted field, which doubled the workload.
|
||||
If either of them forgets to modify the code, it will directly report an error,
|
||||
so adding a discarded field @Deprecated comment to this field in the actual project can avoid a lot of unnecessary trouble.
|
||||
```
|
||||
|
||||
- zfoo takes the intersection of type declarations in all languages, instead of protobuf taking the union, simplifying
|
||||
the type implementation of protobuf
|
||||
|
||||
+33
-9
@@ -127,6 +127,7 @@ cpu： i9900k
|
||||
- 第三种使用：通过ProtocolManagerinitProtocol(xmlProtocols)去注册协议，把协议号写在protocol.xml文件
|
||||
```
|
||||
<protocols>
|
||||
<!-- 使用类路径 -->
|
||||
<module id="1" name="common">
|
||||
<protocol id="100" location="com.zfoo.protocol.packet.ComplexObject"/>
|
||||
<protocol id="101" location="com.zfoo.protocol.packet.NormalObject"/>
|
||||
@@ -136,24 +137,47 @@ cpu： i9900k
|
||||
<protocol id="105" location="com.zfoo.protocol.packet.VeryBigObject"/>
|
||||
<protocol id="106" location="com.zfoo.protocol.packet.EmptyObject"/>
|
||||
</module>
|
||||
<!-- 使用包名会扫描该包路径下的所有协议类 -->
|
||||
<module id="2" name="native">
|
||||
<protocol location="com.zfoo.net.packet.common"/>
|
||||
<protocol location="com.zfoo.tank.common.protocol.common"/>
|
||||
</module>
|
||||
</protocols>
|
||||
```
|
||||
|
||||
- 如果为了版本兼容，增加字段，需要加上Compatible注解，order需要自然增大，这样就可以保证新老协议可以互相兼容
|
||||
- 第四种使用：通过定义proto文件去生成带协议号的协议，这样就能轻松注册协议
|
||||
```
|
||||
syntax = "proto3";
|
||||
package test.message;
|
||||
// start_protocol_id = 500
|
||||
// 上面这个起始id表示整个文件的协议号从哪个开始
|
||||
|
||||
message SimpleObject {
|
||||
int64 aa = 1;
|
||||
}
|
||||
|
||||
// 如果字段的tag超过1000，则视这个字段为需要兼容的协议字段
|
||||
message OneMessage {
|
||||
// 这是属性的注释
|
||||
int64 id = 1;
|
||||
// 等于给这个字段加上了 @Compatible 注解
|
||||
string name = 1001;
|
||||
}
|
||||
```
|
||||
|
||||
- 如果为了版本兼容，增加字段，需要加上Compatible注解，order需要自然增大，这样就可以保证新老协议可以互相兼容，协议嵌套也依然能够兼容
|
||||
- 正式环境为了版本兼容，避免修改字段名称，内部默认使用字段的名称按照字符串的自然顺序来依次读写的（也可以自定义），所以会导致序列化出现异常
|
||||
- 正式环境为了版本兼容，避免减少字段，没必要一定要删除一个不需要的字段，所以不考虑支持这种减少字段兼容协议的情况
|
||||
- 设计模式六大原则中的开闭原则是对扩展开放，对修改关闭。协议的设计涉及到功能应该也要遵守这个原则，优先增加新的协议而不是修改现有协议
|
||||
|
||||
### Ⅷ. 在zfoo中使用Protobuf
|
||||
|
||||
- zfoo提供了proto文件解析工具，将protobuf的proto文件转换为pojo对象给zfoo使用
|
||||
### Ⅷ. zfoo和Protobuf的区别
|
||||
|
||||
- 通过proto文件生成pojo对象给客户端使用，[解析proto配置](https://github.com/zfoo-project/zfoo/blob/main/protocol/src/test/java/com/zfoo/protocol/generate/GenerateProtobufTesting.java)
|
||||
|
||||
|
||||
### Ⅸ. zfoo和Protobuf的区别
|
||||
|
||||
- 舍弃protobuf的删除字段也可以兼容协议的方式，提升1倍的性能，减小1倍的体积
|
||||
- protobuf可以删除字段，zfoo不支持删除字段，以此为代价提升1倍的性能和减小1倍的体积
|
||||
```
|
||||
实际正式上线的项目几乎没遇到谁会去删字段，删除了这个字段，服务器要改代码不去引用这个删除字段，客户端要改代码不去引用这个删除字段，双倍工作量。
|
||||
如果其中任何一端忘了修改代码就会直接报错，所以实际项目中给这个字段加一个废弃字段 @Deprecated 注释就能避免很多不必要的麻烦。
|
||||
```
|
||||
|
||||
- zfoo取所有语言的类型声明的交集，而不是protobuf取并集，简化protobuf的类型实现
|
||||
- protobuf
|
||||
|
||||
Reference in New Issue
Block a user