接口（Api）版本号命名规则

痛定思痛。 2023-07-12 09:13 31阅读 0赞

# 0. 前言 #

**版本号的命名和更新问题，是开发者的责任感和前瞻性的问题。**

# 1. 项目立项时 #

> 版本格式：0.0.0

# 2. 开发阶段时 #

此时系统尚不稳定，随时可能增减或者修正API。

> 版本格式：0.次版本号.修订号，版本号递增规则如下：
> 
> 1.  主版本号：0表示正在开发阶段；
> 2.  次版本号：增加新的功能时增加；
> 3.  修订号：只要有改动就增加。

# 3. 开发完成后，发布API，或进入二方库时 #

此时系统已经基本稳定，可以对外公布使用，意味着API不再会被随意修改。

> 版本格式：1.0.0

# 4. 后续的维护升级时 #

没有特殊需求不会修改API，尤其是对API进行不兼容的升级，或弃用时要特别谨慎。如果需要弃用API，要提前在一个或几个版本中加入弃用标示或注解，并在文档中，建议用户更换为其他可替换的API，然后在下个主版本号升级时，再真正丢掉弃用的API。

> 版本格式：主版本号.次版本号.修订号，版本号递增规则如下：
> 
> 1.  主版本号：全盘重构时增加；重大功能或方向改变时增加；大范围不兼容之前的接口时增加；
> 2.  次版本号：增加新的业务功能时增加；
> 3.  修订号：增加新的接口时增加；在接口不变的情况下，增加接口的非必填属性时增加；增强和扩展接口功能时增加。

新增接口：如果该新增的接口只是对现有的业务线进行扩展则增加修订号；如果是为了增加新的业务线则增加次版本号。

# 5. 先行版本号和开发版本号 #

先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸。

> 1.  先行版本号(Pre-release)：意味该版本不稳定，可能存在兼容性问题。 其格式为：X.Y.Z.\[a-c\]\[正整数\]，如 1.0.0.a1，1.0.0.b99，1.0.0.c1000。
> 2.  开发版本号：常用于 CI-CD（持续集成和持续交付）。 格式为 X.Y.Z-dev\[正整数\]，如 1.0.1-dev4。
> 3.  版本号的排序规则为依次比较主版本号、次版本号和修订号的数值，如 1.0.0 < 1.0.1 < 1.1.1 < 2.0.0；对于先行版本号和开发版本号，有：1.0.0.a100 < 1.0.0，2.1.0-dev3 < 2.1.0；当存在字母时，以 ASCII 的排序来比较，如 1.0.0.a1 < 1.0.0.b1。

# *特别注意：* #

***1. 版本一经发布，不得修改其内容，任何修改必须在新版本发布！***  
***2. 在接口还没有确定下来的时候，应该先使用开发版本号。***  
*3. 业务功能 > 功能 > 接口*

> **推荐阅读：**  
> [版本号命名指南][Link 1]  
> [版本号命名规则-语义化版本 2.0.0 | Semantic Versioning][-_ 2.0.0 _ Semantic Versioning]

————————————————  
版权声明：本文为CSDN博主「frcoder」的原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接及本声明。  
原文链接：[https://blog.csdn.net/u012107143/article/details/78731272][-_ 2.0.0 _ Semantic Versioning]

[Link 1]: http://wsfdl.com/devops/2016/09/27/%E7%89%88%E6%9C%AC%E5%8F%B7.html
[-_ 2.0.0 _ Semantic Versioning]: https://semver.org/lang/zh-CN/