29、API 设计中的多态与资源复制移动操作

API 设计中的多态与资源复制移动操作

1. API 多态性概述

API 中的多态性允许资源呈现不同类型，以避免重复共享功能。然而，支持多态 API 方法存在诸多问题。一方面，若认为资源行为相同值得使用单个 API 方法交互，但表示形式却截然不同，需独立定义资源；另一方面，假定资源行为始终相同且多态方法行为变化会统一应用于所有资源，这两个假设都存在较大跳跃。虽然可能存在使这些假设合理的场景，但更可能的是现在或未来其中之一会瓦解。所以，支持多态 API 方法通常不是好主意，尽管这意味着需要编写更多代码，但能让 API 保持灵活和适应性。

下面是一个基于资源导向多态性的 Message 资源的最终 API 定义示例：

abstract class ChatRoomApi {
  @post("/{parent=chatRooms/*}/messages")
  CreateMessage(req: CreateMessageRequest): Message;
}
interface CreateMessageRequest {
  parent: string;
  resource: Message;
}
interface Message {
  id: string;
  sender: string;
  type: 'text' | 'image' | 'audio' | 'video';
  content: string | Media
}
interface Media {
  uri: string;
  contentType: string;
}

2.