Union 访问 ​

核心概念 ​

访问 union 的字段分为两种操作:写入和读取。写入 union 字段是安全的——你只是在向那块共享内存中存入一个值。读取 union 字段则需要 unsafe,因为编译器不追踪 union 当前存储的是哪个字段,读取错误的字段会把内存中的位模式按错误的类型解释,可能产生无效值(如无效的 bool 值、无效的引用等),导致未定义行为。程序员必须自己确保读取的字段就是最后写入的那个字段,或者确保这种类型双关(type punning)对当前的字段类型组合是安全的。

rust
union Data {
    int_val: i32,
    float_val: f32,
    bytes: [u8; 4],
}

fn main() {
    // === 写入是安全的 ===
    let mut data = Data { int_val: 42 };

    // 切换到另一个字段(安全)
    data.float_val = 3.14;

    // === 读取需要 unsafe ===
    // SAFETY: 刚写入了 float_val
    unsafe {
        println!("float: {}", data.float_val);
    }

    // 读取其他字段是类型双关
    // SAFETY: i32 和 f32 大小相同,读取不会越界
    // 但得到的值是 f32 3.14 的 IEEE 754 位表示
    unsafe {
        println!("int(类型双关): 0x{:08X}", data.int_val);
        println!("bytes(类型双关): {:?}", data.bytes);
    }
}

字段写入 ​

rust
union Config {
    as_u32: u32,
    as_bits: ConfigBits,
}

#[derive(Clone, Copy)]
#[repr(C)]
struct ConfigBits {
    enabled: u8,
    mode: u8,
    priority: u8,
    flags: u8,
}

fn main() {
    // 写入不需要 unsafe
    let mut config = Config { as_u32: 0 };

    // 通过不同字段写入
    config.as_bits = ConfigBits {
        enabled: 1,
        mode: 2,
        priority: 3,
        flags: 0xFF,
    };

    // 每次写入都会覆盖整个 union 的内容
    // 最后写入的字段决定了 union 当前的"活跃字段"

    // SAFETY: 刚写入了 as_bits
    unsafe {
        println!("enabled: {}", config.as_bits.enabled);
        println!("mode: {}", config.as_bits.mode);

        // 通过 as_u32 查看整个 32 位值
        println!("整体值: 0x{:08X}", config.as_u32);
    }

    // 重新写入 u32
    config.as_u32 = 0x00030201;

    // SAFETY: 刚写入了 as_u32,通过 as_bits 查看各字节
    unsafe {
        println!("\n写入 u32 后:");
        println!("enabled: {}", config.as_bits.enabled);  // 低字节
        println!("mode: {}", config.as_bits.mode);
        println!("priority: {}", config.as_bits.priority);
    }
}

字段读取 ​

rust
union Number {
    signed: i32,
    unsigned: u32,
    float: f32,
    bytes: [u8; 4],
}

fn main() {
    // === 读取活跃字段 ===
    let num = Number { signed: -1 };
    // SAFETY: signed 是活跃字段
    unsafe {
        println!("signed: {}", num.signed);
    }

    // === 类型双关读取 ===
    // -1 的补码表示是 0xFFFFFFFF
    // SAFETY: i32 和 u32 大小相同
    unsafe {
        println!("unsigned(双关): {}", num.unsigned);  // 4294967295
        println!("bytes(双关): {:?}", num.bytes);      // [255, 255, 255, 255]
    }

    // === 检查浮点数的位模式 ===
    let num = Number { float: 1.0_f32 };
    // SAFETY: 类型双关,查看 IEEE 754 表示
    unsafe {
        println!("\nf32 1.0:");
        println!("  位模式: 0x{:08X}", num.unsigned);
        println!("  字节: {:?}", num.bytes);
        println!("  符号位: {}", (num.unsigned >> 31) & 1);
        println!("  指数: {}", ((num.unsigned >> 23) & 0xFF) as i32 - 127);
        println!("  尾数: 0x{:06X}", num.unsigned & 0x7FFFFF);
    }

    // === 安全的替代方案 ===
    // f32::to_bits() 和 f32::from_bits() 提供安全的类型双关
    let bits = 1.0_f32.to_bits();
    println!("\n安全替代: f32::to_bits() = 0x{:08X}", bits);
    let back = f32::from_bits(bits);
    println!("f32::from_bits() = {}", back);
}
操作需要 unsafe风险
写入活跃字段否无
写入其他字段(切换)否旧数据被覆盖
读取活跃字段是低(只要确认活跃字段正确)
类型双关读取是中(可能产生无效值)
读取含引用/bool 的字段是高(可能产生 UB)

