📚 课程目录第4章版本号生成策略

4、版本号生成策略：时间戳版本号、递增整数版本号、UUID版本号、语义化版本号（SemVer）

版本号这东西，说白了就是给每次状态变化贴个标签。没有它，你根本不知道哪个版本是哪个。我在项目里见过最惨的案例——团队用「最终版」「最终版2」「打死不改版」来命名，结果上线时全乱套了。

今天咱们就把四种主流策略掰开揉碎。每种都有适用场景，也有坑。

4.1 时间戳版本号

最简单粗暴的方式。直接用当前时间生成版本号，比如 20250321143025（精确到秒）。

优点：

天然有序，新版本一定比旧版本大
一眼看出发布时间
无需中心化计数器，分布式友好

缺点：

可读性差，一串数字看不出功能变化
同一秒内可能产生冲突（概率低但存在）
无法表达版本间的关系（如大版本升级）

我的习惯：时间戳适合做内部快照或自动备份的版本号。我曾在日志系统中用它标记每次配置快照，回滚时直接按时间点找，非常直观。

// 生成时间戳版本号（精确到毫秒）
function generateTimestampVersion(): string {
  const now = new Date();
  const pad = (n: number) => n.toString().padStart(2, '0');
  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}${now.getMilliseconds().toString().padStart(3, '0')}`;
}
// 输出示例：20250321143025123

4.2 递增整数版本号

从 1 开始，每次新版本加 1。简单、有序、无歧义。

优点：

有序，版本号大小直接反映新旧
实现简单，一个计数器搞定
人类友好，容易比较

缺点：

需要中心化存储（如数据库自增ID）
分布式环境下容易冲突
无法表达语义（是修复bug还是加功能？）

我曾经踩过的坑：在微服务架构里用 Redis INCR 生成递增版本号。结果某个服务实例网络抖动，连续调用两次 INCR，跳过了中间一个号。虽然不影响功能，但排查问题时发现版本号不连续，浪费了半天时间。后来我改成了「递增整数 + 服务标识」的组合。

// 递增整数版本号（基于 Redis）
async function getNextVersion(redisClient: Redis): Promise<number> {
  return await redisClient.incr('state:version:counter');
}
// 输出示例：1, 2, 3, 4, ...

4.3 UUID 版本号

用 UUID（通用唯一标识符）作为版本号。比如 550e8400-e29b-41d4-a716-446655440000。

优点：

全球唯一，分布式环境零冲突
无需中心化协调
生成速度快

缺点：

无序，无法比较新旧
可读性极差
存储空间大（36字符）

适用场景：UUID 版本号最适合做「不可变快照」的标识。比如你每次保存状态时生成一个 UUID，用户通过这个 ID 精确引用某个历史版本。你不需要知道它是不是最新的，只需要知道它是唯一的。

// UUID 版本号（v4）
import { v4 as uuidv4 } from 'uuid';
function generateUuidVersion(): string {
  return uuidv4();
}
// 输出示例：550e8400-e29b-41d4-a716-446655440000

4.4 语义化版本号（SemVer）

这才是工业级标准。格式：主版本号.次版本号.修订号，比如 2.1.3。

规则：

主版本号：不兼容的 API 修改
次版本号：向下兼容的功能新增
修订号：向下兼容的问题修正

你想想看，这个规则为什么能火？因为它把「版本号」从单纯的标识变成了「沟通工具」。看到 3.0.0 你就知道要改代码了；看到 2.5.0 你知道有新功能但不用慌；看到 2.5.1 只是修了个 bug。

我个人的建议：如果你的状态元数据要对外暴露（比如 API 版本、配置格式版本），一定要用 SemVer。我在做开放平台时，所有状态 schema 都带 SemVer，客户端根据版本号决定解析逻辑，省去了无数兼容性问题。

// 语义化版本号解析与比较
interface SemVer {
  major: number;
  minor: number;
  patch: number;
}

function parseSemVer(version: string): SemVer {
  const parts = version.split('.').map(Number);
  return { major: parts[0], minor: parts[1], patch: parts[2] };
}

function compareSemVer(a: SemVer, b: SemVer): number {
  if (a.major !== b.major) return a.major - b.major;
  if (a.minor !== b.minor) return a.minor - b.minor;
  return a.patch - b.patch;
}
// 示例：compareSemVer({major:2, minor:1, patch:3}, {major:2, minor:2, patch:0}) → -1

4.5 四种策略对比

策略	有序性	唯一性	可读性	分布式友好	语义表达
时间戳	高	中	低	高	无
递增整数	高	高	中	低	无
UUID	无	极高	极低	极高	无
SemVer	中	中	高	中	强

4.6 实战中的组合策略

说实话，实际项目很少只用一种。我常用的组合是：

内部存储：递增整数 + 时间戳后缀（如 1024_202503211430）
对外 API：SemVer（如 2.1.3）
分布式快照：UUID（如 550e8400-...-446655440000）

核心原则：版本号不是越复杂越好。关键是你的团队和系统能理解它、解析它、依赖它。选一个策略，写进规范，然后严格执行。

下面这张图帮你快速决策：