今天我們來聊一下微服務(wù)項(xiàng)目中的版本號(hào)要怎么設(shè)計(jì)。

小伙伴們平時(shí)看到的項(xiàng)目版本號(hào)，基本上都是分為了三部分 X.Y.Z，版本升級(jí)的時(shí)候版本號(hào)都會(huì)變，那么版本號(hào)怎么變，這可不是拍腦門決定的，今天我們就一起來探討一下這個(gè)話題。

## 1. 語義化版本控制規(guī)范

版本號(hào)該如何控制？其實(shí)是有一個(gè)標(biāo)準(zhǔn)規(guī)范的，規(guī)范地址：??https://semver.org/lang/zh-CN/??

這個(gè)規(guī)范非常友好的提供了中文版的內(nèi)容。

語義化的版本控制規(guī)范要求版本號(hào)由三部分構(gòu)成：

MAJOR（X）：這個(gè)是主版本號(hào)，一般是涉及到不兼容的 API 更改時(shí)，這個(gè)會(huì)變化。

MINOR（Y）：這個(gè)是次版本號(hào)，當(dāng)我們對 API 進(jìn)行向后兼容的增強(qiáng)時(shí)，這個(gè)版本號(hào)會(huì)變化，換句話說，也就是有新增的功能時(shí)，這里會(huì)變化。

PATCH（Z）：這個(gè)是修訂號(hào)，當(dāng)我們進(jìn)行一些 BUG 的修復(fù)，然后要發(fā)版的時(shí)候，這里會(huì)發(fā)生變化。

語義化的版本控制規(guī)范主要做了如下一些要求：

使用語義化版本控制的軟件必須（MUST）定義公共 API。該 API 可以在代碼中被定義或出現(xiàn)于嚴(yán)謹(jǐn)?shù)奈臋n內(nèi)。無論何種形式都應(yīng)該力求精確且完整。

標(biāo)準(zhǔn)的版本號(hào)必須（MUST）采用 X.Y.Z 的格式，其中 X、Y 和 Z 為非負(fù)的整數(shù)，且禁止（MUST NOT）在數(shù)字前方補(bǔ)零。X 是主版本號(hào)、Y 是次版本號(hào)、而 Z 為修訂號(hào)。每個(gè)元素必須（MUST）以數(shù)值來遞增。例如：1.9.1 -> 1.10.0 -> 1.11.0。

標(biāo)記版本號(hào)的軟件發(fā)行后，禁止（MUST NOT）改變該版本軟件的內(nèi)容。任何修改都必須（MUST）以新版本發(fā)行。有的小伙伴可能會(huì)說我們的項(xiàng)目處于快速開發(fā)階段，API 不穩(wěn)定，天天變，要是按照這個(gè)要求來得發(fā)多少個(gè)版本才夠用呀！其實(shí)，一般 API 快速變化主要有兩種情況，一種是項(xiàng)目剛立項(xiàng)的時(shí)候，此時(shí)主版本號(hào)為 0，那么這個(gè)時(shí)候的 API 就不能算是穩(wěn)定的 API；另外一種情況則是下個(gè)主版本處于快速開發(fā)中，但是這種情況一般會(huì)有一個(gè)新的分支用來管理下個(gè)版本的代碼，所以和這里的要求實(shí)際上并不沖突（具體參見第 4、5 條）。

主版本號(hào)為零（0.y.z）的軟件處于開發(fā)初始階段，一切都可能隨時(shí)被改變。這樣的公共 API 不應(yīng)該被視為穩(wěn)定版。

1.0.0 的版本號(hào)用于界定公共 API 的形成。這一版本之后所有的版本號(hào)更新都基于公共 API 及其修改內(nèi)容。那么有的小伙伴可能會(huì)糾結(jié)什么時(shí)候版本號(hào)從 0.Y.Z 變?yōu)?1.Y.Z 呢？一般來說，當(dāng)你的項(xiàng)目已經(jīng)上了生產(chǎn)環(huán)境或者說有穩(wěn)定的 API 提供給別人使用的時(shí)候，基本上就可以算是 1.Y.Z 了。

修訂號(hào) Z（x.y.Z | x > 0）必須（MUST）在只做了向下兼容的修正時(shí)才遞增。這里的修正指的是針對不正確結(jié)果而進(jìn)行的內(nèi)部修改。

