如何在 RESTful API 中处理多对多关系？

Question

假设您有两个实体，Player 和 Team，玩家可以在多个团队中。在我的数据模型中，每个实体都有一个表，以及一个用于维护关系的连接表。 Hibernate 可以很好地处理这个问题，但是我如何在 RESTful API 中公开这种关系？

我可以想到几种方法。首先，我可能让每个实体都包含另一个实体的列表，因此 Player 对象将具有它所属的 Teams 列表，并且每个 Team 对象将具有属于它的 Player 列表。因此，要将玩家添加到团队中，您只需 POST 将玩家的表示形式发送到端点，例如 POST /player 或 POST /team，并将适当的对象作为请求的有效负载。这对我来说似乎是最“RESTful”的，但感觉有点奇怪。

/api/team/0:

{
    name: 'Boston Celtics',
    logo: '/img/Celtics.png',
    players: [
        '/api/player/20',
        '/api/player/5',
        '/api/player/34'
    ]
}

/api/player/20:

{
    pk: 20,
    name: 'Ray Allen',
    birth: '1975-07-20T02:00:00Z',
    team: '/api/team/0'
}

我能想到的另一种方法是将关系本身作为一种资源公开。因此，要查看给定团队中所有玩家的列表，您可以执行 GET /playerteam/team/{id} 或类似的操作，然后返回 PlayerTeam 实体列表。要将玩家添加到团队，请使用适当构建的 PlayerTeam 实体作为有效负载发布 /playerteam。

/api/team/0:

{
    name: 'Boston Celtics',
    logo: '/img/Celtics.png'
}

/api/player/20:

{
    pk: 20,
    name: 'Ray Allen',
    birth: '1975-07-20T02:00:00Z',
    team: '/api/team/0'
}

/api/player/team/0/:

[
    '/api/player/20',
    '/api/player/5',
    '/api/player/34'
]

这方面的最佳做法是什么？

Answer 1

制作一组单独的/memberships/ 资源。

1. REST 是关于制作可进化的系统，如果没有别的。此时，您可能只关心给定球员是否在给定球队，但在未来的某个时候，您会希望用更多数据来注释这种关系：他们已经待了多久在那个团队，谁把他们推荐给那个团队，他们的教练是谁/在那个团队时是谁，等等。
2. REST 依赖于缓存来提高效率，这需要考虑缓存原子性和失效。如果您向/teams/3/players/ 发布一个新实体，该列表将失效，但您不希望备用 URL /players/5/teams/ 保持缓存状态。是的，不同的缓存会有不同年龄的每个列表的副本，我们对此无能为力，但我们至少可以通过限制我们需要使无效的实体数量来最大限度地减少用户发布更新的混乱在他们客户的本地缓存中只有一个在/memberships/98745（有关更详细的讨论，请参阅Helland 在Life beyond Distributed Transactions 中对“备用索引”的讨论）。
3. 您可以通过简单地选择/players/5/teams 或/teams/3/players（但不能同时选择两者）来实现上述两点。让我们假设前者。然而，在某些时候，您可能希望将/players/5/teams/ 保留为当前 成员资格列表，但仍可以在某处引用过去 成员资格。将/players/5/memberships/ 设为/memberships/{id}/ 资源的超链接列表，然后您可以根据需要添加/players/5/past_memberships/，而无需打破每个人对单个会员资源的书签。这是一个笼统的概念；我相信您可以想象其他类似的未来更适用于您的具体情况。

Answer 2

在 RESTful 接口中，您可以通过将这些关系编码为链接来返回描述资源之间关系的文档。因此，可以说一个团队有一个文档资源 (/team/{id}/players)，它是团队中球员 (/player/{id}) 的链接列表，而一个球员可以有一个文档资源 (/player/{id}/teams)，它是玩家所属球队的链接列表。漂亮而对称。您可以轻松地在该列表上进行地图操作，甚至为关系提供自己的 ID（可以说它们有两个 ID，具体取决于您是考虑团队优先还是玩家优先的关系），如果这会让事情变得更容易.唯一棘手的一点是，如果您从一端删除它，您必须记住从另一端删除关系，但是通过使用底层数据模型严格处理这个问题，然后让 REST 接口成为该模型将使这变得更容易。

