社区精选｜微服务的版本号要怎么设计？

今天小编为大家带来的是社区作者 江南一点雨 的文章，让我们一起来学习设计微服务的版本号。

---

今天我们来聊一下微服务项目中的版本号要怎么设计。

小伙伴们平时看到的项目版本号，基本上都是分为了三部分 X.Y.Z，版本升级的时候版本号都会变，那么版本号怎么变，这可不是拍脑门决定的，今天我们就一起来探讨一下这个话题。

1. 语义化版本控制规范

版本号该如何控制？其实是有一个标准规范的，规范地址：

• https://semver.org/lang/zh-CN/

这个规范非常友好的提供了中文版的内容。

语义化的版本控制规范要求版本号由三部分构成：

• MAJOR（X）：这个是主版本号，一般是涉及到不兼容的 API 更改时，这个会变化。
• MINOR（Y）：这个是次版本号，当我们对 API 进行向后兼容的增强时，这个版本号会变化，换句话说，也就是有新增的功能时，这里会变化。
• PATCH（Z）：这个是修订号，当我们进行一些 BUG 的修复，然后要发版的时候，这里会发生变化。

语义化的版本控制规范主要做了如下一些要求：

1. 使用语义化版本控制的软件必须（MUST）定义公共 API。该 API 可以在代码中被定义或出现于严谨的文档内。无论何种形式都应该力求精确且完整。
2. 标准的版本号必须（MUST）采用 X.Y.Z 的格式，其中 X、Y 和 Z 为非负的整数，且禁止（MUST NOT）在数字前方补零。X 是主版本号、Y 是次版本号、而 Z 为修订号。每个元素必须（MUST）以数值来递增。例如：1.9.1 -> 1.10.0 -> 1.11.0。
3. 标记版本号的软件发行后，禁止（MUST NOT）改变该版本软件的内容。任何修改都必须（MUST）以新版本发行。有的小伙伴可能会说我们的项目处于快速开发阶段，API 不稳定，天天变，要是按照这个要求来得发多少个版本才够用呀！其实，一般 API 快速变化主要有两种情况，一种是项目刚立项的时候，此时主版本号为 0，那么这个时候的 API 就不能算是稳定的 API；另外一种情况则是下个主版本处于快速开发中，但是这种情况一般会有一个新的分支用来管理下个版本的代码，所以和这里的要求实际上并不冲突（具体参见第 4、5 条）。
4. 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API 不应该被视为稳定版。
5. 1.0.0 的版本号用于界定公共 API 的形成。这一版本之后所有的版本号更新都基于公共 API 及其修改内容。那么有的小伙伴可能会纠结什么时候版本号从 0.Y.Z 变为 1.Y.Z 呢？一般来说，当你的项目已经上了生产环境或者说有稳定的 API 提供给别人使用的时候，基本上就可以算是 1.Y.Z 了。
6. 修订号 Z（x.y.Z | x > 0）必须（MUST）在只做了向下兼容的修正时才递增。这里的修正指的是针对不正确结果而进行的内部修改。
7. 次版本号 Y（x.Y.z | x > 0）必须（MUST）在有向下兼容的新功能出现时递增。在任何公共 API 的功能被标记为弃用时也必须（MUST）递增。也可以（MAY）在内部程序有大量新功能或改进被加入时递增，其中可以（MAY）包括修订级别的改变。每当次版本号递增时，修订号必须（MUST）归零。
8. 主版本号 X（X.y.z | X > 0）必须（MUST）在有任何不兼容的修改被加入公共 API 时递增。其中可以（MAY）包括次版本号及修订级别的改变。每当主版本号递增时，次版本号和修订号必须（MUST）归零。
9. 先行版本号可以（MAY）被标注在修订版之后，先加上一个连接号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。数字型的标识符禁止（MUST NOT）在前方补零。先行版的优先级低于相关联的标准版本。被标上先行版本号则表示这个版本并非稳定而且可能无法满足预期的兼容性需求。范例：1.0.0-alpha、1.0.0-alpha.1、1.0.0-0.3.7、1.0.0-x.7.z.92。
10. 版本编译信息可以（MAY）被标注在修订版或先行版本号之后，先加上一个加号再加上一连串以句点分隔的标识符来修饰。标识符必须（MUST）由 ASCII 字母数字和连接号 [0-9A-Za-z-] 组成，且禁止（MUST NOT）留白。当判断版本的优先层级时，版本编译信息可（SHOULD）被忽略。因此当两个版本只有在版本编译信息有差别时，属于相同的优先层级。范例：1.0.0-alpha+001、1.0.0+20130313144700、1.0.0-beta+exp.sha.5114f85。
11. 版本的优先层级指的是不同版本在排序时如何比较。
1. 只有数字的标识符以数值高低比较。
2. 有字母或连接号时则逐字以 ASCII 的排序来比较。
3. 数字的标识符比非数字的标识符优先层级低。
4. 若开头的标识符都相同时，栏位比较多的先行版本号优先层级比较高。
   例如：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。
