Lesson 25: C# 15 — Union 类型 Union Types

.NET 11 Preview · 等了十年的 discriminated union · 编译期穷举检查 · 告别"枚举+switch"

〇、一个无处不在的烦恼 The One-Of Problem

编程中最常见的数据建模难题之一：一个值恰好是几种类型之一。

C# 过去有五种"绕路"——每一种都有真实痛点：

核心矛盾：C# 缺少一个"这组类型到此为止——编译期帮我盯着"的语言构造。C# 15 回答了这个问题。

一、Union 语法 Union Declaration

1.1 基本声明

// 声明 case 类型——它们本身是普通 record/class/struct
public record class Cat(string Name);
public record class Dog(string Name);
public record class Bird(string Name);

// 🆕 union 声明——只有一行
public union Pet(Cat, Dog, Bird);

union 是一个类型声明，不是泛型约束、不是特性——是全新的一等公民类型。三行 record class + 一行 union，你有了一个编译期保证穷举的类型。

1.2 隐式转换——每个 case 自动能赋值给 union

Pet pet = new Dog("Rex");          // Dog → Pet 隐式转换
Pet pet2 = new Cat("Whiskers");    // Cat → Pet 隐式转换

Console.WriteLine(pet.Value);            // Dog { Name = Rex }

// 方法参数也是隐式的：
void Describe(Pet pet) { ... }

Describe(new Dog("Buddy"));           // 直接传 Dog——不需要包装
Describe(new Cat("Luna"));            // 直接传 Cat

1.3 case 类型可以是什么？

几乎任何能转为 object 的类型都可以：

// 引用类型
public union Shape(Circle, Rectangle, Triangle);

// 值类型——struct case 在默认形式下会装箱
public union IntOrString(int, string);

// 泛型——经典 Option<T>
public record class None;
public record class Some<T>(T Value);
public union Option<T>(None, Some<T>);

// 嵌套——union 本身也可以是另一个 union 的 case
public union Success<T>(T Value);
public union Failure(Exception Error);
public union Result<T>(Success<T>, Failure);

1.4 Union 可以有自己的成员

public record class Meters(double Value);
public record class Feet(double Value);

public union Length(Meters, Feet)
{
    // 基于模式匹配计算属性
    public double TotalMeters => this switch
    {
        Meters m => m.Value,
        Feet f => f.Value * 0.3048,
    };

    // 返回 union 类型的方法
    public Length Add(Length other) => new Meters(TotalMeters + other.TotalMeters);
}

二、模式匹配——编译器替你盯住每一种可能 Exhaustive Pattern Matching

2.1 穷举检查：不加 default 才是正确的

Pet pet = new Dog("Rex");

string name = pet switch
{
    Dog d => d.Name,
    Cat c => c.Name,
    Bird b => b.Name,
};  // ✅ 编译器通过了——三个 case 全部覆盖
    // 不需要 _ 兜底——编译器知道集合是封闭的

这才是关键——当你加了一个新 case 类型，每个 switch 都自动亮警告：

// 后来有人加了一个新宠物类型：
public record class Fish(string Name, double Depth);

// 改 union 声明：
public union Pet(Cat, Dog, Bird, Fish);   // ← 加了 Fish

// 💡 编译器立即在所有 switch 上亮警告：
// "The switch expression does not handle Fish"
// 你必须去每个 switch 加 Fish 的处理——这就是穷举安全的含义

2.2 "透明解包"——模式匹配直接作用在 Value 上

Union 的模式匹配有一个重要的设计决策：模式默认作用在 .Value 上，而不是 union 本身。这叫"透明解包"——你写 pattern match 时感觉就像在直接匹配 case 类型：

Pet pet = new Cat("Whiskers");

// 你写的代码——直接匹配 case 类型
var result = pet switch
{
    Cat c => "猫: " + c.Name,     // c 是 Cat 类型——不是 Pet
    Dog d => "狗: " + d.Name,
    Bird b => "鸟: " + b.Name,
};

// 等价于编译器隐式做的：
// pet.Value switch { Cat c => ..., Dog d => ..., Bird b => ... }

三个例外——以下模式作用在 union 值本身（不透明），不穿透到 .Value：

2.3 Null 处理

Union 是 struct——本身不能是 null。但 .Value 可以是 null（当 default(Pet) 时）。编译器跟踪 null 状态：

Pet pet = default;   // .Value 是 null
Console.WriteLine(pet.Value is null);  // True

var desc = pet switch
{
    Dog d => d.Name,
    Cat c => c.Name,
    Bird b => b.Name,
    null => "没有宠物",   // null 分支处理 default 情况
};

