27、资源关联与多态性在 API 设计中的应用

资源关联与多态性在 API 设计中的应用

1. 关联资源模式

在 API 设计中，多对多关系是一种常见的情况，即两个资源彼此都有多个对方的实例。例如，一个用户可以是多个组的成员，而一个组也可以有多个用户作为成员。关联资源是一种用于在 API 中建模这种多对多关系的方式。

1.1 关联资源的定义

关联资源是表示两个资源之间关系的一种方式，它提供了最大的灵活性来设计这种关系的工作细节。例如，定义了一个 ListGroupUsersResponse 接口，用于列出组中的用户：

interface ListGroupUsersResponse {
  results: User[];
  nextPageToken: string;
}

1.2 关联资源的权衡

使用关联资源来表示多对多关系有一些好处，但也存在一些缺点：
- 复杂性 ：为了获得极高的灵活性，我们需要付出接口稍微复杂的代价，有时可能不太直观。例如，当我们希望用户加入一个组时，我们使用标准的创建方法来创建一个新的成员关系，而不是调用 JoinGroup 方法。此外，还需要考虑额外的关联资源，这意味着更大的 API 表面，因为每个关联都有一个额外的资源和多达七个额外的方法需要考虑。
- 关联分离 ：即使我们可以提供别名方法来更方便地查询资源关系，但我们仍然将两个资源之间的关联与每个资源的信息分开处理。例如，组的描述和组的成