服務API設計之——API版本規範

API版本規範

發佈RELEASE版本

正式發佈的api包必須是RELEASE版本

eg.

1 2 3 4 5

<dependency> <groupId>cn.gov.zcy.paas.template</groupId> <artifactId>template-api</artifactId> <version>2.1.1.RELEASE</version> </dependency>

版本號風格

使用 《Semantic Versioning》風格

概述

Version號由 「MAJOR.MINOR.PATCH」 三段組合構成，version號增長含義：

1. MAJOR version：【主版本號】表明API發生了不兼容的變動，即便是微小的不兼容。
2. MINOR version：【次版本號】表明以兼容的方式新增了功能、特性
3. PATCH version：【補丁版本號】表明以兼容的方式作了bugfix

用法 / FAQ

版本號以0開始

• X.Y.Z 三個版本號都是以0開始。
• 【特別注意】當版本號是 「1.0.9.RELEASE」時，它的下一個補丁版本號是」1.0.10.RELEASE」 ！！！
  • 而不是」1.1.0.RELEASE」，這裏不存在滿十進位之說。

初始 MAJOR version

• 初始MAJOR version以0開始，表明業務的初始開發階段，這過程當中功能上任何改變均可能發生，此時的API是不穩定的。
• 初始版本一旦發佈生產環境，即將MAJOR version變動爲1，即 1.0.0.RELEASE。是第一個基線版本。

預發佈版本

• 能夠經過在補丁版本以後緊跟附加連字符和一系列點分隔標識符來表示預發佈版本。標識符必須僅包含ASCII字母數字和連字符[0-9A-Za-z-]。標識符不能爲空。數字標識符不得包含前導零。
• 預發佈版本的優先級低於關聯的普通版本。
• 預發佈版本表示版本不穩定，可能沒法知足其關聯的正常版本所表示的預期兼容性要求。示例：1.0.0-alpha，1.0.0-alpha.1,1.0.0-0.3.7,1.0.0-x.7.z.92