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 年 3 月 4 日，我们将把 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 团队自那时以来构建的所有其他优秀功能。