// Nullable union：Pet? 也可用
Pet? maybePet = null;   // Nullable<Pet>——整个 union 为 null

三、编译器生成了什么？ Compiler Lowering

3.1 一行 union 展开为一个 struct

这是理解 union 本质最重要的部分。你写：

public union Pet(Cat, Dog, Bird);

编译器把它降低为：

[System.Runtime.CompilerServices.Union]
public struct Pet : IUnion
{
    // 每个 case 一个构造
    public Pet(Cat value) => Value = value;
    public Pet(Dog value) => Value = value;
    public Pet(Bird value) => Value = value;

    // 存储——统一用 object?
    public object? Value { get; }

    // 每个 case 一个隐式转换
    public static implicit operator Pet(Cat value) => new(value);
    public static implicit operator Pet(Dog value) => new(value);
    public static implicit operator Pet(Bird value) => new(value);
}

3.2 运行时支持：UnionAttribute + IUnion

.NET 11 Preview 5 开始在 BCL 中内置两个运行时类型：

namespace System.Runtime.CompilerServices;

[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct, AllowMultiple = false)]
public sealed class UnionAttribute : Attribute;

public interface IUnion
{
    object? Value { get; }
}

IUnion 让你在运行时检查一个值是不是 union 类型：

if (value is IUnion { Value: null } u)
    Console.WriteLine("这是一个 Value 为 null 的 union");

3.3 默认形式的代价：值类型装箱

因为存储统一用 object?，struct case 在默认生成的 union 中会装箱：

public union IntOrString(int, string);

var u = new IntOrString(42);  // int 42 被装箱为 object——堆分配！

装箱到底发生了什么？

一次装箱——运行时做三件事：

// int x = 42;
// object o = x;   ← 装箱

// 步骤 1: 堆分配——CLR 在 GC 堆上找空闲空间（~20-30 字节）  ~10-20 CPU 周期
// 步骤 2: 内存拷贝——把值从栈拷到堆（int 就 4 字节）         ~数 CPU 周期
// 步骤 3: GC 记账——这个 boxed 对象从此进入 GC 引用链         隐性成本——累积才显现

单次装箱约是栈分配的 50-100 倍。但这不代表你的程序会慢 100 倍——关键在于调用频率。

什么时候你需要在乎？

真正的杀手不是单次分配，是 GC

100 万个 boxed int ≈ 约 20-24 MB 堆分配。在 ~100ms 内触发多次 Gen0、一次 Gen1；如果持续分配，Gen2 也跑不掉：

Gen2 暂停超过 10ms 是人眼可感知的"卡顿"——这才是装箱在热路径上的真正代价。

四、自定义 Union——当你需要不同行为 Custom Union Types

4.1 为什么需要手写？

编译器生成的 union 总是 struct + object? 存储。但你可能需要：

• 避免装箱——值类型 case 不分配堆内存
• 引用语义——class 而非 struct
• 适配已有类型——不能改原类型，但想让它参与穷举检查
• 自定义存储策略——tagged union 布局

4.2 手写 union 的最低要求

// 满足"基本 union 模式"的最低要求：
// ① [Union] attribute  ② 每个 case 一个单参数 public 构造  ③ 公开的 Value 属性

[System.Runtime.CompilerServices.Union]
public struct Shape : System.Runtime.CompilerServices.IUnion
{
    private readonly object? _value;

    public Shape(Circle value)  => _value = value;
    public Shape(Rectangle value) => _value = value;

    public object? Value => _value;
}

public record class Circle(double Radius);
public record class Rectangle(double Width, double Height);

// 使用——和编译器生成的 union 完全一样
Shape shape = new Shape(new Circle(5.0));
var area = shape switch
{
    Circle c => Math.PI * c.Radius * c.Radius,
    Rectangle r => r.Width * r.Height,
};

4.3 无装箱访问模式 Non-Boxing Access Pattern

这才是高性能 union 的精华——用 tagged union 布局，模式匹配不装箱：

[System.Runtime.CompilerServices.Union]
public struct IntOrBool : System.Runtime.CompilerServices.IUnion
{
    private readonly int _intValue;
    private readonly bool _boolValue;
    private readonly byte _tag;  // 0 = 无值, 1 = int, 2 = bool

    public IntOrBool(int? value)
    {
        if (value.HasValue) { _intValue = value.Value; _tag = 1; }
    }
    public IntOrBool(bool? value)
    {
        if (value.HasValue) { _boolValue = value.Value; _tag = 2; }
    }

    public object? Value => _tag switch
    {
        1 => _intValue,
        2 => _boolValue,
        _ => null
    };

    // HasValue —— 非装箱访问模式的关键
    public bool HasValue => _tag != 0;