次版本號(hào) Y（x.Y.z | x > 0）必須（MUST）在有向下兼容的新功能出現(xiàn)時(shí)遞增。在任何公共 API 的功能被標(biāo)記為棄用時(shí)也必須（MUST）遞增。也可以（MAY）在內(nèi)部程序有大量新功能或改進(jìn)被加入時(shí)遞增，其中可以（MAY）包括修訂級(jí)別的改變。每當(dāng)次版本號(hào)遞增時(shí)，修訂號(hào)必須（MUST）歸零。

主版本號(hào) X（X.y.z | X > 0）必須（MUST）在有任何不兼容的修改被加入公共 API 時(shí)遞增。其中可以（MAY）包括次版本號(hào)及修訂級(jí)別的改變。每當(dāng)主版本號(hào)遞增時(shí)，次版本號(hào)和修訂號(hào)必須（MUST）歸零。

先行版本號(hào)可以（MAY）被標(biāo)注在修訂版之后，先加上一個(gè)連接號(hào)再加上一連串以句點(diǎn)分隔的標(biāo)識(shí)符來修飾。標(biāo)識(shí)符必須（MUST）由 ASCII 字母數(shù)字和連接號(hào) [0-9A-Za-z-] 組成，且禁止（MUST NOT）留白。數(shù)字型的標(biāo)識(shí)符禁止（MUST NOT）在前方補(bǔ)零。先行版的優(yōu)先級(jí)低于相關(guān)聯(lián)的標(biāo)準(zhǔn)版本。被標(biāo)上先行版本號(hào)則表示這個(gè)版本并非穩(wěn)定而且可能無法滿足預(yù)期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。

版本編譯信息可以（MAY）被標(biāo)注在修訂版或先行版本號(hào)之后，先加上一個(gè)加號(hào)再加上一連串以句點(diǎn)分隔的標(biāo)識(shí)符來修飾。標(biāo)識(shí)符必須（MUST）由 ASCII 字母數(shù)字和連接號(hào) [0-9A-Za-z-] 組成，且禁止（MUST NOT）留白。當(dāng)判斷版本的優(yōu)先層級(jí)時(shí)，版本編譯信息可（SHOULD）被忽略。因此當(dāng)兩個(gè)版本只有在版本編譯信息有差別時(shí)，屬于相同的優(yōu)先層級(jí)。范例：1.0.0-alpha+001、1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。

版本的優(yōu)先層級(jí)指的是不同版本在排序時(shí)如何比較。

只有數(shù)字的標(biāo)識(shí)符以數(shù)值高低比較。

有字母或連接號(hào)時(shí)則逐字以 ASCII 的排序來比較。

數(shù)字的標(biāo)識(shí)符比非數(shù)字的標(biāo)識(shí)符優(yōu)先層級(jí)低。

若開頭的標(biāo)識(shí)符都相同時(shí)，欄位比較多的先行版本號(hào)優(yōu)先層級(jí)比較高。例如：1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0。

判斷優(yōu)先層級(jí)時(shí)，必須（MUST）把版本依序拆分為主版本號(hào)、次版本號(hào)、修訂號(hào)及先行版本號(hào)后進(jìn)行比較（版本編譯信息不在這份比較的列表中）。

由左到右依序比較每個(gè)標(biāo)識(shí)符，第一個(gè)差異值用來決定優(yōu)先層級(jí)：主版本號(hào)、次版本號(hào)及修訂號(hào)以數(shù)值比較。例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。

當(dāng)主版本號(hào)、次版本號(hào)及修訂號(hào)都相同時(shí)，改以優(yōu)先層級(jí)比較低的先行版本號(hào)決定。例如：1.0.0-alpha < 1.0.0。

有相同主版本號(hào)、次版本號(hào)及修訂號(hào)的兩個(gè)先行版本號(hào)，其優(yōu)先層級(jí)必須（MUST）透過由左到右的每個(gè)被句點(diǎn)分隔的標(biāo)識(shí)符來比較，直到找到一個(gè)差異值后決定：

2. 微服務(wù)中的版本號(hào)

那么在微服務(wù)中，我們的版本號(hào)該怎么設(shè)計(jì)呢？

首先，整體上的思路，就是按照上文所說的語義化版本控制規(guī)范來。

其次，上面雖然給出了很多條條框框，然而我們實(shí)際開發(fā)中，一般只需要從以下幾個(gè)方面簡單考慮即可，每次發(fā)版的時(shí)候都去翻這個(gè)規(guī)范顯然也不現(xiàn)實(shí)：