模式匹配与 union ​

rust
union Packet {
    raw: u32,
    header: PacketHeader,
}

#[derive(Clone, Copy)]
#[repr(C)]
struct PacketHeader {
    packet_type: u8,
    length: u8,
    flags: u16,
}

fn process_packet(packet: &Packet) {
    // union 不能直接用 match
    // 需要先读取字段,然后对值进行 match

    // SAFETY: 调用者保证 packet 已正确初始化
    let header = unsafe { packet.header };

    match header.packet_type {
        0 => println!("  心跳包, 长度: {}", header.length),
        1 => println!("  数据包, 长度: {}, flags: 0x{:04X}", header.length, header.flags),
        2 => println!("  控制包, flags: 0x{:04X}", header.flags),
        _ => println!("  未知类型: {}", header.packet_type),
    }
}

fn main() {
    // 构造数据包
    let packets = [
        Packet { header: PacketHeader { packet_type: 0, length: 0, flags: 0 } },
        Packet { header: PacketHeader { packet_type: 1, length: 64, flags: 0x0001 } },
        Packet { header: PacketHeader { packet_type: 2, length: 0, flags: 0x00FF } },
        Packet { raw: 0xFF030200 },  // 通过原始值构造
    ];

    println!("=== 处理数据包 ===");
    for (i, packet) in packets.iter().enumerate() {
        print!("包{}: ", i);
        process_packet(packet);

        // 查看原始值
        // SAFETY: u32 类型双关总是安全的
        unsafe {
            println!("     原始值: 0x{:08X}", packet.raw);
        }
    }
}

带标签的安全封装 ​

rust
use std::mem::ManuallyDrop;
use std::fmt;

// 标签枚举
#[derive(Debug, Clone, Copy, PartialEq)]
enum JsonType {
    Null,
    Bool,
    Int,
    Float,
    Str,
}

// 数据联合
union JsonData {
    boolean: bool,
    integer: i64,
    float: f64,
    string: ManuallyDrop<String>,
}

// 安全封装
struct JsonValue {
    tag: JsonType,
    data: JsonData,
}

impl JsonValue {
    fn null() -> Self {
        JsonValue { tag: JsonType::Null, data: JsonData { integer: 0 } }
    }

    fn from_bool(v: bool) -> Self {
        JsonValue { tag: JsonType::Bool, data: JsonData { boolean: v } }
    }

    fn from_int(v: i64) -> Self {
        JsonValue { tag: JsonType::Int, data: JsonData { integer: v } }
    }

    fn from_float(v: f64) -> Self {
        JsonValue { tag: JsonType::Float, data: JsonData { float: v } }
    }

    fn from_string(v: String) -> Self {
        JsonValue {
            tag: JsonType::Str,
            data: JsonData { string: ManuallyDrop::new(v) },
        }
    }

    fn type_name(&self) -> &str {
        match self.tag {
            JsonType::Null => "null",
            JsonType::Bool => "bool",
            JsonType::Int => "int",
            JsonType::Float => "float",
            JsonType::Str => "string",
        }
    }

    fn is_null(&self) -> bool { self.tag == JsonType::Null }

    fn as_bool(&self) -> Option<bool> {
        match self.tag {
            JsonType::Bool => Some(unsafe { self.data.boolean }),
            _ => None,
        }
    }

    fn as_int(&self) -> Option<i64> {
        match self.tag {
            JsonType::Int => Some(unsafe { self.data.integer }),
            _ => None,
        }
    }

