REST API 中更新子资源的约定

基础概念

在RESTful API设计中，子资源（也称为嵌套资源）是指与父资源有从属关系的资源。例如，/posts/{postId}/comments中的comments就是posts的子资源。

更新子资源的标准约定

1. HTTP方法

更新子资源通常使用PATCH（部分更新）或PUT（完全替换）方法。

2. URL结构

子资源的更新URL通常遵循以下模式：

PUT /parent-resource/{parent-id}/child-resource/{child-id}

3. 请求体

请求体应包含要更新的字段及其新值。

常见实现方式

部分更新（PATCH）

PATCH /posts/123/comments/456
Content-Type: application/json

{
  "content": "更新后的评论内容"
}

完全替换（PUT）

PUT /posts/123/comments/456
Content-Type: application/json

{
  "content": "全新的评论内容",
  "author": "张三",
  "createdAt": "2023-01-01T00:00:00Z"
}

响应约定

• 成功更新应返回200 OK（带有更新后的完整资源）或204 No Content
• 如果资源不存在但被创建，可返回201 Created
• 验证失败应返回400 Bad Request
• 未授权应返回401 Unauthorized
• 无权限应返回403 Forbidden

优势

1. 清晰的资源层次：明确表示资源间的关系
2. 一致性：遵循REST原则，易于理解和预测
3. 安全性：通过URL结构自然实现访问控制

应用场景

• 博客系统中的评论管理
• 电子商务中的订单项更新
• 文件系统中的子目录/文件操作
• 社交网络中的用户关系管理

常见问题及解决方案

问题1：深度嵌套导致URL过长

解决方案：考虑扁平化设计或使用查询参数，如/comments/456?postId=123

问题2：批量更新子资源

解决方案：提供专门的批量端点，如：

PATCH /posts/123/comments
Content-Type: application/json

[
  {"id": 456, "content": "更新1"},
  {"id": 789, "content": "更新2"}
]

问题3：部分更新与完全更新的混淆

解决方案：明确区分PATCH和PUT的语义，并在API文档中清晰说明。

最佳实践

1. 优先使用PATCH进行部分更新
2. 为嵌套资源提供单独的文档
3. 考虑支持JSON Merge Patch或JSON Patch格式
4. 在响应中包含Location头指向更新后的资源
5. 实现乐观锁机制防止并发冲突