理想情況下，我們應(yīng)該只進(jìn)行向后兼容的更新。

我們要為項(xiàng)目添加新功能、新特性，我們必須要考慮到項(xiàng)目的兼容性。例如接口中新加了一個(gè)參數(shù)，那么為了老版本的客戶端能夠順利訪問這個(gè)接口，服務(wù)端應(yīng)該考慮為老版本客戶端缺少的請求參數(shù)提供一個(gè)默認(rèn)值。我們也可能為響應(yīng)添加新的屬性，或者提供了一些新的接口，當(dāng)然這些一般都不影響老客戶端。

必須進(jìn)行不兼容的升級(jí)。

有時(shí)候我們必須進(jìn)行一些不兼容的升級(jí)，對 API 做一些主要的修改，考慮到微服務(wù)之間的松耦合性，我們沒法強(qiáng)迫客戶端進(jìn)行立馬升級(jí)，此時(shí)可能會(huì)考慮在某一個(gè)時(shí)間段內(nèi)，兩個(gè)版本的 API 共存。

多個(gè) API 共存的時(shí)候，一個(gè)比較簡單的辦法是在 API 設(shè)計(jì)的時(shí)候，加上版本號(hào)，例如 /v1/xxx 或者 /v2/xxx，不過這種寫法有一個(gè)小小的缺陷，就是路徑中加了版本號(hào)之后，這個(gè)路徑看起來就不是一個(gè)完美的 REST 路徑了。

所以這塊還有一個(gè)方案，就是把請求的 API 的版本號(hào)寫到請求頭中。

具體的實(shí)現(xiàn)思路是這樣：

首先，在微服務(wù)中，我們所有的請求一般來說都會(huì)經(jīng)過網(wǎng)關(guān)，我們可以在網(wǎng)關(guān)中提取出請求頭的 Accept 參數(shù)，然后根據(jù) Accept 中的請求版本號(hào)，做不同的請求轉(zhuǎn)發(fā)，如果版本號(hào)是 1.0，就轉(zhuǎn)發(fā)到 1.0 的服務(wù)上去；如果版本號(hào)是 2.0，則轉(zhuǎn)發(fā)到 2.0 的服務(wù)上去。基本上就是這個(gè)樣子。

以現(xiàn)在微服務(wù)中主流的網(wǎng)關(guān) Spring Cloud Gateway 為例，我們可以做如下配置：

spring:
  application:
    name: gateway
  cloud:
    nacos:
      discovery:
        password: nacos
        username: nacos
        server-addr: a.b.c.d:8848
        namespace: public
    gateway:
      discovery:
        locator:
#          enabled: true
          lower-case-service-id: true
      routes:
        - id: v1_provider
          uri: lb://provider
          predicates:
            - Path=/p/**
            - Header=Accept,.*;?version=1\.0(|;.*)
          filters:
            - StripPrefix=1
server:
  port: 8082

大家看一下這個(gè)配置：

首先記得關(guān)閉服務(wù)自動(dòng)發(fā)現(xiàn)，否則通過默認(rèn)的服務(wù)名進(jìn)行代理就不會(huì)經(jīng)過我們配置的過濾器了。

然后我們手動(dòng)配置服務(wù)轉(zhuǎn)發(fā)，上面的配置基本上都是常規(guī)配置，跟版本號(hào)相關(guān)的配置是 Header=Accept,.*;?version=1\.0(|;.*)，這個(gè)配置就是對請求頭提出要求，首先前面的 Accept 表示這里是要判斷請求頭中的 Accept 字段，然后后面緊跟著的是 value（兩者之間用 , 隔開），這個(gè) value 是一個(gè)正則表達(dá)式 .*;?version=1\.0(|;.*)，意思就是在 version=1.0 之前和之后可以有任意字符串，只要 value 中包含 version=1.0 就算匹配上了。只有匹配上了，才會(huì)進(jìn)行請求轉(zhuǎn)發(fā)，否則不會(huì)進(jìn)行請求轉(zhuǎn)發(fā)。

最后，我們在發(fā)送請求的時(shí)候，設(shè)置如下請求頭即可：

如果版本號(hào)是 ?versinotallow=2.0?，則會(huì)報(bào)一個(gè) 404 錯(cuò)誤：

好啦，一個(gè)小小的版本號(hào)話題，感興趣的小伙伴可以試試最后這段代碼哦～