泛型结构体 ​

核心概念 ​

泛型结构体是在结构体名后用尖括号 <T> 声明类型参数的结构体。类型参数可以用在字段类型中,让同一个结构体定义能存储不同类型的数据。标准库中的 Vec<T>、Option<T>、HashMap<K, V> 都是泛型结构体的典型应用。泛型结构体的类型参数在创建实例时确定具体类型,不同具体类型的实例是不同的类型——Point<i32> 和 Point<f64> 是两个不同的类型,不能互相赋值。

rust
// 泛型结构体:坐标点
#[derive(Debug)]
struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    // T = i32
    let int_point = Point { x: 5, y: 10 };
    // T = f64
    let float_point = Point { x: 1.5, y: 3.7 };
    // T = &str
    let str_point = Point { x: "left", y: "right" };

    println!("整数点: {:?}", int_point);
    println!("浮点点: {:?}", float_point);
    println!("字符串点: {:?}", str_point);

    // Point<i32> 和 Point<f64> 是不同类型
    // let mixed = Point { x: 5, y: 3.7 };  // 编译错误:x 是 i32,y 是 f64
}

多个类型参数 ​

当结构体需要存储不同类型的数据时,使用多个类型参数。

rust
// 两个类型参数:x 和 y 可以是不同类型
#[derive(Debug)]
struct Point2<X, Y> {
    x: X,
    y: Y,
}

// 键值对
#[derive(Debug)]
struct KeyValue<K, V> {
    key: K,
    value: V,
}

// 三个类型参数
#[derive(Debug)]
struct Triple<A, B, C> {
    first: A,
    second: B,
    third: C,
}

fn main() {
    // x 和 y 可以是不同类型
    let p = Point2 { x: 5, y: 3.14 };  // X = i32, Y = f64
    println!("{:?}", p);

    let mixed = Point2 { x: "hello", y: 42 };  // X = &str, Y = i32
    println!("{:?}", mixed);

    // 键值对
    let kv = KeyValue { key: String::from("name"), value: 100 };
    println!("{:?}", kv);

    // 三元组
    let t = Triple {
        first: 1,
        second: "two",
        third: 3.0,
    };
    println!("{:?}", t);
}

为泛型结构体实现方法 ​

在 impl 块中,泛型参数需要在 impl 关键字后面重新声明。

rust
#[derive(Debug, Clone)]
struct Wrapper<T> {
    value: T,
}

// 为所有 T 实现的方法
impl<T> Wrapper<T> {
    // 构造函数
    fn new(value: T) -> Self {
        Wrapper { value }
    }

    // 获取引用
    fn get(&self) -> &T {
        &self.value
    }

    // 获取可变引用
    fn get_mut(&mut self) -> &mut T {
        &mut self.value
    }

    // 消耗 Wrapper,返回内部值
    fn into_inner(self) -> T {
        self.value
    }

    // 转换内部类型
    fn map<U, F: FnOnce(T) -> U>(self, f: F) -> Wrapper<U> {
        Wrapper { value: f(self.value) }
    }
}

// 只为特定类型实现的方法
impl Wrapper<String> {
    fn is_empty(&self) -> bool {
        self.value.is_empty()
    }

    fn len(&self) -> usize {
        self.value.len()
    }
}

// 为实现了 Display 的 T 实现的方法
impl<T: std::fmt::Display> Wrapper<T> {
    fn print(&self) {
        println!("Wrapper({})", self.value);
    }
}

fn main() {
    // 通用方法
    let w = Wrapper::new(42);
    println!("值: {}", w.get());
    w.print();

    // map 转换类型
    let w2 = Wrapper::new(10);
    let w3 = w2.map(|n| format!("数字是 {}", n));
    w3.print();

    // String 专有方法
    let ws = Wrapper::new(String::from("hello"));
    println!("长度: {}", ws.len());
    println!("为空: {}", ws.is_empty());

    // into_inner 消耗 Wrapper
    let inner = ws.into_inner();
    println!("取出: {}", inner);
}

带 trait bound 的泛型结构体 ​

rust
use std::fmt::Display;

// 约束 T 必须实现 Display + PartialOrd
#[derive(Debug)]
struct MinMax<T: PartialOrd + Display + Clone> {
    min: T,
    max: T,
}

impl<T: PartialOrd + Display + Clone> MinMax<T> {
    fn new(a: T, b: T) -> Self {
        if a <= b {
            MinMax { min: a, max: b }
        } else {
            MinMax { min: b, max: a }
        }
    }

    fn update(&mut self, value: T) {
        if value < self.min {
            self.min = value;
        } else if value > self.max {
            self.max = value;
        }
    }

    fn range(&self) -> String {
        format!("[{}, {}]", self.min, self.max)
    }

    fn contains(&self, value: &T) -> bool {
        value >= &self.min && value <= &self.max
    }
}

