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 团队自那时以来构建的所有其他好东西。