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

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

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

二. 什么是多态性。

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

1. 示例：住宿租赁系统

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

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

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

三. API中的多态性。

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

1. 单一端点的优势

假设我们需要为房地产代理系统添加新的住宿记录：

如果没有多态性，我们可能需要两个端点：

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文档中记录多态性。

清晰的文档对API消费者理解多态性至关重要。下面介绍如何基于JSON Schema、OpenAPI和AsyncAPI规范记录多态性。

1. 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

2. 使用鉴别器（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消费者可以快速理解每种类型的具体结构，减少误用或错误。