兼容性

    什么算是一个破坏性（不兼容）的变化并没有明确的定义。本指南应该被视为指示性的，而不是每一种可能变化的全面清单。

    这里列出的规则只涉及客户端兼容性。预期API生产者明白在部署方面的要求，包括实现细节的变化。

    一般目的是，服务端更新到一个新的minor版本或patch版本不该破坏客户端。可预期的破坏类型有：

    • 源代码兼容性：针对1.0编写的代码无法在1.1版本编译
    • 传输兼容性：针对1.0构建的应用程序无法与1.1服务器通信
    • 语义兼容性：可以运行，但产生无意义的或令人惊讶的结果

    换句话说：旧客户端应该能够兼容同一major版本号的较新的服务器，并且当后者试图更新到新的minor版本（例如利用新功能）时，可以很容易做到。

    除了理论上的基于协议的考虑之外，也有出于客户端库生成代码和手写代码的实际考虑。尽可能思考在生成新版本的客户端库过程中会产生哪些变化，针对它们写测试用例，并确保其通过测试。

    下面的讨论将原始消息分为三类：

    • 请求消息（例如 ）
    • 响应消息（例如 ListBooksResponse）
    • 资源消息（例如 Book，以及包括在其他资源消息中使用的任何消息）

    这些类别具有不同的规则，因为请求消息只能从客户端发送到服务器，响应消息只能从服务器发送到客户端，但通常资源消息是双向发送。特别强调，对可更新的资源，需要考虑其 读取/修改/写入 循环的顺序。

    从协议的角度来看，这始终是安全的。 唯一需要注意的是，客户端库可能已经在手写的代码中使用了您的新API接口名。 如果新接口与现有接口完全正交，那就没问题（不可能正交）; 如果新接口是现有接口的简化版本，则更有可能导致冲突。

    给API接口添加方法

    除非你添加的方法和客户端库已经生成的方法冲突，否则应该没问题。

    (举一个破坏性的例子:如果你有一个 GetFoo 方法，C＃代码生成器已经创建了和GetFooAsync方法.在API接口中添加一个GetFooAsync方法,从客户端角度，这就是一个破坏性的修改。)

    给方法添加HTTP绑定

    假设绑定不引入任何歧义，使得服务器响应以前会拒绝的URL，这就是安全的。 当将现有操作应用于新资源名称模式时，可以这样做。

    给请求消息添加字段

    最显而易见的反面例子是分页：如果v1.0的API在集合中不包括分页，则不能在v1.1中添加分页，除非新版中的page_size默认为无限大（这通常是一个坏主意）。 否则，希望在单个请求中获取完整结果的v1.0客户端可能会收到不完整的结果，并且不知道结果集包含更多资源。

    在不改变其他响应字段的行为的前提下，非资源（例如，）的响应消息可以扩展而不必破坏客户端的兼容性。即使会引入冗余，先前在响应中填充的任何字段应继续使用相同的语义填充。

    例如，1.0中的查询响应可能包含一个布尔字段contained_duplicates，用来标示某些结果因为重复而被忽略。 在1.1中，我们可能会在duplicate_count字段中提供更详细的信息。 即使从1.1版本的角度来看它是冗余的，仍然必须填充contained_duplicates字段。

    给枚举(enum)添加值

    仅在请求消息中使用的枚举可以自由地扩展新值。例如，使用 模式，可以在新的minor版本中添加新视图。客户端从来不需要接收这个枚举，所以它们不必知道它们不关心的值。

    对于资源消息和响应消息，缺省假设客户端应该处理他们不知道的枚举值。然而，API生产者应该意识到，编写能正确处理新枚举值的应用程序可能很困难。 API所有者应该在文档里描述当遇到未知枚举值时，预期的客户端行为。

    Proto3允许客户端接收不明意义并保留相同值的消息，因此不会中断 读取/修改/写入 周期。
    JSON格式允发送一个名称是未知的值,但是服务器端显然不知道客户端是否能正确理解该字段的确切值。JSON客户端可能意识到已经接收了一个未知的值，要么识别出字符串”name”,要么是数字，不可能两者都识别。客户端会在 读取/修改/写入 周期中原封不动的将值返回服务器，因为服务器应该理解这两种格式。

    给仅输出的资源添加字段

    仅由服务器提供的资源实体中可以添加字段。 服务器可以验证请求中的任何客户端提供的值，但是如果省略该值，服务器禁止失败。

    向后不兼容(破坏性)的修改

    删除或重命名服务，字段，方法或枚举值

    从根本上说，如果客户端代码可以引用某些东西，那么删除或重命名它都是不兼容的变化，这时必须修改major版本号。 引用旧名称的代码将导致某些语言（例如C＃和Java）在编译期出现故障，并可能导致其他语言的执行时失败或丢失数据。 传输格式兼容性与此无关。

    “修改”在这里特指“删除和添加”。 例如，如果您确定要支持PATCH方法，但是您发布的版本支持PUT方法，或者您使用了错误的自定义方法名称，你可以添加新的绑定，但禁止删除旧绑定，原因同删除一个服务方法一样，都是一个不兼容的变化。

    修改字段的类型

    即使新类型是传输格式兼容的，这也可能会导致客户端库生成的代码发生变化，因此必须增加major版本号。 对于编译型静态语言来说，会容易引入编译错误。

    修改资源命名格式

    资源禁止修改其名称 - 这意味着集合名称不能修改。

    更细微地讲，有效资源名称的集合也不应该修改，原因如下：

    • 如果变得更加严格，则以前成功的请求现在将失败。

    • 如果它变得更宽松，那么基于前面文档做出的客户端可能会不兼容。客户端很可能在其他地方存储资源名称，可能对允许的字符集和名称的长度敏感。或者，客户端可能正在执行自己的资源名称验证。 （例如，在允许更长的EC2资源ID时，亚马逊给客户发出了很多警告，并且提供了一个迁移期）

    注意，这样的改变只能在proto文档中可见。因此，当审查CL的兼容性时，仅检查非注释部分修改是不够的。

    修改现有请求的可见行为

    客户端通常依赖于API行为和语义，即使这样的行为没有被明确支持或记录。 因此，在大多数情况下，修改API数据的行为或语义将被消费者视为是破坏性的。 如果行为没有加密隐藏，您应该假设用户已经发现它，并将依赖于它。 例如，。

    因此，加密分页令牌（即使数据没有啥意义）是一个好主意，以防止用户创建自己的令牌，有潜在的令牌行为改变时可能会不兼容的风险。

    除了上面列出的资源名称修改外，有两种修改需要考虑：

    • 自定义方法名称：虽然不是资源名称的一部分，但自定义方法名称是提交到REST客户端的URL的一部分。 修改自定义方法名称不应破坏gRPC客户端，但公共API必须假定它们具有REST客户端。

    给资源消息添加 读取/写入 字段

    客户端将经常执行 读取/修改/写入 操作。 大多数客户端不会为他们不知道的字段提供值，而且proto3也不支持。 您可以指定任何缺少消息类型(而不是原始类型)的字段，这意味着更新不适用于这些字段，也使得从实体中显式移除该字段值变得更加困难。 原始类型（包括字符串和字节）不能这样处理，因为在显式指定int32字段为0和没有指定之间，proto3的表现没有什么不同。

    如果所有更新都是使用字段掩码执行，这就不是问题，因为客户端不会隐式地覆盖其不知道的字段。 然而，这将是一个不寻常的API决策：大多数API允许“整个资源”更新。