gRPC版本控制

非中断性变更允许现有客户端继续工作而不做任何变更。

非重大变化

在 gRPC 协议级别和 .NET 二进制级别,这些变更不会中断。

  • 添加新服务
  • 向服务中添加新方法
  • 将字段添加到请求消息 - 添加到请求消息的字段将在服务器上通过默认值(若未设置)进行反序列化。
  • 将字段添加到响应消息 - 添加到响应消息的字段将反序列化到客户端上消息的未知字段集合中。
  • 向枚举添加值 - 枚举被序列化为数值。 新的枚举值在客户端反序列化为没有枚举名的枚举值。 

二进制中断性变更

以下变更在 gRPC 协议级别是非中断性变更,但如果客户端升级到最新的 .proto 协定或客户端 .NET 程序集,则需要对其进行更新。 如果你计划将 gRPC 库发布到 NuGet,二进制兼容性很重要。

  • 删除字段 - 已删除字段中的值被反序列化为消息的未知字段。 这并不是 gRPC 协议中断性变更,但如果客户端升级到最新的协定,则需要对其进行更新。 删除的字段编号不会在将来被意外重用,这点很重要。 若要确保不会发生这种情况,请使用 Protobuf 的保留关键字指定邮件上已删除的字段编号和名称。
  • 重命名消息 - 消息名称通常不会在网络上发送,因此这不是 gRPC 协议中断性变更。 如果客户端升级到最新的协定,则需要对其进行更新。 当消息名称用于标识消息类型时,任何字段都会出现消息名称在网络上发送的情况。
  • 更改 csharp_namespace - 更改 csharp_namespace 将更改所生成的 .NET 类型的命名空间。 这并不是 gRPC 协议中断性变更,但如果客户端升级到最新的协定,则需要对其进行更新。

协议中断性变更

以下各项是协议和二进制的中断性变更:

  • 重命名字段 - 对于 Protobuf 内容,字段名只在生成的代码中使用。 字段编号用于标识网络上的字段。 对 Protobuf 来说,重命名字段不是协议中断性变更。 但是,如果服务器正在使用 JSON 内容,则重命名字段是一个中断性变更。
  • 更改字段数据类型 - 将字段的数据类型更改为不兼容类型将在反序列化消息时导致错误。 即使新的数据类型是兼容的,但如果客户端升级到最新的协定,它也可能需要更新以支持新的类型。
  • 更改字段编号 - 对于 Protobuf 有效负载,字段编号用于标识网络上的字段。
  • 重命名包、服务或方法 - gRPC 使用包名、服务名和方法名来生成 URL。 客户端从服务器获取 UNIMPLEMENTED 状态。
  • 删除服务或方法 - 客户端在调用已删除的方法时从服务器获取 UNIMPLEMENTED 状态。

行为中断性变更

在进行非中断性更改时,还必须考虑旧客户端是否可以继续使用新的服务行为。 例如,向请求消息添加新字段:

  • 它不是协议中断性变更。
  • 如果未设置新字段,则在服务器上返回错误状态对于旧客户端来说是一个中断性变更。

行为兼容性由应用特定的代码决定。

版本号服务

服务应尽量保持与旧客户端的后向兼容。 最终对应用的更改可能需要进行中断性变更。 中断旧客户端并强制其随服务一起更新不是一种好的用户体验。 若要在进行中断性变更的同时保持后向兼容性,一种方法是发布服务的多个版本。

gRPC 支持可选的说明符,它的功能非常类似于 .NET 命名空间。 实际上,如果 .proto 文件中未设置 option csharp_namespace,则 package 将用作生成的 .NET 类型的 .NET 命名空间。 该包可用于指定服务的版本号及其消息:

package greet.v1;
原文地址:https://www.cnblogs.com/yetsen/p/13762279.html