004-REST-使用 HTTP 方法进行 RESTful 服务

最新推荐文章于 2024-08-03 20:43:02 发布

时间会告诉你答案，但不能重来

最新推荐文章于 2024-08-03 20:43:02 发布

阅读量702

点赞数

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/dejunyang/article/details/91351550

REST 同时被 3 个专栏收录

4 篇文章

订阅专栏

RESTful

4 篇文章

订阅专栏

RESTful

4 篇文章

订阅专栏

本文深入解析HTTP谓词，包括POST、GET、PUT、PATCH和DELETE，探讨其在资源操作中的应用，如创建、读取、更新和删除。文章还详细说明了每种方法的返回值及建议使用场景。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

    HTTP 谓词构成了我们“统一接口”约束的主要部分，并为我们提供了与基于名词的资源相对应的动作。 主要或最常用的 HTTP 谓词（或正确调用的方法）是 POST，GET，PUT，PATCH和DELETE。 它们分别对应于创建，读取，更新和删除（或CRUD）操作。 还有许多其他动词，但使用频率较低。 在那些不常用的方法中，OPTIONS 和 HEAD 的使用频率高于其他方法。

下面的表总结了主要 HTTP 方法与资源 URI 结合使用的建议返回值：

HTTP 动词	CRUD	整个集合(e.g. /customers)	特定 item(e.g./customers/{id})
POST	Create	201(已创建)，‘Location’ header，其中包含指向/customers/{id}的链接，其中包含新 ID	404(未找到)，409(冲突)，如果资源已存在
GET	Read	200(OK),客户列表。使用分页，排序和过滤来导航大列表	200(OK),单个客户。404(未找到)，如果找不到ID或无效
PUT	Update/Replace	405(方法不允许)，除非你要更新/替换整个集合中的每个资源	200(OK),或204(无内容)，404(未找到)，如果找不大ID或无效
PATCH	Update/Modify	405(方法不允许)，除非你想要修改集合本身	200(OK)，或204(无内容)，404(未找到)，如果找不到ID或无效
DELETE	Delete	405(方法不允许)，除非你想删除整个集合-通常不需要	200(OK)，404(为找到)，如果找不到ID或无效

POST

    POST 动词最常用于创建**新资源。特别是，它用于创建从属资源。也就是说，从属于其他一些(eg. parent)资源。换句话说，在创建新资源时，对父服务器和服务的 POST 负责将新资源与父资源相关联，分配 ID(新资源URI)等。
    
    成功创建后，返回 HTTP 状态 201，返回 Location header，其中包含指向具有 201 HTTP 状态的新创建资源的链接。
    
    POST 即不安全也不是幂等。因此，建议用于非幂等资源请求。制作两个相同的 POST 请求最有可能导致两个资源包含相同的信息。
示例：
    - POST http://www.example.com/customers
    - POST http://www.example.com/customers/12345/orders

GET

    HTTP GET 方法用于**读取(或检索)资源的表示。在”happy“(或非错误)路径中，GET 以 XML 或 JSON 格式返回表示形式，并返回 HTTP 响应代码200(OK)。在错误情况下，它通常返回 404 或 400。
    
    根据 HTTP 规范的设计，GET(以及 HEAD)请求仅用于读取数据而不是更改它。因此，当以这种方式使用时，它们被认为是安全的。也就是说，可以调用它们而不存在数据修改或损坏风险-调用它一次具有与调用它 10 次相同的效果，或者根本没有。此外，GET(和 HEAD)是幂等的，这意味着生成多个相同的请求最终会产生与单个请求相同的结果。
    
    不要通过 GET 公开不安全的操作-它永远不应该修改服务器上的任何资源。

示例：
    - GET http://www.example.com/customers/12345
    - GET http://www.example.com/customers/12345/orders
    - GET http://www.example.com/buckets/sample

PUT

    PUT 最常用于”更新“功能，与一直资源 URI 一起使用，请求体包含原始资源的新更新表示。
    
    但是，在客户端而不是服务器选择资源 ID 的情况下，PUT 也可用于创建资源。换句话说，如果 PUT 是包含不存在的资源 ID 的值得 URI。同样，请求体包含资源表示。许多人认为这是令人费解和困惑的。因此，如果有的话，应谨慎使用这种创作方法。
    
    成功更新后，从 PUT 返回 200(如果未返回正文中的任何内容，则返回 204)。如果使用 PUT 进行创建，则在成功创建时返回 HTTP 状态 201.响应中的主体是可选的-提供一个小号更多带宽。由于客户端已经设置了资源ID，因此无需在创建案例中通过 Location header 返回链接。
    
    PUT 不是一个安全的操作，因为它修改(或创建)服务器上的状态，但他是幂等的。换句话说，如果你使用 PUT 创建或更新资源，然后再次进行相同的调用，则资源仍然存在，并且仍让具有与第一次调用时相同的状态。
    
    例如，如果在资源上调用 PUT 会增加资源中的计数器，则该调用不再是幂等的。有时会发生这种情况，并且可能足以证明呼叫不是幂等的。但是，建议保持 PUT 请求是幂等的。强烈建议对非幂等请求使用 POST。
    
示例：
    - PUT http://www.example.com/customers/12345
    - PUT http://www.example.com/customers/12345/orders/98756
    - PUT http://www.example.com/buckets/secret_stuff

PATCH

    PATCH 用于”修改“功能。PATCH 请求只需要包含对资源的更改，而不是完整的哀怨。
    
    这类似于 PUT，但正文包含一组指令，描述如何修改当前驻留在服务器上的资源以生成新版本。这意味着 PATCH 主体不应该仅仅是资源的修改部分，而是某种 PATCH 语言，如 JSON Patch 或 XML Patch。
    
    PATCH 既不安全又不幂等。然而，PATCH 如何可以以幂等方式发布，这也有助于防止在相似时间帧内相同资源上的两个 PATCH 请求之间的冲突导致的不良结果。来自多个 PATCH 请求的冲突可能比 PUT 冲突更危险，因为某些 PATCH 格式需要从一直的基点操作，否则他们将破坏资源。使用此类 PATCH 应用程序的客户端使用条件请求，以便在客户端上次访问资源后资源已更新时请求将失败。例如，客户端可以在 PATCH 请求的 If-Match header 中使用强 ETag。

示例：
    - PATCH http://www.example.com/customers/12345
    - PATCH http://www.example.com/customers/12345/orders/98765
    - PATCH http://www.example.com/buckets/secret_stuff

DELETE

    DELETE很容易理解。它用于**删除由URI标识的资源。
    
    成功删除后，返回HTTP状态200（OK）以及响应正文，可能是已删除项目的表示（通常需要太多带宽），或者包装响应（请参阅下面的返回值）。要么是返回HTTP状态204（NO CONTENT）而没有响应正文。换句话说，建议的响应是204状态，没有正文，或JSEND样式响应和HTTP状态200。

    HTTP-spec-wise，DELETE操作是幂等的。如果删除资源，则会将其删除。在该资源上反复调用DELETE会导致相同的结果：资源消失了。如果调用DELETE说，递减计数器（在资源内），则DELETE调用不再是幂等的。如前所述，只要没有资源数据被更改，就可以更新使用统计和测量，同时仍然考虑服务幂等。建议使用POST进行非幂等资源请求。

    但是，有一个关于DELETE idempotence的警告。第二次在资源上调用DELETE通常会返回404（NOT FOUND），因为它已被删除，因此不再可查找。根据一些观点，这使得DELETE操作不再是幂等的，但是，资源的最终状态是相同的。返回404是可以接受的，并准确地传达呼叫的状态。