5. 判断优先层级时，必须（MUST）把版本依序拆分为主版本号、次版本号、修订号及先行版本号后进行比较（版本编译信息不在这份比较的列表中）。
6. 由左到右依序比较每个标识符，第一个差异值用来决定优先层级：主版本号、次版本号及修订号以数值比较。例如：1.0.0 < 2.0.0 < 2.1.0 < 2.1.1。
7. 当主版本号、次版本号及修订号都相同时，改以优先层级比较低的先行版本号决定。例如：1.0.0-alpha < 1.0.0。
有相同主版本号、次版本号及修订号的两个先行版本号，其优先层级必须（MUST）透过由左到右的每个被句点分隔的标识符来比较，直到找到一个差异值后决定：

2. 微服务中的版本号

那么在微服务中，我们的版本号该怎么设计呢？

首先，整体上的思路，就是按照上文所说的语义化版本控制规范来。

其次，上面虽然给出了很多条条框框，然而我们实际开发中，一般只需要从以下几个方面简单考虑即可，每次发版的时候都去翻这个规范显然也不现实：

1. 理想情况下，我们应该只进行向后兼容的更新。

我们要为项目添加新功能、新特性，我们必须要考虑到项目的兼容性。例如接口中新加了一个参数，那么为了老版本的客户端能够顺利访问这个接口，服务端应该考虑为老版本客户端缺少的请求参数提供一个默认值。我们也可能为响应添加新的属性，或者提供了一些新的接口，当然这些一般都不影响老客户端。

1. 必须进行不兼容的升级。

有时候我们必须进行一些不兼容的升级，对 API 做一些主要的修改，考虑到微服务之间的松耦合性，我们没法强迫客户端进行立马升级，此时可能会考虑在某一个时间段内，两个版本的 API 共存。

多个 API 共存的时候，一个比较简单的办法是在 API 设计的时候，加上版本号，例如 /v1/xxx 或者 /v2/xxx，不过这种写法有一个小小的缺陷，就是路径中加了版本号之后，这个路径看起来就不是一个完美的 REST 路径了。

所以这块还有一个方案，就是把请求的 API 的版本号写到请求头中。

具体的实现思路是这样：

首先，在微服务中，我们所有的请求一般来说都会经过网关，我们可以在网关中提取出请求头的 Accept 参数，然后根据 Accept 中的请求版本号，做不同的请求转发，如果版本号是 1.0，就转发到 1.0 的服务上去；如果版本号是 2.0，则转发到 2.0 的服务上去。基本上就是这个样子。

以现在微服务中主流的网关 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

大家看一下这个配置：

1. 首先记得关闭服务自动发现，否则通过默认的服务名进行代理就不会经过我们配置的过滤器了。
2. 然后我们手动配置服务转发，上面的配置基本上都是常规配置，跟版本号相关的配置是 Header=Accept,.*;?version=1\.0(|;.*)，这个配置就是对请求头提出要求，首先前面的 Accept 表示这里是要判断请求头中的 Accept 字段，然后后面紧跟着的是 value（两者之间用 , 隔开），这个 value 是一个正则表达式 .*;?version=1\.0(|;.*)，意思就是在 version=1.0 之前和之后可以有任意字符串，只要 value 中包含 version=1.0 就算匹配上了。只有匹配上了，才会进行请求转发，否则不会进行请求转发。
3. 最后，我们在发送请求的时候，设置如下请求头即可：

如果版本号是 version=2.0，则会报一个 404 错误：

好啦，一个小小的版本号话题，感兴趣的小伙伴可以试试最后这段代码哦～

---

点击左下角阅读原文，到 SegmentFault 思否社区 和文章作者展开更多互动和交流，“公众号后台“回复“ 入群 ”即可加入我们的技术交流群，收获更多的技术文章~

- END -