    fn as_float(&self) -> Option<f64> {
        match self.tag {
            JsonType::Float => Some(unsafe { self.data.float }),
            _ => None,
        }
    }

    fn as_str(&self) -> Option<&str> {
        match self.tag {
            JsonType::Str => Some(unsafe { &self.data.string }),
            _ => None,
        }
    }
}

impl Drop for JsonValue {
    fn drop(&mut self) {
        if self.tag == JsonType::Str {
            // SAFETY: tag 为 Str 时 string 字段有效
            unsafe { ManuallyDrop::drop(&mut self.data.string); }
        }
    }
}

impl Clone for JsonValue {
    fn clone(&self) -> Self {
        match self.tag {
            JsonType::Null => Self::null(),
            JsonType::Bool => Self::from_bool(self.as_bool().unwrap()),
            JsonType::Int => Self::from_int(self.as_int().unwrap()),
            JsonType::Float => Self::from_float(self.as_float().unwrap()),
            JsonType::Str => Self::from_string(self.as_str().unwrap().to_string()),
        }
    }
}

impl fmt::Display for JsonValue {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self.tag {
            JsonType::Null => write!(f, "null"),
            JsonType::Bool => write!(f, "{}", self.as_bool().unwrap()),
            JsonType::Int => write!(f, "{}", self.as_int().unwrap()),
            JsonType::Float => write!(f, "{}", self.as_float().unwrap()),
            JsonType::Str => write!(f, "\"{}\"", self.as_str().unwrap()),
        }
    }
}

fn main() {
    let values = vec![
        JsonValue::null(),
        JsonValue::from_bool(true),
        JsonValue::from_int(42),
        JsonValue::from_float(3.14),
        JsonValue::from_string("hello world".to_string()),
    ];

    println!("=== JSON 值 ===");
    for v in &values {
        println!("  {} ({})", v, v.type_name());
    }

    // 类型检查
    println!("\n=== 类型检查 ===");
    let v = &values[3];
    println!("is_null: {}", v.is_null());
    println!("as_int: {:?}", v.as_int());
    println!("as_float: {:?}", v.as_float());

    // 克隆
    let cloned = values[4].clone();
    println!("\n克隆: {}", cloned);

    // 内存效率
    println!("\n=== 内存 ===");
    println!("JsonData: {} 字节", std::mem::size_of::<JsonData>());
    println!("JsonValue: {} 字节", std::mem::size_of::<JsonValue>());
}

基本示例 ​

用 union 实现网络协议的字节序转换和字段解析:

rust
#[repr(C)]
union IpAddress {
    addr32: u32,
    octets: [u8; 4],
}

#[repr(C)]
#[derive(Clone, Copy)]
struct TcpHeader {
    src_port: u16,
    dst_port: u16,
    seq_num: u32,
    ack_num: u32,
    data_offset_flags: u16,
    window: u16,
    checksum: u16,
    urgent: u16,
}

#[repr(C)]
union HeaderView {
    tcp: TcpHeader,
    raw: [u8; 20],
}

impl IpAddress {
    fn new(a: u8, b: u8, c: u8, d: u8) -> Self {
        IpAddress { octets: [a, b, c, d] }
    }

    fn from_u32(addr: u32) -> Self {
        IpAddress { addr32: addr }
    }

    fn to_string(&self) -> String {
        // SAFETY: octets 始终可以安全读取(与 addr32 是同一块内存)
        let o = unsafe { self.octets };
        format!("{}.{}.{}.{}", o[0], o[1], o[2], o[3])
    }

    fn to_u32(&self) -> u32 {
        // SAFETY: 类型双关,u32 和 [u8; 4] 大小相同
        unsafe { self.addr32 }
    }

    fn is_loopback(&self) -> bool {
        // SAFETY: octets 可以安全读取
        unsafe { self.octets[0] == 127 }
    }

    fn is_private(&self) -> bool {
        // SAFETY: octets 可以安全读取
        let o = unsafe { self.octets };
        o[0] == 10
            || (o[0] == 172 && (16..=31).contains(&o[1]))
            || (o[0] == 192 && o[1] == 168)
    }
}

