HTTP状态码之201 Created的含义与应用

HTTP状态码之201 Created的含义与应用

1. 介绍

1.1 什么是HTTP状态码

HTTP状态码是由服务器返回给客户端的三位数字代码，用于表示HTTP请求的处理结果。每个状态码都有特定的含义，用于告知客户端请求的处理情况。

1.2 HTTP状态码的分类

HTTP状态码按照第一位数字的不同，可以分为以下五类：

• 1xx：信息性状态码，表示请求已被接受，继续处理。
• 2xx：成功状态码，表示请求已成功被服务器接收、理解和处理。
• 3xx：重定向状态码，表示需要进一步操作以完成请求。
• 4xx：客户端错误状态码，表示客户端发送的请求有误。
• 5xx：服务器错误状态码，表示服务器在处理请求时发生了错误。

1.3 201 Created的含义

201 Created是HTTP状态码中的一个成功状态码，表示服务器成功处理了请求，并且创建了新的资源。通常在处理POST请求时返回该状态码。

2. 201 Created的详细解释

2.1 201 Created的定义

201 Created状态码表示服务器已成功处理了请求，并且创建了新的资源。该状态码通常在POST请求的响应中返回，用于告知客户端新资源的位置。

2.2 201 Created的应用场景

201 Created状态码通常在以下情况下使用：

• 创建新的资源：当客户端发送POST请求用于创建新的资源时，服务器成功创建了资源，并返回201 Created状态码。
• 返回新资源的位置：201 Created状态码的响应头部会包含Location头部信息，用于指示新资源的位置。

2.3 201 Created的示例

下面是一个示例，演示了如何使用201 Created状态码来创建新的资源：

POST /api/users HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

HTTP/1.1 201 Created
Location: /api/users/123
Content-Type: application/json

{
  "id": 123,
  "name": "John",
  "email": "john@example.com"
}

在上面的示例中，客户端发送了一个POST请求来创建新的用户资源。服务器成功创建了用户，并返回了201 Created状态码。响应头部中的Location信息指示了新创建资源的位置。

3. 201 Created的使用注意事项

3.1 201 Created与200 OK的区别

201 Created和200 OK都是成功状态码，但它们之间有一些区别：

• 201 Created表示服务器成功创建了新的资源，而200 OK表示服务器成功处理了请求。
• 201 Created通常在POST请求的响应中返回，而200 OK可以在各种类型的请求中返回。

3.2 如何正确使用201 Created

为了正确使用201 Created状态码，需要注意以下事项：

• 只有在成功创建新资源时才返回201 Created状态码。
• 响应头部中应包含Location头部信息，指示新资源的位置。
• 响应体中可以包含新资源的详细信息，以便客户端获取更多信息。

3.3 常见的错误使用方式

以下是一些常见的错误使用201 Created状态码的方式：

• 返回201 Created状态码，但没有包含Location头部信息。
• 返回201 Created状态码，但没有提供新资源的详细信息。
• 返回201 Created状态码，但在响应体中没有提供新资源的详细信息。

这些错误使用方式可能会导致客户端无法正确获取到新资源的位置或详细信息，从而影响客户端的后续操作。

4. 201 Created的相关HTTP头部信息

4.1 Location头部信息

在201 Created的响应中，通常会包含Location头部信息。该头部信息用于指示新资源的位置。客户端可以通过该信息来获取新资源的详细内容。

例如，在上面的示例中，服务器返回了以下Location头部信息：

Location: /api/users/123

这告诉客户端新创建的用户资源位于/api/users/123的位置。

4.2 Content-Location头部信息

除了Location头部信息之外，有时候还可以使用Content-Location头部信息。Content-Location头部信息用于指示当前返回的实体的位置。

例如，在获取某个资源的详细信息时，服务器返回了以下Content-Location头部信息：

Content-Location: /api/users/123

这告诉客户端当前返回的实体位于/api/users/123的位置。

4.3 ETag头部信息

ETag头部信息是一个用于标识资源的字符串。它可以用于缓存验证和乐观并发控制。

在201 Created的响应中，通常不会包含ETag头部信息，因为这是一个新创建的资源，没有之前的版本。

5. 实际应用案例分析

5.1 使用201 Created的Web开发实例

假设我们正在开发一个博客系统，用户可以通过POST请求创建新的博客文章。服务器成功创建了博客文章后，应返回201 Created状态码和新博客文章的位置。

以下是一个使用Node.js和Express框架的示例代码：

app.post('/api/articles', (req, res) => {
  // 创建新的博客文章
  const newArticle = createArticle(req.body);

  // 返回201 Created状态码和新博客文章的位置
  res.status(201).location(`/api/articles/${newArticle.id}`).json(newArticle);
});

上面的代码中，我们使用Express框架定义了一个POST请求的路由。在路由处理程序中，我们创建了新的博客文章，并将其保存到数据库中。然后，我们使用res.status(201).location()方法设置了响应的状态码和Location头部信息。最后，我们使用res.json()方法返回新博客文章的详细信息。

5.2 使用201 Created的API设计实例

假设我们正在设计一个RESTful API，用于管理用户的收货地址。用户可以通过POST请求创建新的收货地址。服务器成功创建了收货地址后，应返回201 Created状态码和新收货地址的位置。

以下是一个使用Spring Boot框架的Java示例代码：

@PostMapping("/api/addresses")
@ResponseStatus(HttpStatus.CREATED)
public ResponseEntity<Address> createAddress(@RequestBody Address address) {
  // 创建新的收货地址
  Address newAddress = addressService.createAddress(address);

  // 返回201 Created状态码和新收货地址的位置
  URI location = ServletUriComponentsBuilder.fromCurrentRequest()
                        .path("/{id}")
                        .buildAndExpand(newAddress.getId())
                        .toUri();
  return ResponseEntity.created(location).body(newAddress);
}

上面的代码中，我们使用Spring Boot框架的注解来定义一个POST请求的路由。在方法中，我们调用了一个服务类的方法来创建新的收货地址，并将其保存到数据库中。然后，我们使用ResponseEntity.created()方法设置了响应的状态码和Location头部信息。最后，我们使用ResponseEntity.body()方法返回新收货地址的详细信息。

6. 其他常见的HTTP状态码

除了201 Created状态码，还有许多其他常见的HTTP状态码，用于表示不同的请求处理情况。以下是一些常见的HTTP状态码：

• 200 OK：表示请求已成功被服务器接收、理解和处理。
• 301 Moved Permanently：表示请求的资源已永久移动到新的位置。
• 400 Bad Request：表示客户端发送的请求有误，服务器无法理解。
• 404 Not Found：表示请求的资源不存在。
• 500 Internal Server Error：表示服务器在处理请求时发生了错误。

这些状态码在不同的情况下会被服务器返回，用于告知客户端请求的处理结果。

7. 总结

通过本文的介绍，我们了解了HTTP状态码中的201 Created状态码的含义和应用场景。我们了解到，201 Created表示服务器成功处理了请求，并且创建了新的资源。我们还学习了如何正确使用201 Created状态码，并注意了一些常见的错误使用方式。此外，我们还了解了与201 Created相关的HTTP头部信息，例如Location、Content-Location和ETag。最后，我们通过实际应用案例分析，展示了如何在Web开发和API设计中使用201 Created状态码。

8. 参考资料

• RFC 7231 – Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content
• HTTP Status Codes