首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >版本号解析三步走:主次修订、预发布段与构建号|数据鱼API

版本号解析三步走:主次修订、预发布段与构建号|数据鱼API

原创
作者头像
用户12862874
发布于 2026-11-19 20:52:28
发布于 2026-11-19 20:52:28
130
举报

同事把一串版本号贴进发布单:1.2.3-beta.1+build.5。运维问主版本是几,测试问这算不算正式版,产品问构建号要不要写进对外公告。三个人盯同一串字符,给出了三个答案。后来我们把解析、比较、差异判断拆成三步,争议就少了。

版本号本身不复杂,复杂的是每个人默认的读法不同。有人把整串当字符串,有人只看小数点前的数字,有人把 + 后面的内容也当成版本的一部分。

下面拿数据鱼API的「版本号解析与范围匹配」服务当例子。本文只用它的 parse、compare、diff 三个端点,把一串版本号拆成可判断的字段。

步骤一:把字符串拆成五段

parse 只收一个必填参数 version,要求是完整的 SemVer 2.0.0 版本号。文档给的返回结构不复杂,关键是别把每一段当成普通字符串。

字段

样例

含义

valid

true

是否符合 SemVer 2.0.0

version

1.2.3-beta.1

去掉构建号后的规范版本

major / minor / patch

"1" / "2" / "3"

主、次、修订号,以字符串返回

prerelease

["beta","1"]

预发布标识符数组

build

["build","5"]

构建号标识符数组,不参与比较

这里有几个容易踩的边界。v1.2.3 不接受,1、1.2 这种部分版本只能用于范围,不能拿来 parse;数字分量按字符串返回,是为了避免超过 64 位时被浮点数截断。前导零也非法,01.2.3 会直接返回 4002。

解析失败时,返回的 data 里会带回原始 version,把这条错误原样记进发布单,比只写“版本号非法”更容易定位。

代码语言:javascript
复制
GET /api/semver/parse?version=1.2.3-beta.1+build.5

数据鱼API的 parse 返回里,prerelease 和 build 是两个独立数组,别合并处理:前者影响优先级,后者不影响。

步骤二:比较优先级,别按字符串排队

compare 收 a 和 b 两个必填版本,返回 result(-1、0、1)、relation(lt、eq、gt)和 diff。diff 是差异级别:none、major、minor、patch、prerelease。

真正容易错的是预发布段的排序。1.0.0-alpha 低于 1.0.0-alpha.1,后者低于 1.0.0-beta;数字标识符按数值比,所以 beta.11 高于 beta.2,按字符串排反而会颠倒。构建号完全不参与比较,1.0.0+a 与 1.0.0+b 相等。

这个接口的 compare 把这三件事一次返回,省得你在业务代码里手写一套排序规则;手写最容易漏的就是“数字标识符按数值比”这一条。

还有一个常被忽略的点:compare 的 diff 只在两个版本都有完整核心号时才好用。拿 1.2.3-beta.1 和 1.2.3 比,diff 是 prerelease;拿 1.2.3 和 1.2.4 比,diff 是 patch。这些值直接对应发布说明的分类,不用再人工判断。

步骤三:判断差异级别,决定要不要动大版本

diff 收 from 和 to,返回 result、compare 和 direction。result 的取值和 compare 里的 diff 一致,direction 只有 up、same、down 三个方向。

把它放进发布流程,规则可以很简单:major 要过兼容性评审,minor 要更新变更说明,patch 走常规回归,prerelease 只用于候选版本内部流转,none 说明两个版本在优先级上相同、不需要发版。数据鱼API的 diff 会忽略构建号,1.2.3+a 到 1.2.3+b 的差异是 none,避免把构建号的变动误判成一次发布。

如果 from 和 to 相等,compare 是 0,direction 是 same;如果 from 大于 to,direction 是 down,常见于回滚场景。回滚记录里把这两个字段带上,比只写一句“降级”清楚得多。

三步之外,先统一输入

三步跑通之后,剩下的工作不是再加端点,而是把输入统一。发布单里只允许完整 SemVer,范围表达式放到另一个字段;构建号写进内部记录,不写进对外公告;每次判断把原始字符串、解析结果、比较方向一起存档。这样下次有人问“这算正式版吗”,答案不在某个人脑子里,而在同一条记录里。

数据鱼这套端点的数字分量按字符串返回,版本号再长也不会被精度问题改写;对内部构建号很长的项目,这个细节比多一个功能更实在。

以上版本号结构、比较规则与差异字段,整理自数据鱼API「版本号解析与范围匹配」接口的公开文档;文中版本号均为演示。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 步骤一:把字符串拆成五段
  • 步骤二:比较优先级,别按字符串排队
  • 步骤三:判断差异级别,决定要不要动大版本
  • 三步之外,先统一输入
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档