fn main() {
    println!("=== IP 地址解析 ===");
    let addrs = [
        IpAddress::new(192, 168, 1, 100),
        IpAddress::new(10, 0, 0, 1),
        IpAddress::new(127, 0, 0, 1),
        IpAddress::new(8, 8, 8, 8),
        IpAddress::from_u32(0xC0A80164),  // 192.168.1.100(大端序)
    ];

    for addr in &addrs {
        println!("  {} (0x{:08X}) 回环:{} 私有:{}",
            addr.to_string(),
            addr.to_u32(),
            addr.is_loopback(),
            addr.is_private());
    }

    // TCP 头部解析
    println!("\n=== TCP 头部 ===");
    let header = HeaderView {
        tcp: TcpHeader {
            src_port: 8080u16.to_be(),
            dst_port: 443u16.to_be(),
            seq_num: 12345u32.to_be(),
            ack_num: 0,
            data_offset_flags: 0x5000u16.to_be(),  // 数据偏移=5(20字节)
            window: 65535u16.to_be(),
            checksum: 0,
            urgent: 0,
        },
    };

    // SAFETY: tcp 是活跃字段
    unsafe {
        println!("源端口: {}", u16::from_be(header.tcp.src_port));
        println!("目标端口: {}", u16::from_be(header.tcp.dst_port));
        println!("序列号: {}", u32::from_be(header.tcp.seq_num));
        println!("窗口: {}", u16::from_be(header.tcp.window));
    }

    // 查看原始字节
    // SAFETY: raw 和 tcp 共享内存
    unsafe {
        print!("原始字节: ");
        for byte in &header.raw {
            print!("{:02X} ", byte);
        }
        println!();
    }

    println!("\nHeaderView 大小: {} 字节", std::mem::size_of::<HeaderView>());
}

常见问题 ​

问题一:读取 union 的非活跃字段一定是 UB 吗?

不一定。如果两个字段的类型都是简单数值类型(如 i32 和 u32,或 i32 和 [u8; 4]),类型双关通常是安全的(所有位模式都是两种类型的有效值)。但如果涉及 bool(只有 0 和 1 有效)、引用(必须非空对齐)等类型,读取非活跃字段可能产生无效值,导致 UB。

问题二:union 的字段可以有不同大小吗?

可以。union 的大小等于最大字段的大小加上对齐填充。读取较小的字段只会读取共享内存的前几个字节。

问题三:如何安全地使用 union?

用一个外部标签(如枚举)追踪当前活跃的字段,封装在安全的 API 后面。这就是 Rust enum 的工作原理——编译器自动管理标签。

问题四:union 可以实现 trait 吗?

可以,但 impl 块中访问字段同样需要 unsafe。union 不能自动 derive 常见 trait(如 Debug、Clone),需要手动实现。

适用场景 ​

  • FFI:匹配 C 库中的 union 类型
  • 协议解析:网络协议头部的字节级解析
  • 类型双关:查看数值类型的位表示
  • 硬件寄存器:通过不同视图访问寄存器位字段

注意事项 ​

  • 写入 union 字段不需要 unsafe,读取需要
  • 读取非活跃字段是类型双关,需确保不产生无效值
  • 涉及 bool、引用、枚举等类型的双关可能是 UB
  • 用标签封装 union 以提供安全的 API
  • union 不自动调用 Drop
  • 优先使用 Rust enum 代替手动 tagged union

总结 ​

Union 的字段访问分为写入(安全)和读取(unsafe)。写入时只是向共享内存存入值,编译器知道这是合法的。读取时编译器无法确定当前活跃字段,需要程序员在 unsafe 块中保证读取正确的字段。读取非活跃字段构成类型双关——对简单数值类型通常安全,但对 bool、引用等类型可能产生无效值导致 UB。实际项目中应用外部标签追踪活跃字段,将 union 封装在安全的 API 后面。Rust 的 enum 就是编译器管理的安全 tagged union,日常编程应优先使用 enum。