fn main() {
    let mut mm = MinMax::new(10, 5);
    println!("初始范围: {}", mm.range());

    mm.update(3);
    mm.update(15);
    mm.update(8);
    println!("更新后: {}", mm.range());
    println!("包含 7: {}", mm.contains(&7));
    println!("包含 20: {}", mm.contains(&20));

    // 也可以用浮点数
    let mut fmm = MinMax::new(3.14, 2.72);
    fmm.update(1.0);
    fmm.update(9.8);
    println!("浮点范围: {}", fmm.range());
}

泛型结构体与默认类型参数 ​

rust
use std::collections::HashMap;

// 默认类型参数:S 默认为 String
#[derive(Debug)]
struct Config<S = String> {
    entries: HashMap<String, S>,
}

impl<S> Config<S> {
    fn new() -> Self {
        Config {
            entries: HashMap::new(),
        }
    }

    fn set(&mut self, key: &str, value: S) {
        self.entries.insert(key.to_string(), value);
    }

    fn get(&self, key: &str) -> Option<&S> {
        self.entries.get(key)
    }
}

impl Config<String> {
    fn set_str(&mut self, key: &str, value: &str) {
        self.entries.insert(key.to_string(), value.to_string());
    }
}

fn main() {
    // 使用默认类型 S = String
    let mut config = Config::new();
    config.set_str("host", "localhost");
    config.set_str("port", "8080");
    println!("host: {:?}", config.get("host"));

    // 指定其他类型 S = i32
    let mut int_config: Config<i32> = Config::new();
    int_config.set("width", 1920);
    int_config.set("height", 1080);
    println!("width: {:?}", int_config.get("width"));

    // 指定 S = Vec<String>
    let mut list_config: Config<Vec<String>> = Config::new();
    list_config.set("tags", vec![
        String::from("rust"),
        String::from("programming"),
    ]);
    println!("tags: {:?}", list_config.get("tags"));
}

泛型元组结构体 ​

rust
// 泛型元组结构体
#[derive(Debug, Clone, PartialEq)]
struct Pair<T>(T, T);

impl<T> Pair<T> {
    fn new(a: T, b: T) -> Self {
        Pair(a, b)
    }

    fn first(&self) -> &T {
        &self.0
    }

    fn second(&self) -> &T {
        &self.1
    }

    fn into_tuple(self) -> (T, T) {
        (self.0, self.1)
    }
}

impl<T: PartialOrd> Pair<T> {
    fn max(&self) -> &T {
        if self.0 >= self.1 { &self.0 } else { &self.1 }
    }

    fn min(&self) -> &T {
        if self.0 <= self.1 { &self.0 } else { &self.1 }
    }
}

impl<T: std::ops::Add<Output = T> + Clone> Pair<T> {
    fn sum(&self) -> T {
        self.0.clone() + self.1.clone()
    }
}

// Newtype 模式也可以泛型化
#[derive(Debug)]
struct Id<T>(u64, std::marker::PhantomData<T>);

impl<T> Id<T> {
    fn new(id: u64) -> Self {
        Id(id, std::marker::PhantomData)
    }

    fn value(&self) -> u64 {
        self.0
    }
}

// 不同的 phantom type 标记不同的实体
struct User;
struct Order;

fn main() {
    let p = Pair::new(10, 20);
    println!("max: {}", p.max());
    println!("min: {}", p.min());
    println!("sum: {}", p.sum());

    let (a, b) = p.into_tuple();
    println!("解构: a={}, b={}", a, b);

    // PhantomData 标记的类型安全 ID
    let user_id: Id<User> = Id::new(1001);
    let order_id: Id<Order> = Id::new(5001);
    println!("用户ID: {}", user_id.value());
    println!("订单ID: {}", order_id.value());

    // 不同标记的 ID 不能混用
    // let wrong: Id<User> = order_id;  // 编译错误
}

基本示例 ​

用泛型结构体实现一个通用的结果缓存器:

rust
use std::collections::HashMap;
use std::fmt::Display;
use std::hash::Hash;

// 泛型缓存:按键缓存计算结果
#[derive(Debug)]
struct Cache<K, V> {
    store: HashMap<K, V>,
    hits: u32,
    misses: u32,
}

impl<K: Hash + Eq + Clone + Display, V: Clone + Display> Cache<K, V> {
    fn new() -> Self {
        Cache {
            store: HashMap::new(),
            hits: 0,
            misses: 0,
        }
    }

    // 获取或计算:如果缓存中有就直接返回,没有就调用闭包计算
    fn get_or_compute<F>(&mut self, key: &K, compute: F) -> V
    where
        F: FnOnce(&K) -> V,
    {
        if let Some(value) = self.store.get(key) {
            self.hits += 1;
            println!("  [缓存命中] {} → {}", key, value);
            return value.clone();
        }

        self.misses += 1;
        let value = compute(key);
        println!("  [缓存未命中] {} → {} (计算)", key, value);
        self.store.insert(key.clone(), value.clone());
        value
    }

