Rust添加枚举变体是否属于破坏性变更？如何提前告知用户？

问题背景 #

假设Rust库中有如下枚举定义：

#[derive(Debug)]
pub enum Color {
    Red,
    Green,
    Blue,
}

若为该枚举添加第四个变体Color::Yellow，是否属于破坏性变更？如果是，有没有办法向API用户表明该类型未来可能会被扩展？

解答 #

1. 添加新变体属于破坏性变更 #

是的，这绝对是破坏性变更。Rust要求match枚举必须穷尽所有变体，用户代码中如果存在仅覆盖Red/Green/Blue的match语句，在你新增Yellow变体后，这些代码会直接编译失败——因为编译器会检测到未处理的枚举变体，抛出编译错误。这种会导致现有用户代码无法正常编译的修改，完全符合语义化版本中“破坏性变更”的定义。

2. 向用户表明类型可扩展的方法 #

有两种主要方式可以提前告知用户该枚举未来可能扩展，避免后续变更引发兼容问题：

• 文档明确说明
  在枚举的文档注释中直接声明未来可能新增变体，提醒用户编写match时预留扩展空间。示例：

  /// 表示基础颜色类型，未来版本可能会新增更多颜色变体
  /// 建议编写match语句时使用通配分支（_）处理未明确列出的变体
  #[derive(Debug)]
  pub enum Color {
      Red,
      Green,
      Blue,
  }
  

• 使用#[non_exhaustive]属性（官方推荐）
  Rust 1.40及以上版本支持#[non_exhaustive]属性，给枚举添加该属性后，外部代码无法编写穷尽式的match语句（编译时会报错），强制用户必须添加通配分支处理潜在的新增变体。这样后续你添加Yellow或其他变体时，用户的代码不会因为未覆盖新变体而编译失败。示例：

  #[derive(Debug)]
  #[non_exhaustive]
  pub enum Color {
      Red,
      Green,
      Blue,
  }
  

  这个属性的核心作用是向编译器和开发者传递一个明确信号：该枚举的成员集合不是固定的，未来会有扩展的可能，请勿依赖当前的变体列表做穷尽处理。

内容的提问来源于stack exchange，提问作者blerontin