你有没有遇到过这种情况：公司上线了一个新功能，结果手机App突然打不开了？点哪儿都报错。一查原因，原来是后台接口改了，但App没更新，两边对不上号。这种问题在开发里太常见了，而解决它的关键，往往就藏在一个小细节里——API是否带版本号。
什么是API版本号？
简单说，就是在请求接口的时候，URL里带个v1、v2这样的标记。比如：
https://api.example.com/v1/users
这里的 v1 就是版本号。它告诉调用方：“我现在是第一版，别随便动我。”
不加版本号会怎样？
想象一下你家楼下那家早餐店。老板每天换菜单，昨天卖豆浆油条，今天突然只卖咖啡三明治，老顾客一来发现啥也吃不了，肯定骂街。API也一样。如果不带版本，一旦改动，所有依赖它的客户端（比如App、网页）可能瞬间崩溃。
有些团队图省事，一开始不加版本号，觉得“反正就一个版本”。可等用户多了，想改接口就得求爷爷告奶奶让所有人同步更新，根本做不到。
加了版本号怎么用？
当你决定升级接口时，可以保留旧的 /v1 不动，再加个 /v2 上线新逻辑。老用户还能继续用，新用户慢慢迁移。就像地铁站改造，一边修新出口，一边留着旧通道，谁都不耽误。
举个例子：
GET /v1/users -amp;gt; 返回 {id, name, email}
GET /v2/users -amp;gt; 返回 {id, full_name, email, avatar_url}字段变了、结构变了，但老系统照样跑得好好的。
版本号放哪儿合适？
最常见的就是放在URL路径里，像上面那样。也有人喜欢放请求头里，比如 Accept: application/vnd.myapp.v2+json。但对新手来说，URL里带版本最直观，一眼就知道自己调的是哪一版。
是不是每个API都得加？
也不是死规矩。如果你做的内部小工具，只有你自己调，改起来方便，先不加也行。但只要接口对外暴露，哪怕只是给合作方用，最好一开始就带上版本号。别信“以后再说”，等真出问题了，补救成本远比你提前设计高得多。
很多大厂的公开API，比如微信、支付宝、微博，全都在URL里明确标了版本。这不是巧合，是踩过太多坑才定下的规范。
小步迭代比大改更友好
有了版本号，并不意味着可以随便 breaking change（破坏性变更）。理想的做法是：尽量让新版本兼容旧的，比如新增字段而不是删改原有字段。等大部分用户迁走了，再找个时间下线旧版。这样平滑过渡，谁都不会被突然打断。