API 设计中的多类型属性选择：OpenAPI 与 gRPC 的 oneof 与强类型对比

在谈论 API 设计和开发时，有时，一个属性可以是多种类型中的一个，但不能同时是多种类型。比如支付接口的回调处理，常常为了兼容不同平台的参数，会使用以下方式中的一种来进行接收：

1. 范型
2. key-value 形式的 map
3. 所有的 Object 都去接收，枚举哪个取哪个
   但这种模式，往往会造成参数内容的不规范 、接口维护困难 或者是浪费网络传输带宽。

在程序开发中，我们往往会采用主流的 HTTP 协议和 gRPC 协议进行通信，两种技术都为开发者提供了强大的工具来描述、验证和生成 API，但它们的方法和原则有所不同。

OpenAPI 和 oneof

OpenAPI，早前被称为 Swagger，是一个用于描述 RESTful API 的规范。在其 3.0.1 版本中，引入了oneof关键字。

原因：

• RESTful API 设计经常遇到一个属性可以是多种类型中的一个的情况。oneof提供了一种简单、明确的方式来描述这种复杂性。

好处：

• 它使得模式更具表现力和灵活性，允许属性值匹配其中一个定义的模式。

gRPC 和 oneof

gRPC 使用 Protocol Buffers (ProtoBuf) 作为其接口定义语言。ProtoBuf 中也有一个oneof关键字，但其用途与 OpenAPI 中的略有不同。

原因：

• 在 RPC 通信中，特别是在跨语言的场景下，有时需要表示一个值可以是多种数据类型中的一个。oneof为此提供了一个优雅的解决方案。

好处：

• 它保证了在任何给定时间，oneof内的字段只能设置一个，这有助于节省存储空间和序列化/反序列化时间。

强类型支持

强类型是 OpenAPI 和 gRPC 都强烈支持的一个核心概念。

• 强类型保证了数据的一致性：开发者在设计时定义了期望的数据类型，这有助于防止意外的类型错误。
• 提高性能：知道数据的确切类型可以优化存储和访问。

我们可以达到的是

• 错误检测：可以在编译时（或验证时，对于 OpenAPI）捕获类型错误，而不是在运行时。
• 代码清晰：类型声明或注释为其他开发者提供了有关数据的清晰、明确的信息。

尽管 OpenAPI 和 gRPC 在处理oneof和强类型时有所不同，但它们的目标是相同的：提供明确、一致和可靠的 API 描述。选择哪种技术取决于具体的应用场景，但了解这些技术如何处理这些关键概念可以帮助开发者做出明智的决策。