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

本文链接：https://blog.csdn.net/u012107143/article/details/78731272

0. 前言

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

1. 项目立项时

版本格式：0.0.0

2. 开发阶段时

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

版本格式：0.次版本号.修订号，版本号递增规则如下：

主版本号：0表示正在开发阶段；

次版本号：增加新的功能时增加；

修订号：只要有改动就增加。

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

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

版本格式：1.0.0

4. 后续的维护升级时

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

版本格式：主版本号.次版本号.修订号，版本号递增规则如下：

主版本号：全盘重构时增加；重大功能或方向改变时增加；大范围不兼容之前的接口时增加；

次版本号：增加新的业务功能时增加；

修订号：增加新的接口时增加；在接口不变的情况下，增加接口的非必填属性时增加；增强和扩展接口功能时增加。

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

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

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

先行版本号(Pre-release)：意味该版本不稳定，可能存在兼容性问题。 其格式为：X.Y.Z.[a-c][正整数]，如 1.0.0.a1，1.0.0.b99，1.0.0.c1000。

开发版本号：常用于 CI-CD（持续集成和持续交付）。 格式为 X.Y.Z-dev[正整数]，如 1.0.1-dev4。

版本号的排序规则为依次比较主版本号、次版本号和修订号的数值，如 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. 业务功能 > 功能 > 接口

推荐阅读：

版本号命名指南

版本号命名规则-语义化版本 2.0.0 | Semantic Versioning