关系 ID 可能应该基于 UUID 或同样长且随机的东西，而不管您为球队和球员使用的任何类型的 ID。这将让您在关系的每一端都使用与 ID 组件相同的 UUID，而不必担心冲突（小整数 不 有这个优势）。如果这些成员关系除了以双向方式将球员和球队联系起来之外还有其他任何属性，那么他们应该有自己的身份，独立于球员和球队；然后，玩家»团队视图 (/player/{playerID}/teams/{teamID}) 上的 GET 可以将 HTTP 重定向到双向视图 (/memberships/{uuid})。

我建议使用XLinkxlink:href 属性在您返回的任何 XML 文档中编写链接（当然，如果您恰好生成 XML）。

Answer 3

我会将这种关系映射到子资源，一般设计/遍历将是：

# team resource /teams/{teamId} # players resource /players/{playerId} # teams/players subresource /teams/{teamId}/players/{playerId}

在 RESTful 术语中，它有助于不考虑 SQL 和连接，而是更多地考虑集合、子集合和遍历。

一些例子：

# getting player 3 who is on team 1 # or simply checking whether player 3 is on that team (200 vs. 404) GET /teams/1/players/3 # getting player 3 who is also on team 3 GET /teams/3/players/3 # adding player 3 also to team 2 PUT /teams/2/players/3 # getting all teams of player 3 GET /players/3/teams # withdraw player 3 from team 1 (appeared drunk before match) DELETE /teams/1/players/3 # team 1 found a replacement, who is not registered in league yet POST /players # from payload you get back the id, now place it officially to team 1 PUT /teams/1/players/44

如您所见，我不使用 POST 将球员分配到球队，而是使用PUT，它可以更好地处理球员和球队之间的 n:n 关系。

Answer 4

我首选的解决方案是创建三个资源：Players、Teams 和 TeamsPlayers。

因此，要获取团队的所有球员，只需转到 Teams 资源并通过调用 GET /Teams/{teamId}/Players 获取其所有球员。

另一方面，要获取玩家参加过的所有球队，请获取Players 中的Teams 资源。致电GET /Players/{playerId}/Teams。

并且，要获得多对多关系，请调用 GET /Players/{playerId}/TeamsPlayers 或 GET /Teams/{teamId}/TeamsPlayers。

请注意，在此解决方案中，当您调用GET /Players/{playerId}/Teams 时，您将获得一个Teams 资源数组，这与您在调用GET /Teams/{teamId} 时获得的资源完全相同。反之亦然，调用GET /Teams/{teamId}/Players时得到Players资源数组。

在任一调用中，都不会返回有关关系的信息。例如，不返回contractStartDate，因为返回的资源没有关于关系的信息，只有关于它自己的资源。

要处理 n-n 关系，请调用 GET /Players/{playerId}/TeamsPlayers 或 GET /Teams/{teamId}/TeamsPlayers。这些调用返回的正是资源TeamsPlayers。

此TeamsPlayers 资源具有id、playerId、teamId 属性，以及其他一些描述关系的属性。此外，它具有处理它们所需的方法。 GET、POST、PUT、DELETE 等将返回、包含、更新、删除关系资源。

TeamsPlayers 资源实现了一些查询，例如GET /TeamsPlayers?player={playerId} 以返回由{playerId} 标识的玩家拥有的所有TeamsPlayers 关系。按照同样的思路，使用GET /TeamsPlayers?team={teamId}返回TeamsPlayers在{teamId}队伍中打过的所有TeamsPlayers。 在任一GET 调用中，都会返回资源TeamsPlayers。返回关系相关的所有数据。

当调用GET /Players/{playerId}/Teams（或GET /Teams/{teamId}/Players）时，资源Players（或Teams）调用TeamsPlayers使用查询过滤器返回相关球队（或球员）。

GET /Players/{playerId}/Teams 是这样工作的：