    // 每个 case 一个 TryGetValue —— 编译器首选这个而非 Value
    public bool TryGetValue(out int value)
    {
        value = _intValue;
        return _tag == 1;
    }
    public bool TryGetValue(out bool value)
    {
        value = _boolValue;
        return _tag == 2;
    }
}

当 TryGetValue 存在时，编译器优先用它做模式匹配——值类型 case 不需要装箱，直接从 tag 判断类型，从对应字段读取值：

IntOrBool val = new IntOrBool((int?)42);

var desc = val switch
{
    int i => $"整数: {i}",      // 编译器用 TryGetValue(out int)——零装箱
    bool b => $"布尔: {b}",       // 编译器用 TryGetValue(out bool)——零装箱
};

4.4 class 版 union

// 如果需要引用语义（如作为 EF Core 的 owned entity）
[System.Runtime.CompilerServices.Union]
public class Result<T> : System.Runtime.CompilerServices.IUnion
{
    private readonly object? _value;

    public Result(T? value)         => _value = value;
    public Result(Exception? value) => _value = value;

    public object? Value => _value;
}

// 使用——模式匹配和 struct union 完全一样
Result<string> ok = new Result<string>("success");
Result<string> err = new Result<string>(new InvalidOperationException("failed"));

var msg = ok switch
{
    string s => $"OK: {s}",
    Exception e => $"Error: {e.Message}",
    null => "null",
};

五、Union vs 一切——选型指南 When to Use What

六、三个实战场景 Real-World Examples

6.1 Result 模式——告别 "out 参数 + bool 返回"

public record class Success<T>(T Value);
public record class Error(string Message, Exception? Inner = null);

public union Result<T>(Success<T>, Error)
{
    // 方便构造的静态工厂
    public static Result<T> Ok(T value) => new Success<T>(value);
    public static Result<T> Fail(string msg, Exception? ex = null) => new Error(msg, ex);

    // 便捷解构
    public TOut Match<TOut>(Func<T, TOut> onSuccess, Func<Error, TOut> onError)
        => this switch
        {
            Success<T> s => onSuccess(s.Value),
            Error e => onError(e),
        };
}

// ──── 调用方 ────
Result<int> Divide(int a, int b)
    => b == 0
        ? Result<int>.Fail("除数不能为零")
        : Result<int>.Ok(a / b);

// 使用——编译器强迫你处理两种结果
var msg = Divide(10, 2).Match(
    onSuccess: val => $"结果: {val}",
    onError: err => $"失败: {err.Message}"
);

6.2 消息/命令分发——新加消息自动提醒

public record class OrderPlaced(int OrderId, decimal Amount);
public record class PaymentReceived(int OrderId);
public record class OrderCancelled(int OrderId, string Reason);

public union OrderEvent(OrderPlaced, PaymentReceived, OrderCancelled);

// ──── 消息处理器 ────
void Handle(OrderEvent e)
{
    switch (e)
    {
        case OrderPlaced p:
            Console.WriteLine($"新订单 {p.OrderId}，金额 {p.Amount}");
            break;
        case PaymentReceived r:
            Console.WriteLine($"订单 {r.OrderId} 已付款");
            break;
        case OrderCancelled c:
            Console.WriteLine($"订单 {c.OrderId} 已取消: {c.Reason}");
            break;
    }
}

// 🆕 六个月后，有人加了新消息类型：
// public record class OrderRefunded(int OrderId, decimal Amount);
// 改 union: public union OrderEvent(OrderPlaced, PaymentReceived, OrderCancelled, OrderRefunded);
// → 💡 Handle() 立刻亮编译警告——"你没处理 OrderRefunded！"

6.3 Option<T>——值可能存在也可能不存在

public record class None;
public record class Some<T>(T Value);

public union Option<T>(None, Some<T>)
{
    public static Option<T> From(T? value)
        => value is null ? new None() : new Some<T>(value);
}

// 比 nullable 更强力——引用类型也能有 "没有值" 的状态
var found = FindUser("alice");
var greeting = found switch
{
    Some<User> s => $"你好，{s.Value.Name}",
    None => "用户不存在",
};

七、当前限制与未来 Current Limitations & Roadmap

C# 15 还在 Preview——以下功能在提案中但目前尚未实现：

八、测验 Quiz

九、总结 Summary

十、下一步 Next: Closed Hierarchies

Union 解决的是"一组不相关的类型，值必须是其中之一"。但如果你的类型天然有继承关系（基类 + 派生类），你想获得同样的穷举检查怎么办？C# 15 的 Closed Hierarchies（closed class）就是答案——下节课。

← L24: C# 14 小特性合集 · L26: Closed Hierarchies → · 🎯 回顾 Mission