crates.io: API 状态码变更

2024 年 2 月 6 日 · Tobias Bieniek 代表 crates.io 团队

Cargo 和 crates.io 是在 Rust 1.0 发布前的匆忙中开发的，目的是满足管理依赖项的工具和人们可以用来共享代码的注册表的需求。这种快速的工作导致这些工具与一个 API 连接，该 API 最初没有返回正确的 HTTP 响应状态码。在 Rust 1.0 发布之后，Rust 关于向后兼容性的稳定性保证使得修复这个问题变得不那么容易，因为我们希望旧版本的 Cargo 继续与当前的 crates.io API 一起工作。

当旧版本的 Cargo 收到非“200 OK” 响应时，它会像这样显示原始的 JSON 正文

error: failed to get a 200 OK response, got 400
headers:
    HTTP/1.1 400 Bad Request
    Content-Type: application/json; charset=utf-8
    Content-Length: 171

body:
{"errors":[{"detail":"missing or empty metadata fields: description, license. Please see https://doc.rust-lang.net.cn/cargo/reference/manifest.html for how to upload metadata"}]}

这个问题在拉取请求 #6771 中得到了改进，该请求在 Cargo 1.34（2019 年年中）中发布。从那时起，Cargo 也支持接收 4xx 和 5xx 状态码，并从 JSON 响应中提取错误消息（如果可用）。

在 2024-03-04，我们将把 API 从返回错误的“200 OK”状态码切换到新的 4xx/5xx 行为。Cargo 1.33 及更低版本在此更改后仍将继续工作，但会显示原始的 JSON 正文，而不是格式良好的错误消息。我们相信这种降级的错误消息显示不会影响很多用户。根据 crates.io 请求日志，只有极少数请求是由 Cargo 1.33 及更旧版本发出的。

以下是受此更改影响的 API 端点列表

  • GET /api/v1/crates
  • PUT /api/v1/crates/new
  • PUT /api/v1/crates/:crate/:version/yank
  • DELETE /api/v1/crates/:crate/:version/unyank
  • GET /api/v1/crates/:crate/owners
  • PUT /api/v1/crates/:crate/owners
  • DELETE /api/v1/crates/:crate/owners

所有其他端点已经使用标准的 HTTP 状态码一段时间了。

如果您仍在使用 Cargo 1.33 或更旧版本，我们建议您升级到较新的版本，以获得改进的错误消息以及 Cargo 团队此后构建的所有其他好东西。