接口(Api)版本號命名規則

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. 業務功能 > 功能 > 接口

推薦閱讀:
版本號命名指南
版本號命名規則-語義化版本 2.0.0 | Semantic Versioning

————————————————
版權聲明:本文爲CSDN博主「frcoder」的原創文章,遵循 CC 4.0 BY-SA 版權協議,轉載請附上原文出處鏈接及本聲明。
原文鏈接:https://blog.csdn.net/u012107143/article/details/78731272

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章