AIP-146 泛化域

编号	146
原文链接	AIP-146: Generic fields
状态	批准
创建日期	2019-05-28
更新日期	2019-05-28

API中的大多数域，无论是在请求、资源还是自定义应答中，都有具体的类型或模式。这个模式是约定的一部分，开发者依此约定进行编码。

然而，偶尔会有一些泛化或多态域，可以符合多种模式，甚至是完全可以是任意形式的。

指南

虽然泛化域往往很少见，服务 可以 在必要时使用泛化域。根据域需要的泛化程度，有几种方法可以做到这一点；一般来说，服务 应当 尝试使用能够满足用例的“最低泛化”方法。

Oneof

oneof 可以 用于引入联合类型：用户或服务可以指定 oneof 中的一个域。此外 oneof 可以 可以包含同类型域（通常是字符串），表示选项之间存在语义差异。

由于 oneof 中的各个域有不同的键，开发者可以通过编程确定使用哪个（如果有）域。

oneof 为每个选项保留了最大程度的类型安全性和语义意义，服务 应当 在可行时通常优先选择它们，而不是其他泛化或多态选项。然而，当有大量（或无限）的潜在选项时，或者当有需要一系列“级联oneof”的大型资源结构时，oneof构造是不合适的。

注意 向现有的oneof添加额外的可能域是非破坏性更改，但将现有域移入或移出oneof是破坏性的（它会在Go protobuf存根中创建向后不兼容的更改）。

Maps

Maps 可以 用于需要许多/相同类型/的值，但键未知或由用户决定的情况。

Maps通常不适合泛化域，因为map值都共享一个类型，但偶尔它们是有用的。特别是，map有时可以适用于需要许多相同类型的对象，并根据其键的/名字/具有不同行为的情况（例如，使用键作为环境/名字/）。

Struct

[google.protobuf.Struct][struct]对象 可以 用于表示任意嵌套的JSON。键可以是字符串，值可以是浮点数、字符串、布尔值、数组或额外的嵌套结构，允许表示为JSON的任意嵌套结构（并且在使用REST/JSON时自动表示为JSON）。

当服务事先不知道模式时，或者当服务需要存储和检索任意但结构化的用户数据时，Struct最有用。在这种情况下，使用Struct对用户来说很方便，因为他们可以轻松获取可以在其选择的环境中本地操作的JSON对象。

如果服务需要推理Struct的/模式/，它 应当 使用[JSONSchema][]来实现这一目的。因为JSONSchema本身是JSON，所以有效的JSONSchema文档本身可以存储在Struct中。

Any

[google.protobuf.Any][any]对象可以用于发送任意序列化的协议缓冲区和类型定义。

然而，这引入了复杂性，因为如果消费者无法访问proto，Any除了盲目数据传播之外，对任何其他任务都变得无用。此外，即使消费者/确实/有proto，消费者也必须确保类型已注册，然后手动反序列化，这是一个通常不熟悉的过程。

因此，除非其他选项不可行，否则 不应 使用Any。