如何在API中使用和记录多态 - Bump.sh

多态性在API中的应用与记录

在软件开发中，“不要重复自己”（DRY，Don’t Repeat Yourself）是一条重要的原则。它强调通过减少重复代码来提升代码的可维护性和灵活性。多态性作为一种设计模式，正是实现这一原则的关键工具之一。本文将探讨如何在API开发中应用和记录多态性，帮助开发者优化API设计并提高开发效率。

什么是多态性？

多态性指的是通过提取对象共有的特性和行为，避免对相似对象进行重复定义。它的核心在于分离通用特性和特定特性，从而减少代码重复。

示例：住宿租赁系统

以一个房地产代理应用为例，其主要功能是提供住宿租赁服务。假设系统需要处理两种住宿类型：

房子：包含花园、瓦屋顶、总面积、月租金和地址等属性。
公寓：包含特定楼层、停车位、电梯、总面积、月租金和地址等属性。

尽管房子和公寓有各自的特性，但它们也共享许多共同属性，例如月租金、地址和总面积。通过多态性设计，我们可以将这些共享属性提取到一个通用的“住宿”对象中，从而避免重复定义。

API中的多态性

在API设计中，多态性允许开发者通过单一端点处理多个相关对象，从而简化API结构并提升其灵活性。

单一端点的优势

假设我们需要为房地产代理系统添加新的住宿记录。如果没有多态性，我们可能需要两个不同的端点：

POST /house
POST /apartment

每个端点都需要处理大量相似的字段。然而，通过多态性，我们可以设计一个通用端点：

POST /accommodation

请求体中通过一个“类型”字段（如type）来区分住宿类型。例如：

{
  "type": "house",
  "address": "123 Main St",
  "monthly_rent": 1200,
  "garden_size": 50
}

{
  "type": "apartment",
  "address": "456 Elm St",
  "monthly_rent": 900,
  "floor": 3,
  "parking_slots": 1
}

这种设计不仅减少了端点数量，还提升了API的可扩展性和维护性。

在API文档中记录多态性

为了让Schema、OpenAPI和AsyncAPI规范记录多态性的关键方法。

JSON Schema中的多态性

JSON Schema原生支持多态性，主要通过以下组合器实现：

allOf：表示属性的合并，适用于对象继承。
anyOf 和 oneOf：表示属性的替代选择，适用于多态性。

例如，以下是一个用于创建住宿的OpenAPI请求体示例：

components:
  schemas:
    Accommodation:
      type: object
      properties:
        type:
          type: string
        address:
          type: string
        monthly_rent:
          type: number
    House:
      allOf:
        - $ref: '#/components/schemas/Accommodation'
        - type: object
          properties:
            garden_size:
              type: number
    Apartment:
      allOf:
        - $ref: '#/components/schemas/Accommodation'
        - type: object
          properties:
            floor:
              type: number
            parking_slots:
              type: number

使用鉴别器（Discriminator）

为了进一步优化多态性记录，OpenAPI和AsyncAPI引入了“鉴别器”（Discriminator）关键字。鉴别器通过一个共享属性（如type）来明确区分不同的模式。

以下是一个包含鉴别器的示例：

components:
  schemas:
    Accommodation:
      type: object
      discriminator:
        propertyName: type
        mapping:
          house: '#/components/schemas/House'
          apartment: '#/components/schemas/Apartment'
      properties:
        type:
          type: string
        address:
          type: string
        monthly_rent:
          type: number
    House:
      type: object
      properties:
        garden_size:
          type: number
    Apartment:
      type: object
      properties:
        floor:
          type: number
        parking_slots:
          type: number

通过鉴别器，API消费者可以清晰地了解每种类型的具体结构，从而减少误解和错误。

结论

多态性和继承是优化API设计的重要工具。通过减少端点重复和代码冗余，它们不仅提升了API的灵活性和可维护性，还改善了开发者和消费者的体验。

OpenAPI和AsyncAPI提供了强大的工具来支持多态性记录。无论是通过组合器还是鉴别器，开发者都可以根据需求选择合适的实现方式。

希望本文能够帮助您更好地理解和应用多态性，为您的API设计带来更多灵感和优化空间。

原文链接: https://bump.sh/blog/use-document-polymorphism-API