1. 查找 player 具有 id = playerId 的所有 TeamsPlayers。 (GET /TeamsPlayers?player={playerId})
2. 循环返回的TeamsPlayers
3. 使用从TeamsPlayers获取的teamId，调用GET /Teams/{teamId}并存储返回的数据
4. 循环结束后。返回所有参与循环的团队。

您可以使用相同的算法从一个团队中获取所有球员，当调用GET /Teams/{teamId}/Players 时，但交换球队和球员。

我的资源如下所示：

/api/Teams/1:
{
    id: 1
    name: 'Vasco da Gama',
    logo: '/img/Vascao.png',
}

/api/Players/10:
{
    id: 10,
    name: 'Roberto Dinamite',
    birth: '1954-04-13T00:00:00Z',
}

/api/TeamsPlayers/100
{
    id: 100,
    playerId: 10,
    teamId: 1,
    contractStartDate: '1971-11-25T00:00:00Z',
}

此解决方案仅依赖于 REST 资源。尽管可能需要一些额外的调用来从球员、球队或他们的关系中获取数据，但所有 HTTP 方法都很容易实现。 POST、PUT、DELETE 简单明了。

每当创建、更新或删除关系时，Players 和 Teams 资源都会自动更新。

Answer 5

现有的答案并没有解释一致性和幂等性的作用 - 这促使他们建议使用UUIDs/随机数作为 ID 和 PUT 而不是 POST。

如果我们考虑一个简单的场景，例如“将新玩家添加到团队”，我们会遇到一致性问题。

由于播放器不存在，我们需要：

POST /players { "Name": "Murray" } //=> 201 /players/5
POST /teams/1/players/5

但是，如果在 POST 到 /players 之后客户端操作失败，我们创建了一个不属于团队的玩家：

POST /players { "Name": "Murray" } //=> 201 /players/5
// *client failure*
// *client retries naively*
POST /players { "Name": "Murray" } //=> 201 /players/6
POST /teams/1/players/6

现在我们在/players/5 中有一个孤立的重复播放器。

为了解决这个问题，我们可能会编写自定义恢复代码来检查与某些自然键匹配的孤立玩家（例如Name）。这是需要测试的自定义代码，需要花费更多的金钱和时间等

为了避免需要自定义恢复代码，我们可以实现PUT 而不是POST。

来自RFC：

PUT 的意图是幂等的

要使操作具有幂等性，它需要排除外部数据，例如服务器生成的 id 序列。这就是为什么人们将PUT 和UUIDs 一起推荐给Ids。

这允许我们重新运行 /players PUT 和 /memberships PUT 而不会产生任何后果：

PUT /players/23lkrjrqwlej { "Name": "Murray" } //=> 200 OK
// *client failure*
// *client YOLOs*
PUT /players/23lkrjrqwlej { "Name": "Murray" } //=> 200 OK
PUT /teams/1/players/23lkrjrqwlej

一切都很好，除了部分失败重试之外，我们不需要做任何事情。

这更像是对现有答案的补充，但我希望它将它们置于 ReST 的灵活和可靠程度的大背景下。

Answer 6

我知道这个问题的答案标记为已接受，但是，我们可以通过以下方式解决之前提出的问题：

假设 PUT

PUT    /membership/{collection}/{instance}/{collection}/{instance}/

例如，以下所有操作都将产生相同的效果，而无需同步，因为它们是在单个资源上完成的：

PUT    /membership/teams/team1/players/player1/
PUT    /membership/players/player1/teams/team1/

现在，如果我们想为一个团队更新多个成员资格，我们可以执行以下操作（通过适当的验证）：

PUT    /membership/teams/team1/

{
    membership: [
        {
            teamId: "team1"
            playerId: "player1"
        },
        {
            teamId: "team1"
            playerId: "player2"
        },
        ...
    ]
}

Answer 7

1. /players（是主资源）
2. /teams/{id}/players（是关系资源，所以它的反应与1不同）
3. /memberships（是一种关系，但语义复杂）
4. /players/memberships（是一种关系，但语义复杂）

我更喜欢 2