如何对公共Web API进行版本管理？

Lobsters Hottest 工具
api-design versioning semantic-versioning web-development best-practices

摘要

关于API版本管理实践的讨论，质疑将URL路径（例如/v1/）与语义化版本控制耦合的做法，并探讨潜在的反模式。

<p>通常存在一个名为“Product API”之类的现有API。它的路径中通常也包含/api/v1。</p> <p>对我来说，这通常感觉像是一种反模式，尤其是当API本身使用语义化版本控制时：将路由与API契约混在一起。</p> <p>在URL中包含/v1/的同时还有主版本号.次版本号.修订号的版本号：将语义化版本的第一个数字与URL路径耦合对我来说感觉不直观，如果你做出不兼容的更改，你可能需要新的路径和新的反向代理路由等等，并且你还将API契约分散到两个地方：URL和版本号。</p> <p>如果你同时开始构建一个全新的“Product API”的继任者，那么旧API实际上就会卡在“v1”上，即使它本身也有不兼容的更改。</p> <p>你怎么看？</p> <p>你有没有任何关于API设计的小烦恼或意见想要分享？</p> <p>抱歉，这可能是令人困惑的头脑风暴文本，非常想听听大家的意见。</p> <p>谢谢</p>
查看原文
查看缓存全文

缓存时间: 2026/05/29 05:52

# 如何对公共 Web API 进行版本控制？ 来源：https://lobste.rs/s/g9u6b7/how_do_you_version_public_web_apis 通常存在一个名为“Product API”之类的现有 API。它往往也在路径中包含 `/api/v1`。 对我来说，这常常感觉像是一种反模式，尤其是当 API 本身使用语义化版本控制时：将路由与 API 契约混为一谈。 在 URL 中包含 `/v1/`，同时又有一个 `major.minor.patch` 版本：将语义化版本的第一个数字与 URL 路径耦合，这让我觉得有违直觉。如果你做出破坏性变更，你可能需要新的路径和新的反向代理路由等，而且你还会将 API 契约分散到两个地方：URL 和版本号。 如果你同时开始构建“Product API”的全新后继版本，旧 API 实际上就被困在“v1”上了，即使它自身也有破坏性变更。 你怎么看？ 你有什么 API 设计上的“雷点”或见解想分享吗？ 抱歉这篇混乱的脑洞碎片，很期待听听大家的看法。 谢谢

相似文章

为何不根据链接的SDK来改变API行为？

The Old New Thing (Raymond Chen)

本文以Windows的CoInitializeSecurity为例，探讨了根据链接的SDK版本改变API行为的陷阱。讨论了DLL版本不匹配和尾调用优化等问题使这种方法复杂化。

API泛滥及其在AI社交媒体中的走向

Reddit r/artificial

本文揭示了主要平台（如X、Reddit和Stack Overflow）免费利用用户生成内容训练AI模型，随后对访问相同数据收取高昂API费用，并封禁抗议或删除自身内容的用户的模式。