How do you version public web APIs?

你是如何对公共 Web API 进行版本控制的？

Often there is an existing API called something like “Product API”. It often also has /api/v1 in the path. To me this often feels like an antipattern, especially when the API itself uses semantic versioning: mixing the routes with the API contract. 通常会存在一个名为“Product API”之类的现有 API，且其路径中往往包含 /api/v1。对我而言，这通常感觉是一种反模式（antipattern），尤其是当 API 本身已经在使用语义化版本控制（Semantic Versioning）时：这混淆了路由与 API 契约。

Having /v1/ in the URL while also having a major.minor.patch version: coupling the first number of the semantic version to the URL path feels counter intuitive to me, if you make a breaking change, you may need new paths and new reverse proxy routes, and whatnot, and you also spread the API contract to two places, the URL and the version number. 在 URL 中包含 /v1/ 的同时又拥有 major.minor.patch 版本号：将语义化版本号的首位数字与 URL 路径耦合，这让我觉得很不直观。如果你进行了破坏性更新（breaking change），可能需要新的路径、新的反向代理路由等等，而且你还将 API 契约分散到了两个地方：URL 和版本号。

If you start simultaneously building a brand new successor to the “Product API”, the old API is effectively stuck as “v1”, even if it gets breaking changes of its own. What do you think? Do you have any API design pet peeves or opinions to share? Sorry for the confusing brain dump text, very interested in hearing people’s opinions. Thank you. 如果你同时开始构建“Product API”的全新继任者，旧版 API 实际上就被困在了“v1”这个标签上，即使它自身也进行了破坏性更新。你是怎么看的？你有什么关于 API 设计的槽点或观点想分享吗？抱歉这段文字写得有些混乱，我非常希望能听到大家的意见。谢谢。