    // 手动设置缓存
    fn set(&mut self, key: K, value: V) {
        self.store.insert(key, value);
    }

    // 清除缓存
    fn clear(&mut self) {
        self.store.clear();
    }

    // 缓存大小
    fn size(&self) -> usize {
        self.store.len()
    }

    // 命中率
    fn hit_rate(&self) -> f64 {
        let total = self.hits + self.misses;
        if total == 0 {
            0.0
        } else {
            self.hits as f64 / total as f64 * 100.0
        }
    }

    fn stats(&self) -> String {
        format!(
            "缓存大小: {}, 命中: {}, 未命中: {}, 命中率: {:.1}%",
            self.size(), self.hits, self.misses, self.hit_rate()
        )
    }
}

// 泛型栈
#[derive(Debug)]
struct Stack<T> {
    elements: Vec<T>,
}

impl<T> Stack<T> {
    fn new() -> Self {
        Stack { elements: Vec::new() }
    }

    fn push(&mut self, value: T) {
        self.elements.push(value);
    }

    fn pop(&mut self) -> Option<T> {
        self.elements.pop()
    }

    fn peek(&self) -> Option<&T> {
        self.elements.last()
    }

    fn is_empty(&self) -> bool {
        self.elements.is_empty()
    }

    fn size(&self) -> usize {
        self.elements.len()
    }
}

impl<T: Display> Stack<T> {
    fn print(&self) {
        print!("栈[");
        for (i, elem) in self.elements.iter().enumerate() {
            if i > 0 { print!(", "); }
            print!("{}", elem);
        }
        println!("] (顶部在右)");
    }
}

fn main() {
    // === 缓存示例 ===
    println!("=== 缓存示例 ===");
    let mut cache: Cache<String, u64> = Cache::new();

    // 模拟耗时计算
    let compute_factorial = |key: &String| -> u64 {
        let n: u64 = key.parse().unwrap_or(0);
        (1..=n).product()
    };

    // 第一次计算
    for n in &["5", "10", "5", "7", "10", "5"] {
        cache.get_or_compute(&n.to_string(), compute_factorial);
    }

    println!("\n{}", cache.stats());

    // === 栈示例 ===
    println!("\n=== 栈示例 ===");
    let mut stack: Stack<i32> = Stack::new();

    stack.push(10);
    stack.push(20);
    stack.push(30);
    stack.print();

    println!("弹出: {:?}", stack.pop());
    stack.print();

    println!("栈顶: {:?}", stack.peek());
    println!("大小: {}", stack.size());

    // 字符串栈
    let mut str_stack: Stack<String> = Stack::new();
    str_stack.push(String::from("hello"));
    str_stack.push(String::from("world"));
    str_stack.print();
}

常见问题 ​

问题一:泛型结构体的类型参数可以有默认值吗?

可以。语法是 struct Foo<T = DefaultType>。如果使用时不指定类型参数,就用默认类型。标准库中 HashMap<K, V, S = RandomState> 的第三个参数 S 就有默认值。

问题二:impl<T> Foo<T> 和 impl Foo<i32> 有什么区别?

impl<T> Foo<T> 为所有类型的 Foo 实现方法,impl Foo<i32> 只为 Foo<i32> 实现方法。后者可以为特定类型添加专属方法。

问题三:泛型字段一定要在结构体中使用吗?

是的。如果声明了类型参数但字段中没有使用它,需要通过 PhantomData<T> 来"使用"它,否则编译器会报错。PhantomData 是零大小类型,不占内存。

问题四:不同类型参数的泛型结构体实例之间能互相赋值吗?

不能。Point<i32> 和 Point<f64> 是完全不同的类型。如果需要转换,要手动实现转换方法或 From trait。

适用场景 ​

  • 容器类型:栈、队列、缓存等通用数据结构
  • 包装器:Wrapper、Newtype、智能指针
  • 配置对象:泛型配置、泛型构建器
  • 键值对:通用的键值存储

注意事项 ​

  • 类型参数在 impl 块中需要重新声明:impl<T> Foo<T>
  • 可以为特定类型单独实现方法:impl Foo<String>
  • 可以对 impl 中的 T 添加额外的 trait bound
  • 未使用的类型参数需要 PhantomData
  • 不同类型参数的实例是不同类型
  • derive 宏要求所有类型参数也实现对应 trait

总结 ​

泛型结构体通过类型参数让同一个定义存储不同类型的数据,是 Rust 中实现通用数据结构的核心工具。类型参数在 struct 名后声明,可以有多个,也可以有默认值。在 impl 块中为泛型结构体实现方法时,类型参数需要重新声明(impl<T>),也可以为特定类型单独实现方法(impl Foo<String>)。标准库的 Vec<T>、Option<T>、HashMap<K, V> 都是泛型结构体。不同具体类型的实例(如 Point<i32> 和 Point<f64>)是不同类型,编译器通过单态化为每种实际使用的类型生成专门的代码。