Rust for C# Programmers: Complete Training Guide
Rust 面向 C# 程序员：完整训练指南

A comprehensive guide to learning Rust for developers with C# experience. This guide covers everything from basic syntax to advanced patterns, focusing on the conceptual shifts and practical differences between the two languages.
这是一本面向 C# 开发者的 Rust 完整训练指南，内容从基础语法一直覆盖到高级模式，重点讲清两门语言在思维方式和工程实践上的关键差异。

Course Overview
课程总览

• The case for Rust — Why Rust matters for C# developers: performance, safety, and correctness
  为什么要学 Rust：对 C# 开发者来说，Rust 的价值主要体现在性能、安全性和正确性。
• Getting started — Installation, tooling, and your first program
  快速开始：安装、工具链和第一个程序。
• Basic building blocks — Types, variables, control flow
  基础构件：类型、变量和控制流。
• Data structures — Arrays, tuples, structs, collections
  数据结构：数组、元组、结构体和集合。
• Pattern matching and enums — Algebraic data types and exhaustive matching
  模式匹配与枚举：代数数据类型与穷尽匹配。
• Ownership and borrowing — Rust’s memory management model
  所有权与借用：Rust 的内存管理模型。
• Modules and crates — Code organization and dependencies
  模块与 crate：代码组织方式与依赖管理。
• Error handling — Result-based error propagation
  错误处理：基于 Result 的错误传播方式。
• Traits and generics — Rust’s type system
  Trait 与泛型：Rust 类型系统的核心能力。
• Closures and iterators — Functional programming patterns
  闭包与迭代器：函数式编程常用模式。
• Concurrency — Fearless concurrency with type-system guarantees, async/await deep dive
  并发：在类型系统保证下的 fearless concurrency，以及 async/await 深入解析。
• Unsafe Rust and FFI — When and how to go beyond safe Rust
  Unsafe Rust 与 FFI：何时以及如何越过安全 Rust 的边界。
• Migration patterns — Real-world C# to Rust patterns and incremental adoption
  迁移模式：真实世界里的 C# → Rust 转换模式和渐进式引入方式。
• Best practices — Idiomatic Rust for C# developers
  最佳实践：适合 C# 开发者掌握的 Rust 惯用写法。

Self-Study Guide
自学指南

This material works both as an instructor-led course and for self-study. If you’re working through it on your own, here’s how to get the most out of it.
这套材料既适合讲师带读，也适合个人自学。如果是自己推进，下面这套节奏最容易把效果吃满。

Pacing recommendations:
学习节奏建议：

How to use the exercises:
练习怎么做：

• Chapters include hands-on exercises in collapsible <details> blocks with solutions
  每章都带有可折叠的 <details> 实战练习块，并附有参考答案。
• Always try the exercise before expanding the solution. Struggling with the borrow checker is part of learning — the compiler’s error messages are your teacher
  一定先自己做，再展开答案。 和借用检查器缠斗本来就是学习过程的一部分，编译器的报错就是老师。
• If you’re stuck for more than 15 minutes, expand the solution, study it, then close it and try again from scratch
  如果卡住超过 15 分钟，就先展开答案研究，再关掉答案从头重做一遍。
• The Rust Playground lets you run code without a local install
  Rust Playground 可以在没有本地环境的情况下直接运行代码。

Difficulty indicators:
难度标记：

• 🟢 Beginner — Direct translation from C# concepts
  🟢 初级：很多内容都能从 C# 经验直接迁移过来。
• 🟡 Intermediate — Requires understanding ownership or traits
  🟡 中级：需要真正理解所有权或 trait。
• 🔴 Advanced — Lifetimes, async internals, or unsafe code
  🔴 高级：涉及生命周期、async 内部机制或 unsafe 代码。

When you hit a wall:
当读到卡住时：

• Read the compiler error message carefully — Rust’s errors are exceptionally helpful
  仔细看编译器报错，Rust 的错误信息通常特别有帮助。
• Re-read the relevant section; concepts like ownership (ch7) often click on the second pass
  回头重读相关章节，像所有权这种概念，很多时候第二遍才会真正开窍。
• The Rust standard library docs are excellent — search for any type or method
  Rust 标准库文档 质量很高，类型和方法问题都值得直接去查。
• For deeper async patterns, see the companion Async Rust Training
  如果想继续深挖 async，可以配合阅读姊妹教材 Async Rust Training。

Table of Contents
目录总览

Part I — Foundations
第一部分：基础

1. Introduction and Motivation 🟢
1. 引言与动机 🟢

• The Case for Rust for C# Developers
  Rust 为什么值得 C# 开发者学习
• Common C# Pain Points That Rust Addresses
  Rust 解决哪些 C# 常见痛点
• When to Choose Rust Over C#
  什么时候该选 Rust，而不是 C#
• Language Philosophy Comparison
  语言哲学对比
• Quick Reference: Rust vs C#
  Rust 与 C# 快速对照

2. Getting Started 🟢
2. 快速开始 🟢

• Installation and Setup
  安装与环境配置
• Your First Rust Program
  第一个 Rust 程序
• Cargo vs NuGet/MSBuild
  Cargo 与 NuGet / MSBuild 对比
• Reading Input and CLI Arguments
  读取输入与命令行参数
• Essential Rust Keywords (optional reference — consult as needed)
  Rust 关键字速查表（可选参考）

3. Built-in Types and Variables 🟢
3. 内置类型与变量 🟢

• Variables and Mutability
  变量与可变性
• Primitive Types Comparison
  基本类型对照
• String Types: String vs &str
  字符串类型：String 与 &str
• Printing and String Formatting
  打印与字符串格式化
• Type Casting and Conversions
  类型转换
• True Immutability vs Record Illusions
  真正的不可变性与 record 幻觉

4. Control Flow 🟢
4. 控制流 🟢

• Functions vs Methods
  函数与方法
• Expression vs Statement (Important!)
  表达式与语句的差异
• Conditional Statements
  条件语句
• Loops and Iteration
  循环与迭代

5. Data Structures and Collections 🟢
5. 数据结构与集合 🟢

• Tuples and Destructuring
  元组与解构
• Arrays and Slices
  数组与切片
• Structs vs Classes
  Struct 与 Class
• Constructor Patterns
  构造器模式
• Vec<T> vs List<T>
Vec<T> 与 List<T>
• HashMap vs Dictionary
  HashMap 与 Dictionary

6. Enums and Pattern Matching 🟡
6. 枚举与模式匹配 🟡

• Algebraic Data Types vs C# Unions
  代数数据类型与 C# 联合类型
• Exhaustive Pattern Matching
  穷尽模式匹配
• Option<T> for Null Safety
  用 Option<T> 处理空安全
• Guards and Advanced Patterns
  guard 与进阶模式

7. Ownership and Borrowing 🟡
7. 所有权与借用 🟡

• Understanding Ownership
  理解所有权
• Move Semantics vs Reference Semantics
  移动语义与引用语义
• Borrowing and References
  借用与引用
• Memory Safety Deep Dive
  内存安全深入解析
• Lifetimes Deep Dive 🔴
  生命周期深入解析 🔴
• Smart Pointers, Drop, and Deref 🔴
  智能指针、Drop 与 Deref 🔴

8. Crates and Modules 🟢
8. crate 与模块 🟢

• Rust Modules vs C# Namespaces
  Rust 模块与 C# 命名空间
• Crates vs .NET Assemblies
  crate 与 .NET 程序集
• Package Management: Cargo vs NuGet
  包管理：Cargo 与 NuGet

9. Error Handling 🟡
9. 错误处理 🟡

• Exceptions vs Result<T, E>
  异常与 Result<T, E>
• The ? Operator
  ? 运算符
• Custom Error Types
  自定义错误类型
• Crate-Level Error Types and Result Aliases
  crate 级错误类型与 Result 别名
• Error Recovery Patterns
  错误恢复模式

10. Traits and Generics 🟡
10. Trait 与泛型 🟡

• Traits vs Interfaces
  Trait 与接口
• Inheritance vs Composition
  继承与组合
• Generic Constraints: where vs trait bounds
  泛型约束：where 与 trait bound
• Common Standard Library Traits
  标准库常见 Trait

11. From and Into Traits 🟡
11. From 与 Into Trait 🟡

• Type Conversions in Rust
  Rust 中的类型转换
• Implementing From for Custom Types
  为自定义类型实现 From

12. Closures and Iterators 🟡
12. 闭包与迭代器 🟡

• Rust Closures
  Rust 闭包
• LINQ vs Rust Iterators
  LINQ 与 Rust 迭代器
• Macros Primer
  宏入门

Part II — Concurrency & Systems
第二部分：并发与系统

13. Concurrency 🔴
13. 并发 🔴

• Thread Safety: Convention vs Type System Guarantees
  线程安全：约定式与类型系统保证式
• async/await: C# Task vs Rust Future
  async/await：C# Task 与 Rust Future
• Cancellation Patterns
  取消模式
• Pin and tokio::spawn
  Pin 与 tokio::spawn

14. Unsafe Rust, FFI, and Testing 🟡
14. Unsafe Rust、FFI 与测试 🟡

• When and Why to Use Unsafe
  何时以及为何使用 Unsafe
• Interop with C# via FFI
  通过 FFI 与 C# 互操作
• Testing in Rust vs C#
  Rust 与 C# 的测试方式对比
• Property Testing and Mocking
  性质测试与 Mocking

Part III — Migration & Best Practices
第三部分：迁移与最佳实践

15. Migration Patterns and Case Studies 🟡
15. 迁移模式与案例研究 🟡

• Common C# Patterns in Rust
  C# 常见模式在 Rust 中的改写
• Essential Crates for C# Developers
  C# 开发者必备 crate
• Incremental Adoption Strategy
  渐进式引入策略

16. Best Practices and Reference 🟡
16. 最佳实践与参考 🟡

• Idiomatic Rust for C# Developers
  适合 C# 开发者掌握的 Rust 惯用法
• Performance Comparison: Managed vs Native
  托管与原生性能对比
• Common Pitfalls and Solutions
  常见陷阱与解决方案
• Learning Path and Resources
  学习路径与资源
• Rust Tooling Ecosystem
  Rust 工具生态

Capstone
综合项目

17. Capstone Project 🟡
17. 综合项目 🟡

• Build a CLI Weather Tool — combines structs, traits, error handling, async, modules, serde, and testing into a working application
  构建一个命令行天气工具，把结构体、trait、错误处理、async、模块、serde 和测试串成一个可运行应用。

Introduction and Motivation §§ZH§§ 引言与动机

Speaker Intro and General Approach
讲者介绍与整体思路

• Speaker intro
  讲者背景 微软 SCHIE 团队的首席固件架构师，长期做安全、系统编程、固件、操作系统、虚拟机、CPU 与平台架构相关工作。
• Principal Firmware Architect in Microsoft SCHIE (Silicon and Cloud Hardware Infrastructure Engineering) team
  现任微软 SCHIE（Silicon and Cloud Hardware Infrastructure Engineering）团队首席固件架构师。
• Industry veteran with expertise in security, systems programming (firmware, operating systems, hypervisors), CPU and platform architecture, and C++ systems
  是系统、安全、平台架构和 C++ 系统开发方向的资深从业者。
• Started programming in Rust in 2017 (@AWS EC2), and have been in love with the language ever since
  从 2017 年在 AWS EC2 开始写 Rust，之后就一直很认这门语言。
• This course is intended to be as interactive as possible
  这套课程的目标是尽量做成高互动式讲解。
• Assumption: You know C# and .NET development
  默认前提：已经熟悉 C# 和 .NET 开发。
• Examples deliberately map C# concepts to Rust equivalents
  示例会有意识地把 C# 概念映射到 Rust 对应物上。
• Please feel free to ask clarifying questions at any point of time
  随时都可以追问细节，不需要等到讲完再问。

The Case for Rust for C# Developers
为什么 C# 开发者值得学 Rust

What you’ll learn: Why Rust matters for C# developers: the performance gap between managed and native code, how Rust eliminates null-reference exceptions and hidden control flow at compile time, and the main scenarios where Rust complements or replaces C#.
本章将学到什么： 理解 Rust 为什么值得 C# 开发者认真投入：托管代码与原生代码的性能差异从哪来，Rust 如何在编译期消灭空引用异常和隐藏控制流，以及它在什么场景下适合补充甚至替代 C#。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Performance Without the Runtime Tax
没有运行时税的性能

// C# - Great productivity, runtime overhead
public class DataProcessor
{
    private List<int> data = new List<int>();
    
    public void ProcessLargeDataset()
    {
        // Allocations trigger GC
        for (int i = 0; i < 10_000_000; i++)
        {
            data.Add(i * 2); // GC pressure
        }
        // Unpredictable GC pauses during processing
    }
}
// Runtime: Variable (50-200ms due to GC)
// Memory: ~80MB (including GC overhead)
// Predictability: Low (GC pauses)

#![allow(unused)]
fn main() {
// Rust - Same expressiveness, zero runtime overhead
struct DataProcessor {
    data: Vec<i32>,
}

impl DataProcessor {
    fn process_large_dataset(&mut self) {
        // Zero-cost abstractions
        for i in 0..10_000_000 {
            self.data.push(i * 2); // No GC pressure
        }
        // Deterministic performance
    }
}
// Runtime: Consistent (~30ms)
// Memory: ~40MB (exact allocation)
// Predictability: High (no GC)
}

Rust 吸引很多 C# 开发者的第一原因，往往不是语法，而是“性能和可预测性可以同时拿到”。
C# 的生产力确实高，但托管运行时、GC、JIT 这些机制会把性能曲线拉得更复杂；Rust 则是尽量把抽象成本压回编译期，把运行时包袱减到最低。

Memory Safety Without Runtime Checks
不靠运行时检查也能拿到内存安全

// C# - Runtime safety with overhead
public class RuntimeCheckedOperations
{
    public string? ProcessArray(int[] array)
    {
        // Runtime bounds checking on every access
        if (array.Length > 0)
        {
            return array[0].ToString(); // Safe — int is a value type, never null
        }
        return null; // Nullable return (string? with C# 8+ nullable reference types)
    }
    
    public void ProcessConcurrently()
    {
        var list = new List<int>();
        
        // Data races possible, requires careful locking
        Parallel.For(0, 1000, i =>
        {
            lock (list) // Runtime overhead
            {
                list.Add(i);
            }
        });
    }
}

#![allow(unused)]
fn main() {
// Rust - Compile-time safety with zero runtime cost
struct SafeOperations;

impl SafeOperations {
    // Compile-time null safety, no runtime checks
    fn process_array(array: &[i32]) -> Option<String> {
        array.first().map(|x| x.to_string())
        // No null references possible
        // Bounds checking optimized away when provably safe
    }
    
    fn process_concurrently() {
        use std::sync::{Arc, Mutex};
        use std::thread;
        
        let data = Arc::new(Mutex::new(Vec::new()));
        
        // Data races prevented at compile time
        let handles: Vec<_> = (0..1000).map(|i| {
            let data = Arc::clone(&data);
            thread::spawn(move || {
                data.lock().unwrap().push(i);
            })
        }).collect();
        
        for handle in handles {
            handle.join().unwrap();
        }
    }
}
}

Rust 真正厉害的地方，不只是安全，而是“把很多安全成本挪到了编译期”。
换句话说，它不是靠在运行时加一堆护栏来保护程序，而是尽量让错误写不出来，或者至少编不过去。

Common C# Pain Points That Rust Addresses
Rust 正面击中的那些 C# 常见痛点

1. The Billion Dollar Mistake: Null References
1. 十亿美元错误：空引用

// C# - Null reference exceptions are runtime bombs
public class UserService
{
    public string GetUserDisplayName(User user)
    {
        // Any of these could throw NullReferenceException
        return user.Profile.DisplayName.ToUpper();
        //     ^^^^^ ^^^^^^^ ^^^^^^^^^^^ ^^^^^^^
        //     Could be null at runtime
    }
    
    // Even with nullable reference types (C# 8+)
    public string GetDisplayName(User? user)
    {
        return user?.Profile?.DisplayName?.ToUpper() ?? "Unknown";
        // Still possible to have null at runtime
    }
}

#![allow(unused)]
fn main() {
// Rust - Null safety guaranteed at compile time
struct UserService;

impl UserService {
    fn get_user_display_name(user: &User) -> Option<String> {
        user.profile.as_ref()?
            .display_name.as_ref()
            .map(|name| name.to_uppercase())
        // Compiler forces you to handle None case
        // Impossible to have null pointer exceptions
    }
    
    fn get_display_name_safe(user: Option<&User>) -> String {
        user.and_then(|u| u.profile.as_ref())
            .and_then(|p| p.display_name.as_ref())
            .map(|name| name.to_uppercase())
            .unwrap_or_else(|| "Unknown".to_string())
        // Explicit handling, no surprises
    }
}
}

Rust is not just “null safety, but stricter”; the whole mental model is different.
在 Rust 里，可选值就是 Option<T>，不写出来就不允许默认存在；在 C# 里，哪怕有可空引用类型加成，很多空值问题本质上还是靠规则和警告在兜。

2. Hidden Exceptions and Control Flow
2. 隐藏的异常与控制流

// C# - Exceptions can be thrown from anywhere
public async Task<UserData> GetUserDataAsync(int userId)
{
    // Each of these might throw different exceptions
    var user = await userRepository.GetAsync(userId);        // SqlException
    var permissions = await permissionService.GetAsync(user); // HttpRequestException  
    var preferences = await preferenceService.GetAsync(user); // TimeoutException
    
    return new UserData(user, permissions, preferences);
    // Caller has no idea what exceptions to expect
}

#![allow(unused)]
fn main() {
// Rust - All errors explicit in function signatures
#[derive(Debug)]
enum UserDataError {
    DatabaseError(String),
    NetworkError(String),
    Timeout,
    UserNotFound(i32),
}

async fn get_user_data(user_id: i32) -> Result<UserData, UserDataError> {
    // All errors explicit and handled
    let user = user_repository.get(user_id).await
        .map_err(UserDataError::DatabaseError)?;
    
    let permissions = permission_service.get(&user).await
        .map_err(UserDataError::NetworkError)?;
    
    let preferences = preference_service.get(&user).await
        .map_err(|_| UserDataError::Timeout)?;
    
    Ok(UserData::new(user, permissions, preferences))
    // Caller knows exactly what errors are possible
}
}

这部分是很多人真正喜欢上 Rust 的地方。
函数签名里把错误类型写出来以后，控制流就没那么“暗箱操作”了。调用者会明确知道：这里会失败，而且会怎么失败。

3. Correctness: The Type System as a Proof Engine
3. 正确性：把类型系统当证明引擎

Rust’s type system can rule out entire categories of bugs at compile time that C# usually catches only through testing, review, or production incidents.
Rust 的类型系统能在编译期排除掉整类 bug，而这些问题在 C# 里很多时候只能靠测试、代码审查，甚至线上事故才能抓到。

ADTs vs Sealed-Class Workarounds
ADT 与 sealed class 式替代方案

// C# — Discriminated unions require sealed-class boilerplate.
// The compiler warns about missing cases (CS8524) ONLY when there's no _ catch-all.
// In practice, most C# code uses _ as a default, which silences the warning.
public abstract record Shape;
public sealed record Circle(double Radius)   : Shape;
public sealed record Rectangle(double W, double H) : Shape;
public sealed record Triangle(double A, double B, double C) : Shape;

public static double Area(Shape shape) => shape switch
{
    Circle c    => Math.PI * c.Radius * c.Radius,
    Rectangle r => r.W * r.H,
    // Forgot Triangle? The _ catch-all silences any compiler warning.
    _           => throw new ArgumentException("Unknown shape")
};
// Add a new variant six months later — the _ pattern hides the missing case.
// No compiler warning tells you about the 47 switch expressions you need to update.

#![allow(unused)]
fn main() {
// Rust — ADTs + exhaustive matching = compile-time proof
enum Shape {
    Circle { radius: f64 },
    Rectangle { w: f64, h: f64 },
    Triangle { a: f64, b: f64, c: f64 },
}

fn area(shape: &Shape) -> f64 {
    match shape {
        Shape::Circle { radius }    => std::f64::consts::PI * radius * radius,
        Shape::Rectangle { w, h }   => w * h,
        // Forget Triangle? ERROR: non-exhaustive pattern
        Shape::Triangle { a, b, c } => {
            let s = (a + b + c) / 2.0;
            (s * (s - a) * (s - b) * (s - c)).sqrt()
        }
    }
}
// Add a new variant → compiler shows you EVERY match that needs updating.
}

Immutability by Default vs Opt-In Immutability
默认不可变 与 选择性不可变

// C# — Everything is mutable by default
public class Config
{
    public string Host { get; set; }   // Mutable by default
    public int Port { get; set; }
}

// "readonly" and "record" help, but don't prevent deep mutation:
public record ServerConfig(string Host, int Port, List<string> AllowedOrigins);

var config = new ServerConfig("localhost", 8080, new List<string> { "*.example.com" });
// Records are "immutable" but reference-type fields are NOT:
config.AllowedOrigins.Add("*.evil.com"); // Compiles and mutates! ← bug
// The compiler gives you no warning.

#![allow(unused)]
fn main() {
// Rust — Immutable by default, mutation is explicit and visible
struct Config {
    host: String,
    port: u16,
    allowed_origins: Vec<String>,
}

let config = Config {
    host: "localhost".into(),
    port: 8080,
    allowed_origins: vec!["*.example.com".into()],
};

// config.allowed_origins.push("*.evil.com".into()); // ERROR: cannot borrow as mutable

// Mutation requires explicit opt-in:
let mut config = config;
config.allowed_origins.push("*.safe.com".into()); // OK — visibly mutable

// "mut" in the signature tells every reader: "this function modifies data"
fn add_origin(config: &mut Config, origin: String) {
    config.allowed_origins.push(origin);
}
}

Functional Programming: First-Class vs Afterthought
函数式风格：第一公民还是外挂能力

// C# — FP bolted on; LINQ is expressive but the language fights you
public IEnumerable<Order> GetHighValueOrders(IEnumerable<Order> orders)
{
    return orders
        .Where(o => o.Total > 1000)   // Func<Order, bool> — heap-allocated delegate
        .Select(o => new OrderSummary  // Anonymous type or extra class
        {
            Id = o.Id,
            Total = o.Total
        })
        .OrderByDescending(o => o.Total);
    // No exhaustive matching on results
    // Null can sneak in anywhere in the pipeline
    // Can't enforce purity — any lambda might have side effects
}

#![allow(unused)]
fn main() {
// Rust — FP is a first-class citizen
fn get_high_value_orders(orders: &[Order]) -> Vec<OrderSummary> {
    orders.iter()
        .filter(|o| o.total > 1000)      // Zero-cost closure, no heap allocation
        .map(|o| OrderSummary {           // Type-checked struct
            id: o.id,
            total: o.total,
        })
        .sorted_by(|a, b| b.total.cmp(&a.total)) // itertools
        .collect()
    // No nulls anywhere in the pipeline
    // Closures are monomorphized — zero overhead vs hand-written loops
    // Purity enforced: &[Order] means the function CAN'T modify orders
}
}

Inheritance: Elegant in Theory, Fragile in Practice
继承：理论上优雅，实践里脆弱

// C# — The fragile base class problem
public class Animal
{
    public virtual string Speak() => "...";
    public void Greet() => Console.WriteLine($"I say: {Speak()}");
}

public class Dog : Animal
{
    public override string Speak() => "Woof!";
}

public class RobotDog : Dog
{
    // Which Speak() does Greet() call? What if Dog changes?
    // Diamond problem with interfaces + default methods
    // Tight coupling: changing Animal can break RobotDog silently
}

// Common C# anti-patterns:
// - God base classes with 20 virtual methods
// - Deep hierarchies (5+ levels) nobody can reason about
// - "protected" fields creating hidden coupling
// - Base class changes silently altering derived behavior

#![allow(unused)]
fn main() {
// Rust — Composition over inheritance, enforced by the language
trait Speaker {
    fn speak(&self) -> &str;
}

trait Greeter: Speaker {
    fn greet(&self) {
        println!("I say: {}", self.speak());
    }
}

struct Dog;
impl Speaker for Dog {
    fn speak(&self) -> &str { "Woof!" }
}
impl Greeter for Dog {} // Uses default greet()

struct RobotDog {
    voice: String, // Composition: owns its own data
}
impl Speaker for RobotDog {
    fn speak(&self) -> &str { &self.voice }
}
impl Greeter for RobotDog {} // Clear, explicit behavior

// No fragile base class problem — no base classes at all
// No hidden coupling — traits are explicit contracts
// No diamond problem — trait coherence rules prevent ambiguity
// Adding a method to Speaker? Compiler tells you everywhere to implement it.
}

Key insight: In C#, correctness is a discipline. Teams rely on conventions, tests, and reviews to keep dangerous states in check. In Rust, correctness is much more often encoded directly into the type system, making whole bug families structurally impossible.
关键理解： 在 C# 里，正确性很多时候更像一种团队纪律，要靠约定、测试和审查来维持；在 Rust 里，正确性更容易被写进类型系统本身，于是整类 bug 会直接变成“结构上就写不出来”。

4. Unpredictable Performance Due to GC
4. GC 带来的不可预测性能

// C# - GC can pause at any time
public class HighFrequencyTrader
{
    private List<Trade> trades = new List<Trade>();
    
    public void ProcessMarketData(MarketTick tick)
    {
        // Allocations can trigger GC at worst possible moment
        var analysis = new MarketAnalysis(tick);
        trades.Add(new Trade(analysis.Signal, tick.Price));
        
        // GC might pause here during critical market moment
        // Pause duration: 1-100ms depending on heap size
    }
}

#![allow(unused)]
fn main() {
// Rust - Predictable, deterministic performance
struct HighFrequencyTrader {
    trades: Vec<Trade>,
}

impl HighFrequencyTrader {
    fn process_market_data(&mut self, tick: MarketTick) {
        // Zero allocations, predictable performance
        let analysis = MarketAnalysis::from(tick);
        self.trades.push(Trade::new(analysis.signal(), tick.price));
        
        // No GC pauses, consistent sub-microsecond latency
        // Performance guaranteed by type system
    }
}
}

这里真正关键的词不是“更快”，而是“更稳”。
很多系统并不是不能接受平均性能一般，而是不能接受偶发停顿、尾延迟飙高、关键时刻刚好被 GC 插一脚。Rust 在这类场景里优势特别明显。

When to Choose Rust Over C#
什么时候该选 Rust，而不是 C#

✅ Choose Rust When:
✅ 这些场景优先考虑 Rust：

• Correctness matters: State machines, protocol implementations, financial logic, where a missed case is a production incident instead of a minor bug.
  正确性极其关键：状态机、协议实现、金融逻辑，这类地方漏掉一个分支就可能是事故。
• Performance is critical: Real-time systems, high-frequency trading, game engines.
  性能非常关键：实时系统、高频交易、游戏引擎。
• Memory usage matters: Embedded devices, mobile apps, cloud infrastructure costs.
  内存成本敏感：嵌入式、移动端、云成本场景。
• Predictability is required: Medical devices, automotive, financial systems.
  必须要可预测性：医疗、汽车、金融等系统。
• Security is paramount: Cryptography, network security, system-level components.
  安全性优先级极高：密码学、网络安全、系统级组件。
• Long-running services: GC pauses can accumulate into visible tail-latency problems.
  长时间运行的服务：GC 停顿会不断转化成可见的尾延迟问题。
• Resource-constrained environments: IoT and edge computing.
  资源受限环境：IoT、边缘计算。
• System programming: CLI tools, databases, web servers, operating systems.
  系统级编程：命令行工具、数据库、Web 服务器、操作系统。

✅ Stay with C# When:
✅ 这些场景继续用 C# 更划算：

• Rapid application development: Business systems and CRUD-heavy applications.
  强调快速业务开发：各种后台系统、CRUD 项目。
• Large existing codebase: Migration cost is simply too high.
  已有巨大存量代码：迁移成本过高。
• Team expertise: The Rust learning curve would not pay back soon enough.
  团队能力结构决定：Rust 学习成本短期内回不了本。
• Enterprise integrations: Deep .NET and Windows ecosystem dependencies.
  企业级集成密集：重度依赖 .NET、Windows 生态。
• GUI applications: WPF, WinUI, Blazor and the broader .NET UI stack.
  GUI 应用：WPF、WinUI、Blazor 这一整套生态仍然更顺手。
• Time to market dominates: Shipping quickly is worth more than squeezing out runtime costs.
  时间窗口压倒一切：先快速交付比追求极致性能更重要。

🔄 Consider Both (Hybrid Approach):
🔄 也可以两者结合：

• Performance-critical components in Rust called from C# via FFI or P/Invoke.
  把性能敏感组件写成 Rust，通过 FFI / P/Invoke 给 C# 调。
• Business logic in C#, where familiar tooling and development speed still shine.
  业务逻辑主体继续放在 C#，保留开发效率和熟悉度。
• Gradual migration, starting with new services or isolated modules.
  逐步迁移，从新服务或隔离模块开始，而不是一口吃成胖子。

Real-World Impact: Why Companies Choose Rust
现实世界里的影响：为什么很多公司会选 Rust

Dropbox: Storage Infrastructure
Dropbox：存储基础设施

• Before (Python): High CPU usage, large memory overhead.
  之前（Python）：CPU 占用高，内存开销大。
• After (Rust): Around 10x performance improvement and about 50% memory reduction.
  之后（Rust）：性能大约提升 10 倍，内存下降约一半。
• Result: Infrastructure cost savings at very large scale.
  结果：在大规模基础设施上直接省钱。

Discord: Voice/Video Backend
Discord：音视频后端

• Before (Go): GC pauses caused audio drops.
  之前（Go）：GC 停顿会导致音频掉帧、断续。
• After (Rust): Stable low-latency performance.
  之后（Rust）：低延迟表现更稳定。
• Result: Better user experience and lower server costs.
  结果：用户体验更好，服务器成本也更低。

Microsoft: Windows Components
微软：Windows 组件

• Rust in Windows: File system and networking stack components are already using Rust in parts.
  Windows 里的 Rust：文件系统、网络栈等部分组件已经开始引入 Rust。
• Benefit: Memory safety without giving up performance.
  收益：内存安全和性能不再必须二选一。
• Impact: Fewer security vulnerabilities with the same runtime profile.
  影响：在不牺牲运行表现的前提下减少安全漏洞。

Why This Matters for C# Developers:
为什么这些例子对 C# 开发者有意义：

1. Complementary skills: Rust and C# solve different classes of problems.
   能力互补：Rust 和 C# 擅长解决的问题类型并不完全一样。
2. Career growth: Systems programming ability is increasingly valuable.
   职业成长：系统级编程能力越来越值钱。
3. Performance understanding: Rust helps develop intuition for zero-cost abstractions and data layout.
   性能认知升级：Rust 会逼着人真正理解零成本抽象、数据布局和资源所有权。
4. Safety mindset: Ownership thinking will improve code quality even in other languages.
   安全思维迁移：所有权思维回流到别的语言里，也会提升整体代码质量。
5. Cloud costs: Performance and memory behavior often map directly to infrastructure spending.
   云成本现实：性能和内存占用很多时候直接就是服务器账单。

Language Philosophy Comparison
语言哲学对照

C# Philosophy
C# 的哲学

• Productivity first: Rich tooling, broad framework support, and a large “pit of success”.
  生产力优先：工具强、框架多、成功路径铺得比较平。
• Managed runtime: Garbage collection handles memory automatically.
  托管运行时：内存管理主要交给 GC。
• Enterprise-focused: Strong typing plus reflection and a huge standard ecosystem.
  企业场景友好：强类型加反射，再配成熟的大生态。
• Object-oriented: Classes, inheritance, and interfaces remain primary abstractions.
  偏面向对象：类、继承、接口长期是主抽象手段。

Rust Philosophy
Rust 的哲学

• Performance without sacrifice: Zero-cost abstractions and no mandatory runtime tax.
  性能不妥协：零成本抽象，不背强制运行时包袱。
• Memory safety: Compile-time guarantees prevent crashes and many security bugs.
  内存安全优先：很多崩溃和安全问题在编译期就挡掉。
• Systems programming: It gives low-level control while keeping high-level abstractions.
  系统级定位：既保留底层控制力，也提供高层抽象。
• Functional + systems: Immutability by default, ownership-driven resource management.
  函数式和系统编程融合：默认不可变，资源管理围着所有权展开。

graph TD
    subgraph "C# Development Model"
        CS_CODE["C# Source Code<br/>Classes, Methods, Properties"]
        CS_COMPILE["C# Compiler<br/>(csc.exe)"]
        CS_IL["Intermediate Language<br/>(IL bytecode)"]
        CS_RUNTIME[".NET Runtime<br/>(CLR)"]
        CS_JIT["Just-In-Time Compiler"]
        CS_NATIVE["Native Machine Code"]
        CS_GC["Garbage Collector<br/>(Memory management)"]
        
        CS_CODE --> CS_COMPILE
        CS_COMPILE --> CS_IL
        CS_IL --> CS_RUNTIME
        CS_RUNTIME --> CS_JIT
        CS_JIT --> CS_NATIVE
        CS_RUNTIME --> CS_GC
        
        CS_BENEFITS["[OK] Fast development<br/>[OK] Rich ecosystem<br/>[OK] Automatic memory management<br/>[ERROR] Runtime overhead<br/>[ERROR] GC pauses<br/>[ERROR] Platform dependency"]
    end
    
    subgraph "Rust Development Model"
        RUST_CODE["Rust Source Code<br/>Structs, Enums, Functions"]
        RUST_COMPILE["Rust Compiler<br/>(rustc)"]
        RUST_NATIVE["Native Machine Code<br/>(Direct compilation)"]
        RUST_ZERO["Zero Runtime<br/>(No VM, No GC)"]
        
        RUST_CODE --> RUST_COMPILE
        RUST_COMPILE --> RUST_NATIVE
        RUST_NATIVE --> RUST_ZERO
        
        RUST_BENEFITS["[OK] Maximum performance<br/>[OK] Memory safety<br/>[OK] No runtime dependencies<br/>[ERROR] Steeper learning curve<br/>[ERROR] Longer compile times<br/>[ERROR] More explicit code"]
    end
    
    style CS_BENEFITS fill:#e3f2fd,color:#000
    style RUST_BENEFITS fill:#e8f5e8,color:#000
    style CS_GC fill:#fff3e0,color:#000
    style RUST_ZERO fill:#e8f5e8,color:#000

Quick Reference: Rust vs C#
Rust 与 C# 速查对照

Getting Started §§ZH§§ 快速开始

Installation and Setup
安装与环境准备

What you’ll learn: How to install Rust and set up your IDE, the Cargo build system vs MSBuild/NuGet, your first Rust program compared to C#, and how to read command-line input.
本章将学到什么： 如何安装 Rust 并配置开发环境，Cargo 构建系统和 MSBuild / NuGet 的对应关系，第一段 Rust 程序和 C# 的对照，以及如何读取命令行输入。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Installing Rust
安装 Rust

# Install Rust (works on Windows, macOS, Linux)
# 安装 Rust（Windows、macOS、Linux 都可用）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# On Windows, you can also download from: https://rustup.rs/
# 在 Windows 上也可以直接从这个地址下载安装包：https://rustup.rs/

Rust Tools vs C# Tools
Rust 工具链与 C# 工具链对照

IDE Setup
IDE 配置

1. VS Code (Recommended for beginners)
   1. VS Code（适合刚上手的人）

   • Install the rust-analyzer extension
     安装 rust-analyzer 扩展
   • Install CodeLLDB for debugging
     安装 CodeLLDB 作为调试器

2. Visual Studio (Windows)
   2. Visual Studio（Windows）

   • Install a Rust support extension
     安装 Rust 支持扩展

3. JetBrains RustRover (Full IDE)
   3. JetBrains RustRover（完整 IDE）

   • Similar to Rider for C# developers
     对 C# 开发者来说，使用感受和 Rider 比较接近

Your First Rust Program
第一段 Rust 程序

C# Hello World
C# 版 Hello World

// Program.cs
using System;

namespace HelloWorld
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello, World!");
        }
    }
}

Rust Hello World
Rust 版 Hello World

// main.rs
fn main() {
    println!("Hello, World!");
}

Key Differences for C# Developers
C# 开发者需要先记住的差别

1. No classes required - Functions can exist at the top level
   1. 不需要类，函数可以直接定义在顶层。
2. No namespaces - Uses module system instead
   2. 没有 namespace，Rust 用模块系统组织代码。
3. println! is a macro - Notice the !
   3. println! 是宏，后面的 ! 不是摆设。
4. No semicolon after println! - Expression vs statement
   4. println! 这一段开始要慢慢习惯 Rust 里“表达式”和“语句”的区别。
5. No explicit return type - main returns () (unit type)
   5. 没有显式返回类型，main 默认返回 ()，也就是单元类型。

Creating Your First Project
创建第一个项目

# Create new project (like 'dotnet new console')
# 创建新项目（相当于 'dotnet new console'）
cargo new hello_rust
cd hello_rust

# Project structure created:
# 生成出来的项目结构：
# hello_rust/
# ├── Cargo.toml      (like .csproj file)
# │                   （相当于 .csproj 文件）
# └── src/
#     └── main.rs     (like Program.cs)
#                      （相当于 Program.cs）

# Run the project (like 'dotnet run')
# 运行项目（相当于 'dotnet run'）
cargo run

Cargo vs NuGet/MSBuild
Cargo 与 NuGet / MSBuild 的对应关系

Project Configuration
项目配置文件

C# (.csproj)
C#（.csproj）

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageReference Include="Serilog" Version="3.0.1" />
</Project>

Rust (Cargo.toml)
Rust（Cargo.toml）

[package]
name = "hello_rust"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1.0"    # Like Newtonsoft.Json
log = "0.4"           # Like Serilog

Common Cargo Commands
常用 Cargo 命令

# Create new project
# 创建新项目
cargo new my_project
cargo new my_project --lib  # Create library project
                             # 创建库项目

# Build and run
# 编译与运行
cargo build          # Like 'dotnet build'
cargo run            # Like 'dotnet run'
cargo test           # Like 'dotnet test'

# Package management
# 包管理
cargo add serde      # Add dependency (like 'dotnet add package')
cargo update         # Update dependencies

# Release build
# 发布构建
cargo build --release  # Optimized build
cargo run --release    # Run optimized version

# Documentation
# 文档
cargo doc --open     # Generate and open docs

Workspace vs Solution
Workspace 与 Solution 的对照

C# Solution (.sln)
C# 的 Solution（.sln）

MySolution/
├── MySolution.sln
├── WebApi/
│   └── WebApi.csproj
├── Business/
│   └── Business.csproj
└── Tests/
    └── Tests.csproj

Rust Workspace (Cargo.toml)
Rust 的 Workspace（写在 Cargo.toml 里）

[workspace]
members = [
    "web_api",
    "business", 
    "tests"
]

Reading Input and CLI Arguments
读取输入与命令行参数

Every C# developer knows Console.ReadLine(). Here’s how Rust handles user input, environment variables, and command-line arguments.
Console.ReadLine() 写 C# 的都熟，Rust 这边处理用户输入、环境变量和命令行参数的方式也得顺手摸清。

Console Input
控制台输入

// C# — reading user input
// C#：读取用户输入
Console.Write("Enter your name: ");
string? name = Console.ReadLine();  // Returns string? in .NET 6+
Console.WriteLine($"Hello, {name}!");

// Parsing input
// 解析输入
Console.Write("Enter a number: ");
if (int.TryParse(Console.ReadLine(), out int number))
{
    Console.WriteLine($"You entered: {number}");
}
else
{
    Console.WriteLine("That's not a valid number.");
}

use std::io::{self, Write};

fn main() {
    // Reading a line of input
    // 读取一行输入
    print!("Enter your name: ");
    io::stdout().flush().unwrap(); // flush because print! doesn't auto-flush
                                  // print! 不会自动刷新，所以要手动 flush

    let mut name = String::new();
    io::stdin().read_line(&mut name).expect("Failed to read line");
    let name = name.trim(); // remove trailing newline
                            // 去掉结尾换行
    println!("Hello, {name}!");

    // Parsing input
    // 解析输入
    print!("Enter a number: ");
    io::stdout().flush().unwrap();

    let mut input = String::new();
    io::stdin().read_line(&mut input).expect("Failed to read");
    match input.trim().parse::<i32>() {
        Ok(number) => println!("You entered: {number}"),
        Err(_)     => println!("That's not a valid number."),
    }
}

Command-Line Arguments
命令行参数

// C# — reading CLI args
// C#：读取命令行参数
static void Main(string[] args)
{
    if (args.Length < 1)
    {
        Console.WriteLine("Usage: program <filename>");
        return;
    }
    string filename = args[0];
    Console.WriteLine($"Processing {filename}");
}

use std::env;

fn main() {
    let args: Vec<String> = env::args().collect();
    // args[0] = program name (like C#'s Assembly name)
    // args[1..] = actual arguments
    // args[0] 是程序名，args[1..] 才是真正传进来的参数

    if args.len() < 2 {
        eprintln!("Usage: {} <filename>", args[0]); // eprintln! -> stderr
                                                    // eprintln! 会写到标准错误
        std::process::exit(1);
    }
    let filename = &args[1];
    println!("Processing {filename}");
}

Environment Variables
环境变量

// C#
string dbUrl = Environment.GetEnvironmentVariable("DATABASE_URL") ?? "localhost";

#![allow(unused)]
fn main() {
use std::env;

let db_url = env::var("DATABASE_URL").unwrap_or_else(|_| "localhost".to_string());
// env::var returns Result<String, VarError> — no nulls!
// env::var 返回的是 Result<String, VarError>，不会给个 null 糊弄过去
}

Production CLI Apps with clap
用 clap 编写正式 CLI 程序

For anything beyond trivial argument parsing, use the clap crate. It fills the role that System.CommandLine or CommandLineParser libraries play in C#.
只要参数解析稍微复杂一点，就该把 clap 拿出来了。它在 Rust 里的定位，大致就和 C# 里的 System.CommandLine、CommandLineParser 一个级别。

# Cargo.toml
[dependencies]
clap = { version = "4", features = ["derive"] }

use clap::Parser;

/// A simple file processor — this doc comment becomes the help text
/// 一个简单的文件处理器，这段文档注释会直接变成帮助文本
#[derive(Parser, Debug)]
#[command(name = "processor", version, about)]
struct Args {
    /// Input file to process
    /// 要处理的输入文件
    #[arg(short, long)]
    input: String,

    /// Output file (defaults to stdout)
    /// 输出文件，默认写到标准输出
    #[arg(short, long)]
    output: Option<String>,

    /// Enable verbose logging
    /// 打开详细日志
    #[arg(short, long, default_value_t = false)]
    verbose: bool,

    /// Number of worker threads
    /// 工作线程数量
    #[arg(short = 'j', long, default_value_t = 4)]
    threads: usize,
}

fn main() {
    let args = Args::parse(); // auto-parses, validates, generates --help
                              // 自动解析、校验，并生成 --help

    if args.verbose {
        println!("Input:   {}", args.input);
        println!("Output:  {:?}", args.output);
        println!("Threads: {}", args.threads);
    }

    // Use args.input, args.output, etc.
    // 后面直接使用 args.input、args.output 等字段即可
}

# Auto-generated help:
# 自动生成的帮助信息：
$ processor --help
A simple file processor

Usage: processor [OPTIONS] --input <INPUT>

Options:
  -i, --input <INPUT>      Input file to process
  -o, --output <OUTPUT>    Output file (defaults to stdout)
  -v, --verbose            Enable verbose logging
  -j, --threads <THREADS>  Number of worker threads [default: 4]
  -h, --help               Print help
  -V, --version            Print version

// C# equivalent with System.CommandLine (more boilerplate):
// C# 里用 System.CommandLine 的对应写法，样板代码会更多一些：
var inputOption = new Option<string>("--input", "Input file") { IsRequired = true };
var verboseOption = new Option<bool>("--verbose", "Enable verbose logging");
var rootCommand = new RootCommand("A simple file processor");
rootCommand.AddOption(inputOption);
rootCommand.AddOption(verboseOption);
rootCommand.SetHandler((input, verbose) => { /* ... */ }, inputOption, verboseOption);
await rootCommand.InvokeAsync(args);
// clap's derive macro approach is more concise and type-safe
// clap 用 derive 宏写起来更紧凑，类型约束也更自然

Essential Keywords Reference (optional) §§ZH§§ 核心关键字速查表（可选）

Essential Rust Keywords for C# Developers
面向 C# 开发者的 Rust 核心关键字速查

What you’ll learn: A quick-reference mapping of Rust keywords to their C# equivalents — visibility modifiers, ownership keywords, control flow, type definitions, and pattern matching syntax.
本章将学到什么： 一份面向 C# 开发者的 Rust 关键字速查表，覆盖可见性修饰符、所有权相关关键字、控制流、类型定义和模式匹配语法。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Understanding Rust’s keywords and their purposes helps C# developers navigate the language more effectively.
先把 Rust 关键字和用途认熟，C# 开发者切进 Rust 时会顺很多，不至于看代码像在啃天书。

Visibility and Access Control Keywords
可见性与访问控制关键字

C# Access Modifiers
C# 的访问修饰符

public class Example
{
    public int PublicField;           // Accessible everywhere
    private int privateField;        // Only within this class
    protected int protectedField;    // This class and subclasses
    internal int internalField;      // Within this assembly
    protected internal int protectedInternalField; // Combination
}

Rust Visibility Keywords
Rust 的可见性关键字

#![allow(unused)]
fn main() {
// pub - Makes items public (like C# public)
pub struct PublicStruct {
    pub public_field: i32,           // Public field
    private_field: i32,              // Private by default (no keyword)
}

pub mod my_module {
    pub(crate) fn crate_public() {}     // Public within current crate (like internal)
    pub(super) fn parent_public() {}    // Public to parent module
    pub(self) fn self_public() {}       // Public within current module (same as private)
    
    pub use super::PublicStruct;        // Re-export (like using alias)
}

// No direct equivalent to C# protected - use composition instead
}

Rust 这块最容易让 C# 开发者发愣的点，是“默认私有”。很多东西不写 pub 就关起来了，而且 pub(crate)、pub(super) 这种粒度比 C# 更细。
另外，Rust 没有一个和 C# protected 完全对位的关键字，很多时候更推荐通过模块边界和组合关系来表达设计意图。

Memory and Ownership Keywords
内存与所有权关键字

C# Memory Keywords
C# 里和内存相关的关键字

// ref - Pass by reference
public void Method(ref int value) { value = 10; }

// out - Output parameter
public bool TryParse(string input, out int result) { /* */ }

// in - Readonly reference (C# 7.2+)
public void ReadOnly(in LargeStruct data) { /* Cannot modify data */ }

Rust Ownership Keywords
Rust 里的所有权相关关键字

#![allow(unused)]
fn main() {
// & - Immutable reference (like C# in parameter)
fn read_only(data: &Vec<i32>) {
    println!("Length: {}", data.len()); // Can read, cannot modify
}

// &mut - Mutable reference (like C# ref parameter)
fn modify(data: &mut Vec<i32>) {
    data.push(42); // Can modify
}

// move - Force move capture in closures
let data = vec![1, 2, 3];
let closure = move || {
    println!("{:?}", data); // data is moved into closure
};
// data is no longer accessible here

// Box - Heap allocation (like C# new for reference types)
let boxed_data = Box::new(42); // Allocate on heap
}

这部分是 Rust 和 C# 真正拉开差距的地方。C# 里的 ref、out、in 更像参数传递方式；Rust 的 &、&mut 背后还连着借用规则和生命周期。
move 也很关键，它不是“复制一份”，而是把所有权直接交出去。这个语义如果没吃透，后面闭包、线程和异步代码会频繁撞墙。

Control Flow Keywords
控制流关键字

C# Control Flow
C# 的控制流

// return - Exit function with value
public int GetValue() { return 42; }

// yield return - Iterator pattern
public IEnumerable<int> GetNumbers()
{
    yield return 1;
    yield return 2;
}

// break/continue - Loop control
foreach (var item in items)
{
    if (item == null) continue;
    if (item.Stop) break;
}

Rust Control Flow Keywords
Rust 的控制流关键字

#![allow(unused)]
fn main() {
// return - Explicit return (usually not needed)
fn get_value() -> i32 {
    return 42; // Explicit return
    // OR just: 42 (implicit return)
}

// break/continue - Loop control with optional values
fn find_value() -> Option<i32> {
    loop {
        let value = get_next();
        if value < 0 { continue; }
        if value > 100 { break None; }      // Break with value
        if value == 42 { break Some(value); } // Break with success
    }
}

// loop - Infinite loop (like while(true))
loop {
    if condition { break; }
}

// while - Conditional loop
while condition {
    // code
}

// for - Iterator loop
for item in collection {
    // code
}
}

Rust 这里最骚的一点，是 break 还能带值，loop 因此不只是“死循环”，还可以被拿来当表达式。
另外，Rust 末尾表达式默认返回值这件事，也和 C# 那种处处写 return 的风格很不一样。

Type Definition Keywords
类型定义关键字

C# Type Keywords
C# 的类型关键字

// class - Reference type
public class MyClass { }

// struct - Value type
public struct MyStruct { }

// interface - Contract definition
public interface IMyInterface { }

// enum - Enumeration
public enum MyEnum { Value1, Value2 }

// delegate - Function pointer
public delegate void MyDelegate(int value);

Rust Type Keywords
Rust 的类型关键字

#![allow(unused)]
fn main() {
// struct - Data structure (like C# class/struct combined)
struct MyStruct {
    field: i32,
}

// enum - Algebraic data type (much more powerful than C# enum)
enum MyEnum {
    Variant1,
    Variant2(i32),               // Can hold data
    Variant3 { x: i32, y: i32 }, // Struct-like variant
}

// trait - Interface definition (like C# interface but more powerful)
trait MyTrait {
    fn method(&self);
    
    // Default implementation (like C# 8+ default interface methods)
    fn default_method(&self) {
        println!("Default implementation");
    }
}

// type - Type alias (like C# using alias)
type UserId = u32;
type Result<T> = std::result::Result<T, MyError>;

// impl - Implementation block
impl MyStruct {
    fn new() -> MyStruct {
        MyStruct { field: 0 }
    }
}

impl MyTrait for MyStruct {
    fn method(&self) {
        println!("Implementation");
    }
}
}

Rust 的 enum 比 C# enum 强得多，这玩意儿本质上已经是代数数据类型了，能直接带结构化数据。
trait 也不只是接口翻版，它配合默认实现、泛型约束和静态分发，能玩出来的花样比 C# interface 更大。

Function Definition Keywords
函数定义关键字

C# Function Keywords
C# 的函数关键字

// static - Class method
public static void StaticMethod() { }

// virtual - Can be overridden
public virtual void VirtualMethod() { }

// override - Override base method
public override void VirtualMethod() { }

// abstract - Must be implemented
public abstract void AbstractMethod();

// async - Asynchronous method
public async Task<int> AsyncMethod() { return await SomeTask(); }

Rust Function Keywords
Rust 的函数关键字

#![allow(unused)]
fn main() {
// fn - Function definition
fn regular_function() {
    println!("Hello");
}

// const fn - Compile-time function
const fn compile_time_function() -> i32 {
    42
}

// async fn - Asynchronous function
async fn async_function() -> i32 {
    some_async_operation().await
}

// unsafe fn - Function that may violate memory safety
unsafe fn unsafe_function() {
    // Can perform unsafe operations
}

// extern fn - Foreign function interface
extern "C" fn c_compatible_function() {
    // Can be called from C
}
}

Rust 没有 virtual、override 这一套继承味很重的关键字组合，很多行为差异会被 trait 和静态分发吸收掉。
反过来，const fn、unsafe fn、extern fn 这类关键字会更早把“这函数属于哪种语义区域”标清楚。

Variable Declaration Keywords
变量声明关键字

C# Variable Keywords
C# 的变量关键字

// var - Type inference
var name = "John"; // Inferred as string

// const - Compile-time constant
const int MaxSize = 100;

// readonly - Runtime constant (fields only, not local variables)
// readonly DateTime createdAt = DateTime.Now;

// static - Class-level variable
static int instanceCount = 0;

Rust Variable Keywords
Rust 的变量关键字

#![allow(unused)]
fn main() {
// let - Variable binding
let name = "John"; // Immutable by default

// let mut - Mutable variable binding
let mut count = 0;
count += 1;

// const - Compile-time constant
const MAX_SIZE: usize = 100;

// static - Global variable
static INSTANCE_COUNT: std::sync::atomic::AtomicUsize =
    std::sync::atomic::AtomicUsize::new(0);
}

这里最值得记住的一件事就是：Rust 默认不可变。
C# 里如果不特意写 readonly，很多变量都是默认可改；Rust 则反过来，想改就必须显式 mut。

Pattern Matching Keywords
模式匹配关键字

C# Pattern Matching (C# 8+)
C# 8+ 的模式匹配

// switch expression
string result = value switch
{
    1 => "One",
    2 => "Two",
    _ => "Other"
};

// is pattern
if (obj is string str)
{
    Console.WriteLine(str.Length);
}

Rust Pattern Matching Keywords
Rust 的模式匹配关键字

#![allow(unused)]
fn main() {
// match - Pattern matching
let result = match value {
    1 => "One",
    2 => "Two",
    3..=10 => "Between 3 and 10",
    _ => "Other",
};

// if let - Conditional pattern matching
if let Some(value) = optional {
    println!("Got value: {}", value);
}

// while let - Loop with pattern matching
while let Some(item) = iterator.next() {
    println!("Item: {}", item);
}

// let with patterns - Destructuring
let (x, y) = point;
let Some(value) = optional else {
    return;
};
}

Rust 的 match 不只是更强的 switch，它还要求分支穷尽。
这一点很值钱，因为很多“漏写一个 case”在编译期就会被卡死，不等到运行时再翻车。

Memory Safety Keywords
内存安全关键字

C# Memory Keywords
C# 里的内存安全相关关键字

// unsafe - Disable safety checks
unsafe
{
    int* ptr = &variable;
    *ptr = 42;
}

// fixed - Pin managed memory
unsafe
{
    fixed (byte* ptr = array)
    {
        // Use ptr
    }
}

Rust Safety Keywords
Rust 的安全关键字

#![allow(unused)]
fn main() {
// unsafe - Disable borrow checker (use sparingly!)
unsafe {
    let ptr = &variable as *const i32;
    let value = *ptr; // Dereference raw pointer
}

// Raw pointer types
let ptr: *const i32 = &42;
let ptr: *mut i32 = &mut 42;
}

Rust 里 unsafe 不是“随便乱搞许可证”，而是“这里的安全性证明交给开发者自己承担”的标记。
也正因为这样，unsafe 区域通常越小越好，最好把危险操作关进一层安全抽象里。

Common Rust Keywords Not in C#
C# 里没有直接对应物的 Rust 常见关键字

#![allow(unused)]
fn main() {
// where - Generic constraints
fn generic_function<T>()
where
    T: Clone + Send + Sync,
{
}

// dyn - Dynamic trait objects
let drawable: Box<dyn Draw> = Box::new(Circle::new());

// Self - Refer to the implementing type
impl MyStruct {
    fn new() -> Self {
        Self { field: 0 }
    }
}

// self - Method receiver
impl MyStruct {
    fn method(&self) { }
    fn method_mut(&mut self) { }
    fn consume(self) { }
}

// crate - Refer to current crate root
use crate::models::User;

// super - Refer to parent module
use super::utils;
}

这几个关键字经常会让 C# 开发者一开始有点懵。
尤其是 dyn、Self、self、crate、super 这些，看起来短，实际背后牵扯的是 Rust 的模块系统、trait 对象和方法接收者模型。

Keywords Summary for C# Developers
面向 C# 开发者的关键字总表

Built-in Types and Variables §§ZH§§ 内置类型与变量

Variables and Mutability
变量与可变性

What you’ll learn: Rust’s variable declaration and mutability model compared with C# var and const, primitive type mappings, the important distinction between String and &str, type inference, and Rust’s stricter approach to casting and conversions.
本章将学到什么： 对照理解 Rust 的变量声明与可变性模型，理解它和 C# 里的 var、const 有什么差别，熟悉基础类型映射，掌握 String 与 &str 的关键区别，理解类型推断，以及 Rust 对类型转换更严格的处理方式。

Difficulty: 🟢 Beginner
难度： 🟢 入门

C# Variable Declaration
C# 的变量声明

// C# - Variables are mutable by default
int count = 0;           // Mutable
count = 5;               // ✅ Works

// readonly fields (class-level only, not for local variables)
// readonly int maxSize = 100;  // Immutable after initialization

const int BUFFER_SIZE = 1024; // Compile-time constant (works as local or field)

Rust Variable Declaration
Rust 的变量声明

#![allow(unused)]
fn main() {
// Rust - Variables are immutable by default
let count = 0;           // Immutable by default
// count = 5;            // ❌ Compile error: cannot assign twice to immutable variable

let mut count = 0;       // Explicitly mutable
count = 5;               // ✅ Works

const BUFFER_SIZE: usize = 1024; // Compile-time constant
}

Rust 在这里的核心思路很简单：默认别改，真要改就把 mut 写出来。
这和 C# 基本反着来。C# 里默认可变，想收紧要额外写；Rust 则先把变化这件事当成需要明确声明的动作。

Key Mental Shift for C# Developers
给 C# 开发者的关键心智转变

#![allow(unused)]
fn main() {
// Think of 'let' as C#'s readonly field semantics applied to all variables
let name = "John";       // Like a readonly field: once set, cannot change
let mut age = 30;        // Like: int age = 30;

// Variable shadowing (unique to Rust)
let spaces = "   ";      // String
let spaces = spaces.len(); // Now it's a number (usize)
// This is different from mutation - we're creating a new variable
}

shadowing 很容易被误会成“换皮的可变赋值”，其实不是一回事。
它不是把原变量改了，而是重新引入了一个同名新变量。这个机制在类型转换、去空格、解析字符串这类场景里非常顺手。

Practical Example: Counter
实战例子：计数器

// C# version
public class Counter
{
    private int value = 0;
    
    public void Increment()
    {
        value++;  // Mutation
    }
    
    public int GetValue() => value;
}

#![allow(unused)]
fn main() {
// Rust version
pub struct Counter {
    value: i32,  // Private by default
}

impl Counter {
    pub fn new() -> Counter {
        Counter { value: 0 }
    }
    
    pub fn increment(&mut self) {  // &mut needed for mutation
        self.value += 1;
    }
    
    pub fn get_value(&self) -> i32 {
        self.value
    }
}
}

这里顺手就把 Rust 的另一个常识带出来了：方法要改内部状态，就得拿到 &mut self。
也就是说，可变性不只是变量层面的事，方法签名层面也会被强制写清楚。

Data Types Comparison
数据类型对照

Primitive Types
基础类型

Size Types (Important!)
尺寸类型（很重要）

// C# - int is always 32-bit
int arrayIndex = 0;
long fileSize = file.Length;

#![allow(unused)]
fn main() {
// Rust - size types match pointer size (32-bit or 64-bit)
let array_index: usize = 0;    // Like size_t in C
let file_size: u64 = file.len(); // Explicit 64-bit
}

usize 和 isize 是 Rust 里很容易早期忽略、后面频繁见到的类型。
只要牵扯到索引、容量、长度、切片范围，这俩就经常跳出来，因为它们专门表示“适合当前平台地址宽度的大小”。

Type Inference
类型推断

// C# - var keyword
var name = "John";        // string
var count = 42;           // int
var price = 29.99;        // double

#![allow(unused)]
fn main() {
// Rust - automatic type inference
let name = "John";        // &str (string slice)
let count = 42;           // i32 (default integer)
let price = 29.99;        // f64 (default float)

// Explicit type annotations
let count: u32 = 42;
let price: f32 = 29.99;
}

Rust 的类型推断很强，但它不是“模糊处理”。
一旦上下文不够，或者默认推断类型和需求不一致，就得老老实实补标注。尤其是空集合、数值类型和泛型代码里，这种事很常见。

Arrays and Collections Overview
数组与集合概览

// C# - reference types, heap allocated
int[] numbers = new int[5];        // Fixed size
List<int> list = new List<int>();  // Dynamic size

#![allow(unused)]
fn main() {
// Rust - multiple options
let numbers: [i32; 5] = [1, 2, 3, 4, 5];  // Stack array, fixed size
let mut list: Vec<i32> = Vec::new();       // Heap vector, dynamic size
}

Rust 对“固定大小数组”和“动态大小向量”分得更清楚。
数组 [T; N] 是类型级别就带长度的，Vec<T> 才是运行时可增长的集合。别把两者混成一回事，不然一到函数参数和 trait 实现就容易懵。

String Types: String vs &str
字符串类型：String 与 &str

This is one of the most confusing concepts for C# developers, so it deserves careful treatment.
这是 C# 开发者进 Rust 最容易卡住的地方之一，所以必须掰细了讲。很多前期的所有权、借用、函数参数设计问题，最后都会绕回这里。

C# String Handling
C# 的字符串处理

// C# - Simple string model
string name = "John";           // String literal
string greeting = "Hello, " + name;  // String concatenation
string upper = name.ToUpper();  // Method call

Rust String Types
Rust 的字符串类型

#![allow(unused)]
fn main() {
// Rust - Two main string types

// 1. &str (string slice) - like ReadOnlySpan<char> in C#
let name: &str = "John";        // String literal (immutable, borrowed)

// 2. String - like StringBuilder or mutable string
let mut greeting = String::new();       // Empty string
greeting.push_str("Hello, ");          // Append
greeting.push_str(name);               // Append

// Or create directly
let greeting = String::from("Hello, John");
let greeting = "Hello, John".to_string();  // Convert &str to String
}

When to Use Which?
什么时候该用哪个

Practical Examples
实战例子

// Function that accepts any string type
fn greet(name: &str) {  // Accepts both String and &str
    println!("Hello, {}!", name);
}

fn main() {
    let literal = "John";                    // &str
    let owned = String::from("Jane");        // String
    
    greet(literal);                          // Works
    greet(&owned);                           // Works (borrow String as &str)
    greet("Bob");                            // Works
}

// Function that returns owned string
fn create_greeting(name: &str) -> String {
    format!("Hello, {}!", name)  // format! macro returns String
}

函数参数优先写 &str，这是 Rust 里非常常见的习惯。
因为它最宽松，既能接字面量，也能接 String 的借用。除非函数明确要拿走字符串所有权，否则别上来就写 String，那样会把调用方搞得更难受。

C# Developers: Think of it This Way
给 C# 开发者的直观类比

#![allow(unused)]
fn main() {
// &str is like ReadOnlySpan<char> - a view into string data
// String is like a char[] that you own and can modify

let borrowed: &str = "I don't own this data";
let owned: String = String::from("I own this data");

// Convert between them
let owned_copy: String = borrowed.to_string();  // Copy to owned
let borrowed_view: &str = &owned;               // Borrow from owned
}

当然，这个类比只能帮入门，别太当真。
但在早期阶段，用“&str 是借来的视图，String 是自己拥有的字符串缓冲区”这个脑图，已经足够把很多问题想顺。

Printing and String Formatting
打印与字符串格式化

C# developers rely heavily on Console.WriteLine and string interpolation. Rust has equally strong formatting tools, but they live in macros and trait-based formatting machinery.
C# 里大家基本张嘴就是 Console.WriteLine 和插值字符串；Rust 这边的能力一点也不弱，只是它更多是通过宏和格式化 trait 体系来运作。

Basic Output
基础输出

// C# output
Console.Write("no newline");
Console.WriteLine("with newline");
Console.Error.WriteLine("to stderr");

// String interpolation (C# 6+)
string name = "Alice";
int age = 30;
Console.WriteLine($"{name} is {age} years old");

#![allow(unused)]
fn main() {
// Rust output — all macros (note the !)
print!("no newline");              // → stdout, no newline
println!("with newline");           // → stdout + newline
eprint!("to stderr");              // → stderr, no newline  
eprintln!("to stderr with newline"); // → stderr + newline

// String formatting (like $"" interpolation)
let name = "Alice";
let age = 30;
println!("{name} is {age} years old");     // Inline variable capture (Rust 1.58+)
println!("{} is {} years old", name, age); // Positional arguments

// format! returns a String instead of printing
let msg = format!("{name} is {age} years old");
}

Rust 里一看到 println!、format! 这种写法，就记住后面的 ! 不是装饰。
这些都是宏，不是普通函数。也正因为是宏，格式字符串检查和参数展开才能在编译期做得这么紧。

Format Specifiers
格式说明符

// C# format specifiers
Console.WriteLine($"{price:F2}");         // Fixed decimal:  29.99
Console.WriteLine($"{count:D5}");         // Padded integer: 00042
Console.WriteLine($"{value,10}");         // Right-aligned, width 10
Console.WriteLine($"{value,-10}");        // Left-aligned, width 10
Console.WriteLine($"{hex:X}");            // Hexadecimal:    FF
Console.WriteLine($"{ratio:P1}");         // Percentage:     85.0%

#![allow(unused)]
fn main() {
// Rust format specifiers
println!("{price:.2}");          // 2 decimal places:  29.99
println!("{count:05}");          // Zero-padded, width 5: 00042
println!("{value:>10}");         // Right-aligned, width 10
println!("{value:<10}");         // Left-aligned, width 10
println!("{value:^10}");         // Center-aligned, width 10
println!("{hex:#X}");            // Hex with prefix: 0xFF
println!("{hex:08X}");           // Hex zero-padded: 000000FF
println!("{bits:#010b}");        // Binary with prefix: 0b00001010
println!("{big}", big = 1_000_000); // Named parameter
}

这套格式说明符一开始看着有点硬，但用熟了比 C# 那套更统一。
特别是和 Display、Debug 这些 trait 结合以后，用户输出和开发者调试输出能分得很明白。

Debug vs Display Printing
Debug 与 Display 打印

#![allow(unused)]
fn main() {
// {:?}  — Debug trait (for developers, auto-derived)
// {:#?} — Pretty-printed Debug (indented, multi-line)
// {}    — Display trait (for users, must implement manually)

#[derive(Debug)] // Auto-generates Debug output
struct Point { x: f64, y: f64 }

let p = Point { x: 1.5, y: 2.7 };

println!("{:?}", p);   // Point { x: 1.5, y: 2.7 }   — compact debug
println!("{:#?}", p);  // Point {                     — pretty debug
                        //     x: 1.5,
                        //     y: 2.7,
                        // }
// println!("{}", p);  // ❌ ERROR: Point doesn't implement Display

// Implement Display for user-facing output:
use std::fmt;

impl fmt::Display for Point {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "({}, {})", self.x, self.y)
    }
}
println!("{}", p);    // (1.5, 2.7)  — user-friendly
}

// C# equivalent:
// {:?}  ≈ object.GetType().ToString() or reflection dump
// {}    ≈ object.ToString()
// In C# you override ToString(); in Rust you implement Display

Debug 和 Display 的分工特别值得早点建立起来。
一个是给开发者看的，重点是信息量；一个是给用户看的，重点是可读性。别把这俩混着用，不然后面日志和终端输出都容易长得很别扭。

Quick Reference
速查表

Type Casting and Conversions
类型转换与转换规则

C# has implicit conversions, explicit casts, and Convert.To*() helpers. Rust is much stricter: numeric conversions are always explicit, and safe conversions usually return Result.
C# 里有隐式转换、显式强转和 Convert.To*() 这套辅助方法；Rust 就收得紧得多。数值转换一律显式写，想要安全转换，通常就得接 Result。

Numeric Conversions
数值转换

// C# — implicit and explicit conversions
int small = 42;
long big = small;              // Implicit widening: OK
double d = small;              // Implicit widening: OK
int truncated = (int)3.14;     // Explicit narrowing: 3
byte b = (byte)300;            // Silent overflow: 44

// Safe conversion
if (int.TryParse("42", out int parsed)) { /* ... */ }

#![allow(unused)]
fn main() {
// Rust — ALL numeric conversions are explicit
let small: i32 = 42;
let big: i64 = small as i64;       // Widening: explicit with 'as'
let d: f64 = small as f64;         // Int to float: explicit
let truncated: i32 = 3.14_f64 as i32; // Narrowing: 3 (truncates)
let b: u8 = 300_u16 as u8;        // Overflow: wraps to 44 (like C# unchecked)

// Safe conversion with TryFrom
use std::convert::TryFrom;
let safe: Result<u8, _> = u8::try_from(300_u16); // Err — out of range
let ok: Result<u8, _>   = u8::try_from(42_u16);  // Ok(42)

// String parsing — returns Result, not bool + out param
let parsed: Result<i32, _> = "42".parse::<i32>();   // Ok(42)
let bad: Result<i32, _>    = "abc".parse::<i32>();  // Err(ParseIntError)

// With turbofish syntax:
let n = "42".parse::<f64>().unwrap(); // 42.0
}

Rust 这里的态度非常明确：别让转换偷偷发生。
这样写起来确实烦一点，但很多边界问题、溢出问题、类型误解问题，也就没那么容易悄悄溜进去了。

String Conversions
字符串转换

// C#
int n = 42;
string s = n.ToString();          // "42"
string formatted = $"{n:X}";
int back = int.Parse(s);          // 42 or throws
bool ok = int.TryParse(s, out int result);

#![allow(unused)]
fn main() {
// Rust — to_string() via Display, parse() via FromStr
let n: i32 = 42;
let s: String = n.to_string();            // "42" (uses Display trait)
let formatted = format!("{n:X}");         // "2A"
let back: i32 = s.parse().unwrap();       // 42 or panics
let result: Result<i32, _> = s.parse();   // Ok(42) — safe version

// &str ↔ String conversions (most common conversion in Rust)
let owned: String = "hello".to_string();    // &str → String
let owned2: String = String::from("hello"); // &str → String (equivalent)
let borrowed: &str = &owned;               // String → &str (free, just a borrow)
}

这里最常见、也最不该糊涂的转换，就是 &str 和 String 之间那一对。
前者变后者通常要分配和拷贝，后者借成前者基本是免费的。这个成本差异在写接口时很有意义。

Reference Conversions (No Inheritance Casting!)
引用转换（没有继承式强转）

// C# — upcasting and downcasting
Animal a = new Dog();              // Upcast (implicit)
Dog d = (Dog)a;                    // Downcast (explicit, can throw)
if (a is Dog dog) { /* ... */ }    // Safe downcast with pattern match

#![allow(unused)]
fn main() {
// Rust — No inheritance, no upcasting/downcasting
// Use trait objects for polymorphism:
let animal: Box<dyn Animal> = Box::new(Dog);

// "Downcasting" requires the Any trait (rarely needed):
use std::any::Any;
if let Some(dog) = animal_any.downcast_ref::<Dog>() {
    // Use dog
}
// In practice, use enums instead of downcasting:
enum Animal {
    Dog(Dog),
    Cat(Cat),
}
match animal {
    Animal::Dog(d) => { /* use d */ }
    Animal::Cat(c) => { /* use c */ }
}
}

Rust 没有那种遍地都是继承树的默认心智，所以也就没有整套向上转型、向下转型的日常操作。
真要做运行时类型判断，当然也有办法，但大多数时候更推荐用 enum 或 trait 设计把问题提前建模清楚。

Quick Reference
速查表

Comments and Documentation
注释与文档

Regular Comments
普通注释

// C# comments
// Single line comment
/* Multi-line
   comment */

/// <summary>
/// XML documentation comment
/// </summary>
/// <param name="name">The user's name</param>
/// <returns>A greeting string</returns>
public string Greet(string name)
{
    return $"Hello, {name}!";
}

#![allow(unused)]
fn main() {
// Rust comments
// Single line comment
/* Multi-line
   comment */

/// Documentation comment (like C# ///)
/// This function greets a user by name.
/// 
/// # Arguments
/// 
/// * `name` - The user's name as a string slice
/// 
/// # Returns
/// 
/// A `String` containing the greeting
/// 
/// # Examples
/// 
/// ```
/// let greeting = greet("Alice");
/// assert_eq!(greeting, "Hello, Alice!");
/// ```
pub fn greet(name: &str) -> String {
    format!("Hello, {}!", name)
}
}

Rust 文档注释最爽的地方，是它不仅是注释，还是工具链的一部分。
写好了以后能直接生成文档，示例代码还能进文档测试，这就比很多“只是写给人看、工具链不认”的注释系统强得多。

Documentation Generation
文档生成

# Generate documentation (like XML docs in C#)
cargo doc --open

# Run documentation tests
cargo test --doc

Exercises
练习

use std::sync::atomic::{AtomicU32, Ordering};

const ABSOLUTE_ZERO_C: f64 = -273.15;
static CONVERSION_COUNT: AtomicU32 = AtomicU32::new(0);

fn celsius_to_fahrenheit(c: f64) -> f64 {
    if c < ABSOLUTE_ZERO_C {
        return f64::NAN;
    }
    CONVERSION_COUNT.fetch_add(1, Ordering::Relaxed);
    c * 9.0 / 5.0 + 32.0
}

fn main() {
    let temp = "98.6";           // &str
    let temp: f64 = temp.parse().unwrap(); // shadow as f64
    let temp = celsius_to_fahrenheit(temp); // shadow as Fahrenheit
    println!("{temp:.1}°F");
    println!("Conversions: {}", CONVERSION_COUNT.load(Ordering::Relaxed));
}

True Immutability vs Record Illusions §§ZH§§ 真正的不可变性与 record 幻觉

True Immutability vs Record Illusions
真正的不可变性与 record 幻觉

What you’ll learn: Why C# record types aren’t truly immutable (mutable fields, reflection bypass), how Rust enforces real immutability at compile time, and when to use interior mutability patterns.
本章将学到什么： 为什么 C# 的 record 并不等于真正不可变，它仍然会被可变字段和反射绕开；Rust 又是如何在编译期强制执行真正的不可变性；以及什么时候才应该引入内部可变性模式。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

C# Records - Immutability Theater
C# record：看起来很美的“不可变表演”

// C# records look immutable but have escape hatches
public record Person(string Name, int Age, List<string> Hobbies);

var person = new Person("John", 30, new List<string> { "reading" });

// These all "look" like they create new instances:
var older = person with { Age = 31 };  // New record
var renamed = person with { Name = "Jonathan" };  // New record

// But the reference types are still mutable!
person.Hobbies.Add("gaming");  // Mutates the original!
Console.WriteLine(older.Hobbies.Count);  // 2 - older person affected!
Console.WriteLine(renamed.Hobbies.Count); // 2 - renamed person also affected!

// Init-only properties can still be set via reflection
typeof(Person).GetProperty("Age")?.SetValue(person, 25);

// Collection expressions help but don't solve the fundamental issue
public record BetterPerson(string Name, int Age, IReadOnlyList<string> Hobbies);

var betterPerson = new BetterPerson("Jane", 25, new List<string> { "painting" });
// Still mutable via casting: 
((List<string>)betterPerson.Hobbies).Add("hacking the system");

// Even "immutable" collections aren't truly immutable
using System.Collections.Immutable;
public record SafePerson(string Name, int Age, ImmutableList<string> Hobbies);
// This is better, but requires discipline and has performance overhead

C# 的 record 更像是“顶层字段更新体验很好”的语法糖，而不是全树不可变的语义保证。只要内部藏着 List<T>、可变引用对象，或者有人用反射硬掰，所谓“不可变”立刻露馅。
C# 的 record 更接近“表层不可变”。写起来像创建了新值，实际内部依然可能挂着一堆可变对象。只要结构里有 List<T>、可变引用成员，或者有人上反射，这个壳子马上就裂开。

Rust - True Immutability by Default
Rust：默认就给真正的不可变性

#![allow(unused)]
fn main() {
#[derive(Debug, Clone)]
struct Person {
    name: String,
    age: u32,
    hobbies: Vec<String>,
}

let person = Person {
    name: "John".to_string(),
    age: 30,
    hobbies: vec!["reading".to_string()],
};

// This simply won't compile:
// person.age = 31;  // ERROR: cannot assign to immutable field
// person.hobbies.push("gaming".to_string());  // ERROR: cannot borrow as mutable

// To modify, you must explicitly opt-in with 'mut':
let mut older_person = person.clone();
older_person.age = 31;  // Now it's clear this is mutation

// Or use functional update patterns:
let renamed = Person {
    name: "Jonathan".to_string(),
    ..person  // Copies other fields (move semantics apply)
};

// The original is guaranteed unchanged (until moved):
println!("{:?}", person.hobbies);  // Always ["reading"] - immutable

// Structural sharing with efficient immutable data structures
use std::rc::Rc;

#[derive(Debug, Clone)]
struct EfficientPerson {
    name: String,
    age: u32,
    hobbies: Rc<Vec<String>>,  // Shared, immutable reference
}

// Creating new versions shares data efficiently
let person1 = EfficientPerson {
    name: "Alice".to_string(),
    age: 30,
    hobbies: Rc::new(vec!["reading".to_string(), "cycling".to_string()]),
};

let person2 = EfficientPerson {
    name: "Bob".to_string(),
    age: 25,
    hobbies: Rc::clone(&person1.hobbies),  // Shared reference, no deep copy
};
}

Rust 这里就硬气得多。let person = ... 没有 mut，那整个值树都视为不可变，编译器一口咬死，谁也别想偷偷改。外层字段、里层 Vec、嵌套成员，统统遵守同一套规则。
Rust 的不可变性不是“团队约定”，而是编译器强制规则。只要变量不是 mut，修改字段不行，向 Vec 里 push 也不行，根本轮不到运行时再慢慢发现问题。

graph TD
    subgraph "C# Records - Shallow Immutability"
        CS_RECORD["record Person(...)"]
        CS_WITH["with expressions"]
        CS_SHALLOW["⚠️ Only top-level immutable"]
        CS_REF_MUT["❌ Reference types still mutable"]
        CS_REFLECTION["❌ Reflection can bypass"]
        CS_RUNTIME["❌ Runtime surprises"]
        CS_DISCIPLINE["😓 Requires team discipline"]
        
        CS_RECORD --> CS_WITH
        CS_WITH --> CS_SHALLOW
        CS_SHALLOW --> CS_REF_MUT
        CS_RECORD --> CS_REFLECTION
        CS_REF_MUT --> CS_RUNTIME
        CS_RUNTIME --> CS_DISCIPLINE
    end
    
    subgraph "Rust - True Immutability"
        RUST_STRUCT["struct Person { ... }"]
        RUST_DEFAULT["✅ Immutable by default"]
        RUST_COMPILE["✅ Compile-time enforcement"]
        RUST_MUT["🔒 Explicit 'mut' required"]
        RUST_MOVE["🔄 Move semantics"]
        RUST_ZERO["⚡ Zero runtime overhead"]
        RUST_SAFE["🛡️ Memory safe"]
        
        RUST_STRUCT --> RUST_DEFAULT
        RUST_DEFAULT --> RUST_COMPILE
        RUST_COMPILE --> RUST_MUT
        RUST_MUT --> RUST_MOVE
        RUST_MOVE --> RUST_ZERO
        RUST_ZERO --> RUST_SAFE
    end
    
    style CS_REF_MUT fill:#ffcdd2,color:#000
    style CS_REFLECTION fill:#ffcdd2,color:#000
    style CS_RUNTIME fill:#ffcdd2,color:#000
    style RUST_COMPILE fill:#c8e6c9,color:#000
    style RUST_ZERO fill:#c8e6c9,color:#000
    style RUST_SAFE fill:#c8e6c9,color:#000

上面这张图说白了就一句：C# record 主要改善的是写法体验，Rust 改的是语义地基。一个靠自觉兜底，一个靠类型系统和借用规则兜底，差别就在这。
也正因为如此，Rust 的“不可变”没有额外运行时成本。它不是靠包装器、代理对象、特殊集合堆出来的，而是直接写进语言规则里。

Interior Mutability: The Escape Hatch You Use on Purpose
内部可变性：确实需要时再主动开门

Rust 也不是死板到一点变化都不给。只是它要求“要改，就明牌”。例如 Cell<T>、RefCell<T>、Mutex<T> 这些模式，都是把“这里存在受控可变性”显式写出来。
这和 C# record 那种默认看着像不可变、实际暗地里还能改，是完全相反的思路。Rust 是先封死，再按需开口子。

常见选择可以这样理解：
常见工具可以这样记：

• Cell<T> for small Copy values you want to update behind an immutable reference.
  Cell<T>：适合小型 Copy 值，需要在不可变引用背后更新时使用。
• RefCell<T> when mutation is single-threaded and borrow rules must be checked at runtime.
  RefCell<T>：适合单线程场景，把借用检查延后到运行时。
• Mutex<T> or RwLock<T> when shared mutation must be synchronized across threads.
  Mutex<T> 或 RwLock<T>：适合多线程共享可变状态，需要同步保护时使用。

经验上，普通业务数据先按“真正不可变”设计，实在有缓存、惰性初始化、共享计数之类的硬需求，再挑一种内部可变性工具补进去。
先把默认方案站稳，再开例外口子，代码会干净得多，也更容易审查。

Exercises
练习

public record Config(string Host, int Port, List<string> AllowedOrigins);

var config = new Config("localhost", 8080, new List<string> { "example.com" });
// "Immutable" record... but:
config.AllowedOrigins.Add("evil.com"); // Compiles! List is mutable.

#[derive(Debug, Clone)]
struct Config {
    host: String,
    port: u16,
    allowed_origins: Vec<String>,
}

impl Config {
    fn with_host(&self, host: impl Into<String>) -> Self {
        Config {
            host: host.into(),
            ..self.clone()
        }
    }
}

fn main() {
    let config = Config {
        host: "localhost".into(),
        port: 8080,
        allowed_origins: vec!["example.com".into()],
    };

    // config.allowed_origins.push("evil.com".into());
    // ❌ ERROR: cannot borrow `config.allowed_origins` as mutable

    let production = config.with_host("prod.example.com");
    println!("Dev: {:?}", config);       // original unchanged
    println!("Prod: {:?}", production);  // new copy with different host
}

Control Flow §§ZH§§ 控制流

Functions vs Methods
函数与方法

What you’ll learn: Functions and methods in Rust vs C#, the critical distinction between expressions and statements, if/match/loop/while/for syntax, and how Rust’s expression-oriented design eliminates the need for ternary operators.
本章将学到什么： Rust 和 C# 在函数、方法上的区别，表达式与语句这组极关键概念，if / match / loop / while / for 的基本语法，以及为什么 Rust 的表达式导向设计让三元运算符变得没有必要。

Difficulty: 🟢 Beginner
难度： 🟢 入门

C# Function Declaration
C# 的函数声明方式

// C# - Methods in classes
public class Calculator
{
    // Instance method
    public int Add(int a, int b)
    {
        return a + b;
    }
    
    // Static method
    public static int Multiply(int a, int b)
    {
        return a * b;
    }
    
    // Method with ref parameter
    public void Increment(ref int value)
    {
        value++;
    }
}

在 C# 里，大部分行为都挂在类上。实例方法、静态方法、ref 参数，这些东西对 C# 开发者来说已经是肌肉记忆。
到了 Rust，这套结构会被拆得更开一些：既有独立函数，也有绑定在 impl 块里的方法。

Rust Function Declaration
Rust 的函数声明方式

// Rust - Standalone functions
fn add(a: i32, b: i32) -> i32 {
    a + b  // No 'return' needed for final expression
}

fn multiply(a: i32, b: i32) -> i32 {
    return a * b;  // Explicit return is also fine
}

// Function with mutable reference
fn increment(value: &mut i32) {
    *value += 1;
}

fn main() {
    let result = add(5, 3);
    println!("5 + 3 = {}", result);
    
    let mut x = 10;
    increment(&mut x);
    println!("After increment: {}", x);
}

Rust 里独立函数是一等公民，不需要先塞进类里才能存在。方法则放在 impl TypeName 里。
另外，&mut i32 这种写法也值得注意，它和 C# 的 ref 有一点像，但本质上更接近“显式可变借用”。

Expression vs Statement (Important!)
表达式与语句的区别，这个很重要

graph LR
    subgraph "C# — Statements"
        CS1["if (cond)"] --> CS2["return 42;"]
        CS1 --> CS3["return 0;"]
        CS2 --> CS4["Value exits via return"]
        CS3 --> CS4
    end
    subgraph "Rust — Expressions"
        RS1["if cond"] --> RS2["42  (no semicolon)"]
        RS1 --> RS3["0  (no semicolon)"]
        RS2 --> RS4["Block IS the value"]
        RS3 --> RS4
    end

    style CS4 fill:#bbdefb,color:#000
    style RS4 fill:#c8e6c9,color:#000

// C# - Statements vs expressions
public int GetValue()
{
    if (condition)
    {
        return 42;  // Statement
    }
    return 0;       // Statement
}

#![allow(unused)]
fn main() {
// Rust - Everything can be an expression
fn get_value(condition: bool) -> i32 {
    if condition {
        42  // Expression (no semicolon)
    } else {
        0   // Expression (no semicolon)
    }
    // The if-else block itself is an expression that returns a value
}

// Or even simpler
fn get_value_ternary(condition: bool) -> i32 {
    if condition { 42 } else { 0 }
}
}

这就是 Rust 入门阶段最容易突然“咯噔”一下的地方。if 在 Rust 里不只是控制流程，它还能直接产出值。
也正因为如此，Rust 根本不需要单独再设计一个三元运算符。if ... else ... 自己就是表达式，而且通常更清楚。

Function Parameters and Return Types
函数参数与返回值

// No parameters, no return value (returns unit type ())
fn say_hello() {
    println!("Hello!");
}

// Multiple parameters
fn greet(name: &str, age: u32) {
    println!("{} is {} years old", name, age);
}

// Multiple return values using tuple
fn divide_and_remainder(dividend: i32, divisor: i32) -> (i32, i32) {
    (dividend / divisor, dividend % divisor)
}

fn main() {
    let (quotient, remainder) = divide_and_remainder(10, 3);
    println!("10 ÷ 3 = {} remainder {}", quotient, remainder);
}

Rust 在返回多个值时不会先催着去定义个类或者 struct，元组就能先顶上。
当然，如果这些返回值有明确业务语义，后续还是更推荐换成具名结构体，代码可读性会更好。

Control Flow Basics
控制流基础

Conditional Statements
条件语句

// C# if statements
int x = 5;
if (x > 10)
{
    Console.WriteLine("Big number");
}
else if (x > 5)
{
    Console.WriteLine("Medium number");
}
else
{
    Console.WriteLine("Small number");
}

// C# ternary operator
string message = x > 10 ? "Big" : "Small";

#![allow(unused)]
fn main() {
// Rust if expressions
let x = 5;
if x > 10 {
    println!("Big number");
} else if x > 5 {
    println!("Medium number");
} else {
    println!("Small number");
}

// Rust if as expression (like ternary)
let message = if x > 10 { "Big" } else { "Small" };

// Multiple conditions
let message = if x > 10 {
    "Big"
} else if x > 5 {
    "Medium"
} else {
    "Small"
};
}

这里能明显看出 Rust 的表达式导向风格。if 既能控制流程，也能直接生成结果。
只要每个分支返回的类型一致，就能把它赋值给变量，写法通常比三元表达式更平滑。

Loops
循环

// C# loops
// For loop
for (int i = 0; i < 5; i++)
{
    Console.WriteLine(i);
}

// Foreach loop
var numbers = new[] { 1, 2, 3, 4, 5 };
foreach (var num in numbers)
{
    Console.WriteLine(num);
}

// While loop
int count = 0;
while (count < 3)
{
    Console.WriteLine(count);
    count++;
}

#![allow(unused)]
fn main() {
// Rust loops
// Range-based for loop
for i in 0..5 {  // 0 to 4 (exclusive end)
    println!("{}", i);
}

// Iterate over collection
let numbers = vec![1, 2, 3, 4, 5];
for num in numbers {  // Takes ownership
    println!("{}", num);
}

// Iterate over references (more common)
let numbers = vec![1, 2, 3, 4, 5];
for num in &numbers {  // Borrows elements
    println!("{}", num);
}

// While loop
let mut count = 0;
while count < 3 {
    println!("{}", count);
    count += 1;
}

// Infinite loop with break
let mut counter = 0;
loop {
    if counter >= 3 {
        break;
    }
    println!("{}", counter);
    counter += 1;
}
}

Rust 的 for 背后其实是基于迭代器的，这和 C# foreach 的精神很接近。但要特别注意所有权语义：for num in numbers 会消耗集合，for num in &numbers 才是借用遍历。
这也是 Rust 新手常见失误点之一，循环一跑完，发现原集合被 move 走了，然后一脸问号。

Loop Control
循环控制

// C# loop control
for (int i = 0; i < 10; i++)
{
    if (i == 3) continue;
    if (i == 7) break;
    Console.WriteLine(i);
}

#![allow(unused)]
fn main() {
// Rust loop control
for i in 0..10 {
    if i == 3 { continue; }
    if i == 7 { break; }
    println!("{}", i);
}

// Loop labels (for nested loops)
'outer: for i in 0..3 {
    'inner: for j in 0..3 {
        if i == 1 && j == 1 {
            break 'outer;  // Break out of outer loop
        }
        println!("i: {}, j: {}", i, j);
    }
}
}

循环标签是 Rust 里一个很实用但很多语言不常见的东西。嵌套循环里想直接跳出外层，不用手搓布尔标志位，也不用额外包函数，给循环贴个标签就行。
写复杂状态机或搜索逻辑时，这招挺省心。

// C# — convert this to Rust
public static double Convert(double value, string from, string to)
{
    double celsius = from switch
    {
        "F" => (value - 32.0) * 5.0 / 9.0,
        "K" => value - 273.15,
        "C" => value,
        _ => throw new ArgumentException($"Unknown unit: {from}")
    };
    return to switch
    {
        "F" => celsius * 9.0 / 5.0 + 32.0,
        "K" => celsius + 273.15,
        "C" => celsius,
        _ => throw new ArgumentException($"Unknown unit: {to}")
    };
}

#[derive(Debug, Clone, Copy)]
enum TempUnit { Celsius, Fahrenheit, Kelvin }

fn parse_unit(s: &str) -> Result<TempUnit, String> {
    match s {
        "C" => Ok(TempUnit::Celsius),
        "F" => Ok(TempUnit::Fahrenheit),
        "K" => Ok(TempUnit::Kelvin),
        _   => Err(format!("Unknown unit: {s}")),
    }
}

fn convert(value: f64, from: TempUnit, to: TempUnit) -> f64 {
    let celsius = match from {
        TempUnit::Fahrenheit => (value - 32.0) * 5.0 / 9.0,
        TempUnit::Kelvin     => value - 273.15,
        TempUnit::Celsius    => value,
    };
    match to {
        TempUnit::Fahrenheit => celsius * 9.0 / 5.0 + 32.0,
        TempUnit::Kelvin     => celsius + 273.15,
        TempUnit::Celsius    => celsius,
    }
}

fn main() -> Result<(), String> {
    let from = parse_unit("F")?;
    let to   = parse_unit("C")?;
    println!("212°F = {:.1}°C", convert(212.0, from, to));
    Ok(())
}

Data Structures and Collections §§ZH§§ 数据结构与集合

Tuples and Destructuring
元组与解构

What you’ll learn: Rust tuples compared with C# ValueTuple, arrays and slices, structs versus classes, the newtype pattern for zero-cost domain safety, and destructuring syntax.
本章将学到什么： 对照理解 Rust 元组和 C# ValueTuple，理解数组、切片、struct 与 class 的差异，掌握 newtype 模式怎样以零成本提供领域类型安全，并熟悉解构语法。

Difficulty: 🟢 Beginner
难度： 🟢 入门

C# has ValueTuple, and Rust tuples feel familiar at first glance, but Rust pushes tuples and destructuring much deeper into the language.
C# 从 ValueTuple 开始，已经让元组变得比较顺手；Rust 则把元组和解构进一步揉进了语言核心，所以后面会反复遇到它们。

C# Tuples
C# 元组

// C# ValueTuple (C# 7+)
var point = (10, 20);                         // (int, int)
var named = (X: 10, Y: 20);                   // Named elements
Console.WriteLine($"{named.X}, {named.Y}");

// Tuple as return type
public (int Quotient, int Remainder) Divide(int a, int b)
{
    return (a / b, a % b);
}

var (q, r) = Divide(10, 3);    // Deconstruction
Console.WriteLine($"{q} remainder {r}");

// Discards
var (_, remainder) = Divide(10, 3);  // Ignore quotient

Rust Tuples
Rust 元组

#![allow(unused)]
fn main() {
// Rust tuples — immutable by default, no named elements
let point = (10, 20);                // (i32, i32)
let point3d: (f64, f64, f64) = (1.0, 2.0, 3.0);

// Access by index (0-based)
println!("x={}, y={}", point.0, point.1);

// Tuple as return type
fn divide(a: i32, b: i32) -> (i32, i32) {
    (a / b, a % b)
}

let (q, r) = divide(10, 3);       // Destructuring
println!("{q} remainder {r}");

// Discards with _
let (_, remainder) = divide(10, 3);

// Unit type () — the "empty tuple" (like C# void)
fn greet() {          // implicit return type is ()
    println!("hi");
}
}

Rust 元组最大的区别，就是它没给字段名留位置。
所以只要元组开始承载“有语义的业务字段”，就该警觉是不是该换成 struct 了。元组适合临时组合，struct 适合长期表达。

Key Differences
关键差异

Tuple Structs (Newtypes)
元组结构体与 Newtype

#![allow(unused)]
fn main() {
// When a plain tuple isn't descriptive enough, use a tuple struct:
struct Meters(f64);     // Single-field "newtype" wrapper
struct Celsius(f64);
struct Fahrenheit(f64);

// The compiler treats these as DIFFERENT types:
let distance = Meters(100.0);
let temp = Celsius(36.6);
// distance == temp;  // ❌ ERROR: can't compare Meters with Celsius

// Newtype pattern prevents unit-confusion bugs at compile time!
// In C# you'd need a full class/struct for the same safety.
}

// C# equivalent requires more ceremony:
public readonly record struct Meters(double Value);
public readonly record struct Celsius(double Value);
// Not interchangeable, but records add overhead vs Rust's zero-cost newtypes

newtype 是 Rust 做领域建模时非常锋利的一把刀。
它看起来只是“外面套一层壳”，实际上是在编译期把不同语义强行分开，避免把米、摄氏度、用户 ID、端口号这类东西混用。

The Newtype Pattern in Depth: Domain Modeling with Zero Cost
进一步理解 Newtype：零成本的领域建模

Newtypes do much more than prevent unit confusion. They are one of Rust’s primary tools for encoding business rules into types instead of repeating runtime validation everywhere.
Newtype 不只是防止单位混用，它更大的价值在于：把业务规则直接编码进类型里，而不是把校验逻辑散落到每一个调用点。

C# Validation Approach: Runtime Guards
C# 常见做法：运行时 Guard

// C# — validation happens at runtime, every time
public class UserService
{
    public User CreateUser(string email, int age)
    {
        if (string.IsNullOrWhiteSpace(email) || !email.Contains('@'))
            throw new ArgumentException("Invalid email");
        if (age < 0 || age > 150)
            throw new ArgumentException("Invalid age");

        return new User { Email = email, Age = age };
    }

    public void SendEmail(string email)
    {
        // Must re-validate — or trust the caller?
        if (!email.Contains('@')) throw new ArgumentException("Invalid email");
        // ...
    }
}

Rust Newtype Approach: Compile-Time Proof
Rust 的 Newtype 做法：编译期证明

#![allow(unused)]
fn main() {
/// A validated email address — the type itself IS the proof of validity.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Email(String);

impl Email {
    /// The ONLY way to create an Email — validation happens once at construction.
    pub fn new(raw: &str) -> Result<Self, &'static str> {
        if raw.contains('@') && raw.len() > 3 {
            Ok(Email(raw.to_lowercase()))
        } else {
            Err("invalid email format")
        }
    }

    /// Safe access to the inner value
    pub fn as_str(&self) -> &str { &self.0 }
}

/// A validated age — impossible to create an invalid one.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct Age(u8);

impl Age {
    pub fn new(raw: u8) -> Result<Self, &'static str> {
        if raw <= 150 { Ok(Age(raw)) } else { Err("age out of range") }
    }
    pub fn value(&self) -> u8 { self.0 }
}

// Now functions take PROVEN types — no re-validation needed!
fn create_user(email: Email, age: Age) -> User {
    // email is GUARANTEED valid — it's a type invariant
    User { email, age }
}

fn send_email(to: &Email) {
    // No validation needed — Email type proves validity
    println!("Sending to: {}", to.as_str());
}
}

Common Newtype Uses for C# Developers
C# 开发者常见的 Newtype 用法

#![allow(unused)]
fn main() {
// Zero-cost: newtypes compile to the same assembly as the inner type.
// This Rust code:
struct UserId(u64);
fn lookup(id: UserId) -> Option<User> { /* ... */ }

// Generates the SAME machine code as:
fn lookup(id: u64) -> Option<User> { /* ... */ }
// But with full type safety at compile time!
}

这就是 Rust 喜欢把正确性做进类型里的味道。
不是靠“记得调用 Validate()”，而是靠“没有合法类型就根本过不了接口”。这两者的可靠度差得不是一点半点。

Arrays and Slices
数组与切片

Understanding arrays, slices, and vectors separately is crucial. They solve different problems and Rust keeps the distinctions explicit.
数组、切片、向量这三样东西一定要拆开理解。它们解决的是不同层次的问题，而 Rust 正是故意把这种区别写得很明白。

C# Arrays
C# 数组

// C# arrays
int[] numbers = new int[5];         // Fixed size, heap allocated
int[] initialized = { 1, 2, 3, 4, 5 }; // Array literal

// Access
numbers[0] = 10;
int first = numbers[0];

// Length
int length = numbers.Length;

// Array as parameter (reference type)
void ProcessArray(int[] array)
{
    array[0] = 99;  // Modifies original
}

Rust Arrays, Slices, and Vectors
Rust 的数组、切片与向量

#![allow(unused)]
fn main() {
// 1. Arrays - Fixed size, stack allocated
let numbers: [i32; 5] = [1, 2, 3, 4, 5];  // Type: [i32; 5]
let zeros = [0; 10];                       // 10 zeros

// Access
let first = numbers[0];
// numbers[0] = 10;  // ❌ Error: arrays are immutable by default

let mut mut_array = [1, 2, 3, 4, 5];
mut_array[0] = 10;  // ✅ Works with mut

// 2. Slices - Views into arrays or vectors
let slice: &[i32] = &numbers[1..4];  // Elements 1, 2, 3
let all_slice: &[i32] = &numbers;    // Entire array as slice

// 3. Vectors - Dynamic size, heap allocated (covered earlier)
let mut vec = vec![1, 2, 3, 4, 5];
vec.push(6);  // Can grow
}

切片 &[T] 这玩意一定要尽快熟。
它不是独立拥有数据的集合，而只是“对一段连续元素的借用视图”。很多更通用、更优雅的函数签名，最后都会落在切片上。

Slices as Function Parameters
把切片作为函数参数

// C# - Method that works with arrays
public void ProcessNumbers(int[] numbers)
{
    for (int i = 0; i < numbers.Length; i++)
    {
        Console.WriteLine(numbers[i]);
    }
}

// Works with arrays only
ProcessNumbers(new int[] { 1, 2, 3 });

// Rust - Function that works with any sequence
fn process_numbers(numbers: &[i32]) {  // Slice parameter
    for (i, num) in numbers.iter().enumerate() {
        println!("Index {}: {}", i, num);
    }
}

fn main() {
    let array = [1, 2, 3, 4, 5];
    let vec = vec![1, 2, 3, 4, 5];
    
    // Same function works with both!
    process_numbers(&array);      // Array as slice
    process_numbers(&vec);        // Vector as slice
    process_numbers(&vec[1..4]);  // Partial slice
}

这就是为什么 Rust 社区老爱说“参数尽量收切片”。
因为一旦签成 &[T]，数组、向量、子区间都能复用；签死成 Vec<T> 反而会把接口绑窄，还平白无故多出所有权要求。

String Slices (&str) Revisited
再次回到字符串切片 &str

#![allow(unused)]
fn main() {
// String and &str relationship
fn string_slice_example() {
    let owned = String::from("Hello, World!");
    let slice: &str = &owned[0..5];      // "Hello"
    let slice2: &str = &owned[7..];      // "World!"
    
    println!("{}", slice);   // "Hello"
    println!("{}", slice2);  // "World!"
    
    // Function that accepts any string type
    print_string("String literal");      // &str
    print_string(&owned);               // String as &str
    print_string(slice);                // &str slice
}

fn print_string(s: &str) {
    println!("{}", s);
}
}

字符串切片本质上也是切片思想在文本上的体现。
所以前面搞懂了普通切片，再回头看 &str 就会舒服很多：它不是神秘特例，只是 UTF-8 文本上的借用视图。

Structs vs Classes
Struct 与 Class 对照

Structs in Rust fill many of the roles that classes cover in C#, but the storage model and method system differ quite a bit.
Rust 的 struct 能覆盖 C# class 很多职责，但它们在存储方式、所有权和方法组织上差异不小，别简单拿“Rust 的 struct 就是 C# 的 class”去硬套。

graph TD
    subgraph "C# Class (Heap)"
        CObj["Object Header<br/>+ vtable ptr"] --> CFields["Name: string ref<br/>Age: int<br/>Hobbies: List ref"]
        CFields --> CHeap1["#quot;Alice#quot; on heap"]
        CFields --> CHeap2["List&lt;string&gt; on heap"]
    end
    subgraph "Rust Struct (Stack)"
        RFields["name: String<br/>ptr | len | cap<br/>age: i32<br/>hobbies: Vec<br/>ptr | len | cap"]
        RFields --> RHeap1["#quot;Alice#quot; heap buffer"]
        RFields --> RHeap2["Vec heap buffer"]
    end

    style CObj fill:#bbdefb,color:#000
    style RFields fill:#c8e6c9,color:#000

Key insight: C# classes always live on the heap behind references. Rust structs live on the stack by default, while dynamically-sized internals such as String buffers or Vec contents live on the heap.
关键理解： C# 的 class 一般总是在堆上，再通过引用访问；Rust 的 struct 默认值本体在栈上，只有像 String、Vec 这种内部动态数据缓冲区才放到堆里。

C# Class Definition
C# 类定义

// C# class with properties and methods
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public List<string> Hobbies { get; set; }
    
    public Person(string name, int age)
    {
        Name = name;
        Age = age;
        Hobbies = new List<string>();
    }
    
    public void AddHobby(string hobby)
    {
        Hobbies.Add(hobby);
    }
    
    public string GetInfo()
    {
        return $"{Name} is {Age} years old";
    }
}

Rust Struct Definition
Rust Struct 定义

#![allow(unused)]
fn main() {
// Rust struct with associated functions and methods
#[derive(Debug)]  // Automatically implement Debug trait
pub struct Person {
    pub name: String,    // Public field
    pub age: u32,        // Public field
    hobbies: Vec<String>, // Private field (no pub)
}

impl Person {
    // Associated function (like static method)
    pub fn new(name: String, age: u32) -> Person {
        Person {
            name,
            age,
            hobbies: Vec::new(),
        }
    }
    
    // Method (takes &self, &mut self, or self)
    pub fn add_hobby(&mut self, hobby: String) {
        self.hobbies.push(hobby);
    }
    
    // Method that borrows immutably
    pub fn get_info(&self) -> String {
        format!("{} is {} years old", self.name, self.age)
    }
    
    // Getter for private field
    pub fn hobbies(&self) -> &Vec<String> {
        &self.hobbies
    }
}
}

Rust struct 没有那种“默认 public 属性 + 默认 getter/setter”的味道。
字段是否公开、方法是否允许修改内部状态，都得明确写出来。代码会更啰嗦一点，但边界也会更清楚。

Creating and Using Instances
创建并使用实例

// C# object creation and usage
var person = new Person("Alice", 30);
person.AddHobby("Reading");
person.AddHobby("Swimming");

Console.WriteLine(person.GetInfo());
Console.WriteLine($"Hobbies: {string.Join(", ", person.Hobbies)}");

// Modify properties directly
person.Age = 31;

#![allow(unused)]
fn main() {
// Rust struct creation and usage
let mut person = Person::new("Alice".to_string(), 30);
person.add_hobby("Reading".to_string());
person.add_hobby("Swimming".to_string());

println!("{}", person.get_info());
println!("Hobbies: {:?}", person.hobbies());

// Modify public fields directly
person.age = 31;

// Debug print the entire struct
println!("{:?}", person);
}

Struct Initialization Patterns
Struct 初始化方式

// C# object initialization
var person = new Person("Bob", 25)
{
    Hobbies = new List<string> { "Gaming", "Coding" }
};

// Anonymous types
var anonymous = new { Name = "Charlie", Age = 35 };

#![allow(unused)]
fn main() {
// Rust struct initialization
let person = Person {
    name: "Bob".to_string(),
    age: 25,
    hobbies: vec!["Gaming".to_string(), "Coding".to_string()],
};

// Struct update syntax (like object spread)
let older_person = Person {
    age: 26,
    ..person  // Use remaining fields from person (moves person!)
};

// Tuple structs (like anonymous types)
#[derive(Debug)]
struct Point(i32, i32);

let point = Point(10, 20);
println!("Point: ({}, {})", point.0, point.1);
}

结构体更新语法 ..person 很方便，但它会 move 剩余字段。
这东西好用归好用，脑子里一定得记住：一旦源值里有非 Copy 字段，被搬走以后原变量通常就不能再用。

Methods and Associated Functions
方法与关联函数

Understanding the difference between methods and associated functions is essential because Rust uses receiver types explicitly.
方法和关联函数的区别一定要搞清楚，因为 Rust 会把“这个函数到底如何接收实例”写在签名里，不给模糊空间。

C# Method Types
C# 里的方法类型

public class Calculator
{
    private int memory = 0;
    
    // Instance method
    public int Add(int a, int b)
    {
        return a + b;
    }
    
    // Instance method that uses state
    public void StoreInMemory(int value)
    {
        memory = value;
    }
    
    // Static method
    public static int Multiply(int a, int b)
    {
        return a * b;
    }
    
    // Static factory method
    public static Calculator CreateWithMemory(int initialMemory)
    {
        var calc = new Calculator();
        calc.memory = initialMemory;
        return calc;
    }
}

Rust Method Types
Rust 里的方法类型

#[derive(Debug)]
pub struct Calculator {
    memory: i32,
}

impl Calculator {
    // Associated function (like static method) - no self parameter
    pub fn new() -> Calculator {
        Calculator { memory: 0 }
    }
    
    // Associated function with parameters
    pub fn with_memory(initial_memory: i32) -> Calculator {
        Calculator { memory: initial_memory }
    }
    
    // Method that borrows immutably (&self)
    pub fn add(&self, a: i32, b: i32) -> i32 {
        a + b
    }
    
    // Method that borrows mutably (&mut self)
    pub fn store_in_memory(&mut self, value: i32) {
        self.memory = value;
    }
    
    // Method that takes ownership (self)
    pub fn into_memory(self) -> i32 {
        self.memory  // Calculator is consumed
    }
    
    // Getter method
    pub fn memory(&self) -> i32 {
        self.memory
    }
}

fn main() {
    // Associated functions called with ::
    let mut calc = Calculator::new();
    let calc2 = Calculator::with_memory(42);
    
    // Methods called with .
    let result = calc.add(5, 3);
    calc.store_in_memory(result);
    
    println!("Memory: {}", calc.memory());
    
    // Consuming method
    let memory_value = calc.into_memory();  // calc is no longer usable
    println!("Final memory: {}", memory_value);
}

Rust 把接收者写得很实在：&self、&mut self、self。
只要看见签名，就能知道这个方法是只读、可改，还是会直接把整个对象吃掉。这种清晰度后面会越来越值钱。

Method Receiver Types Explained
方法接收者类型说明

#![allow(unused)]
fn main() {
impl Person {
    // &self - Immutable borrow (most common)
    // Use when you only need to read the data
    pub fn get_name(&self) -> &str {
        &self.name
    }
    
    // &mut self - Mutable borrow
    // Use when you need to modify the data
    pub fn set_name(&mut self, name: String) {
        self.name = name;
    }
    
    // self - Take ownership (less common)
    // Use when you want to consume the struct
    pub fn consume(self) -> String {
        self.name  // Person is moved, no longer accessible
    }
}

fn method_examples() {
    let mut person = Person::new("Alice".to_string(), 30);
    
    // Immutable borrow
    let name = person.get_name();  // person can still be used
    println!("Name: {}", name);
    
    // Mutable borrow
    person.set_name("Alice Smith".to_string());  // person can still be used
    
    // Taking ownership
    let final_name = person.consume();  // person is no longer usable
    println!("Final name: {}", final_name);
}
}

一旦把这三种 receiver 想成“看一下”“改一下”“拿走整个对象”，很多 API 设计会自然很多。
这套方式虽然比 C# 更显式，但恰恰因为显式，调用方更不容易踩坑。

Exercises
练习

fn rolling_average(data: &[f64], window: usize) -> Vec<f64> {
    // Your implementation here
    todo!()
}

fn main() {
    let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
    let avgs = rolling_average(&data, 3);
    println!("{avgs:?}"); // [2.0, 3.0, 4.0]
}

fn rolling_average(data: &[f64], window: usize) -> Vec<f64> {
    data.windows(window)
        .map(|w| w.iter().sum::<f64>() / w.len() as f64)
        .collect()
}

fn main() {
    let data = vec![1.0, 2.0, 3.0, 4.0, 5.0];
    let avgs = rolling_average(&data, 3);
    assert_eq!(avgs, vec![2.0, 3.0, 4.0]);
    println!("{avgs:?}");
}

#[derive(Debug, PartialEq)]
enum PhoneType { Mobile, Home, Work }

#[derive(Debug)]
struct Contact {
    name: String,
    phones: Vec<(PhoneType, String)>,
}

impl Contact {
    fn new(name: impl Into<String>) -> Self {
        Contact { name: name.into(), phones: Vec::new() }
    }

    fn add_phone(&mut self, kind: PhoneType, number: impl Into<String>) {
        self.phones.push((kind, number.into()));
    }

    fn mobile_numbers(&self) -> Vec<&str> {
        self.phones
            .iter()
            .filter(|(kind, _)| *kind == PhoneType::Mobile)
            .map(|(_, num)| num.as_str())
            .collect()
    }
}

fn main() {
    let mut alice = Contact::new("Alice");
    alice.add_phone(PhoneType::Mobile, "+1-555-0100");
    alice.add_phone(PhoneType::Work, "+1-555-0200");
    alice.add_phone(PhoneType::Mobile, "+1-555-0101");

    println!("{}'s mobile numbers: {:?}", alice.name, alice.mobile_numbers());
}

Constructor Patterns §§ZH§§ 构造器模式

Constructor Patterns
构造器模式

What you’ll learn: How to create Rust structs without traditional constructors — new() conventions, the Default trait, factory methods, and the builder pattern for complex initialization.
本章将学到什么： Rust 在没有传统类构造函数的前提下，通常如何创建结构体，包括 new() 约定、Default trait、工厂方法，以及复杂初始化常用的 builder 模式。

Difficulty: 🟢 Beginner
难度： 🟢 入门

C# Constructor Patterns
C# 里的构造器模式

public class Configuration
{
    public string DatabaseUrl { get; set; }
    public int MaxConnections { get; set; }
    public bool EnableLogging { get; set; }
    
    // Default constructor
    public Configuration()
    {
        DatabaseUrl = "localhost";
        MaxConnections = 10;
        EnableLogging = false;
    }
    
    // Parameterized constructor
    public Configuration(string databaseUrl, int maxConnections)
    {
        DatabaseUrl = databaseUrl;
        MaxConnections = maxConnections;
        EnableLogging = false;
    }
    
    // Factory method
    public static Configuration ForProduction()
    {
        return new Configuration("prod.db.server", 100)
        {
            EnableLogging = true
        };
    }
}

C# 的写法很顺：默认构造器、带参构造器、静态工厂，全都围着类构造函数转。很多开发者刚到 Rust 时，最先懵的一下就是“诶，构造函数呢？”
答案是 Rust 压根没有语言层面的专用构造函数语法，但这不代表它没有成熟模式，反而是把选择权交给了类型本身。

Rust Constructor Patterns
Rust 的构造器模式

#[derive(Debug)]
pub struct Configuration {
    pub database_url: String,
    pub max_connections: u32,
    pub enable_logging: bool,
}

impl Configuration {
    // Default constructor
    pub fn new() -> Configuration {
        Configuration {
            database_url: "localhost".to_string(),
            max_connections: 10,
            enable_logging: false,
        }
    }
    
    // Parameterized constructor
    pub fn with_database(database_url: String, max_connections: u32) -> Configuration {
        Configuration {
            database_url,
            max_connections,
            enable_logging: false,
        }
    }
    
    // Factory method
    pub fn for_production() -> Configuration {
        Configuration {
            database_url: "prod.db.server".to_string(),
            max_connections: 100,
            enable_logging: true,
        }
    }
    
    // Builder pattern method
    pub fn enable_logging(mut self) -> Configuration {
        self.enable_logging = true;
        self  // Return self for chaining
    }
    
    pub fn max_connections(mut self, count: u32) -> Configuration {
        self.max_connections = count;
        self
    }
}

// Default trait implementation
impl Default for Configuration {
    fn default() -> Self {
        Self::new()
    }
}

fn main() {
    // Different construction patterns
    let config1 = Configuration::new();
    let config2 = Configuration::with_database("localhost:5432".to_string(), 20);
    let config3 = Configuration::for_production();
    
    // Builder pattern
    let config4 = Configuration::new()
        .enable_logging()
        .max_connections(50);
    
    // Using Default trait
    let config5 = Configuration::default();
    
    println!("{:?}", config4);
}

Rust 的常见套路，是在 impl 里自己定义 new()、with_xxx()、for_production() 这种关联函数。它们看着像构造器，实际上只是普通关联函数，但完全够用，而且命名更自由。
也就是说，Rust 并不是“没有构造方案”，而是没有把构造强塞进语言语法里，反而让接口设计更明确。

Default Is More Important Than It Looks
Default 的地位比表面看起来更重要

很多 C# 开发者会下意识去找“无参构造函数”的平替。Rust 里更常见的答案是 Default。
只要类型有一个合理的默认值集合，实现 Default 通常比单独搞一堆“空构造器”更顺手，因为生态里很多泛型组件也会优先认这个 trait。

如果默认值语义明确，用 Configuration::default() 往往比 Configuration::new() 更能表达意图。反过来，如果默认值并不天然成立，而是某种具体场景的初始化，那继续保留 new() 或命名工厂方法会更清楚。
别把所有初始化都一股脑塞进 Default，那样也容易把接口搞脏。

Builder Pattern Implementation
Builder 模式实现

// More complex builder pattern
#[derive(Debug)]
pub struct DatabaseConfig {
    host: String,
    port: u16,
    username: String,
    password: Option<String>,
    ssl_enabled: bool,
    timeout_seconds: u64,
}

pub struct DatabaseConfigBuilder {
    host: Option<String>,
    port: Option<u16>,
    username: Option<String>,
    password: Option<String>,
    ssl_enabled: bool,
    timeout_seconds: u64,
}

impl DatabaseConfigBuilder {
    pub fn new() -> Self {
        DatabaseConfigBuilder {
            host: None,
            port: None,
            username: None,
            password: None,
            ssl_enabled: false,
            timeout_seconds: 30,
        }
    }
    
    pub fn host(mut self, host: impl Into<String>) -> Self {
        self.host = Some(host.into());
        self
    }
    
    pub fn port(mut self, port: u16) -> Self {
        self.port = Some(port);
        self
    }
    
    pub fn username(mut self, username: impl Into<String>) -> Self {
        self.username = Some(username.into());
        self
    }
    
    pub fn password(mut self, password: impl Into<String>) -> Self {
        self.password = Some(password.into());
        self
    }
    
    pub fn enable_ssl(mut self) -> Self {
        self.ssl_enabled = true;
        self
    }
    
    pub fn timeout(mut self, seconds: u64) -> Self {
        self.timeout_seconds = seconds;
        self
    }
    
    pub fn build(self) -> Result<DatabaseConfig, String> {
        let host = self.host.ok_or("Host is required")?;
        let port = self.port.ok_or("Port is required")?;
        let username = self.username.ok_or("Username is required")?;
        
        Ok(DatabaseConfig {
            host,
            port,
            username,
            password: self.password,
            ssl_enabled: self.ssl_enabled,
            timeout_seconds: self.timeout_seconds,
        })
    }
}

fn main() {
    let config = DatabaseConfigBuilder::new()
        .host("localhost")
        .port(5432)
        .username("admin")
        .password("secret123")
        .enable_ssl()
        .timeout(60)
        .build()
        .expect("Failed to build config");
    
    println!("{:?}", config);
}

当初始化参数多、可选项多、还带校验逻辑时，builder 模式基本就是最稳妥的解法。它能把“逐步填写字段”和“最终一致性检查”拆开。
比起一个十几个参数的大构造器，builder 读起来不容易串参数，维护时也更容易扩展。

Rust 的 builder 还有个常见优势，就是链式 API 可以直接消费 self 返回新值，写起来非常顺。
如果再配合 typestate，还能把“哪些字段必填”也编码进类型系统，不过那就属于进阶玩法了。

Exercises
练习

#![allow(unused)]
fn main() {
#[derive(Debug)]
struct Email {
    to: String,
    subject: String,
    body: Option<String>,
    cc: Vec<String>,
}

#[derive(Default)]
struct EmailBuilder {
    to: Option<String>,
    subject: Option<String>,
    body: Option<String>,
    cc: Vec<String>,
}

impl EmailBuilder {
    fn new() -> Self { Self::default() }

    fn to(mut self, to: impl Into<String>) -> Self {
        self.to = Some(to.into()); self
    }
    fn subject(mut self, subject: impl Into<String>) -> Self {
        self.subject = Some(subject.into()); self
    }
    fn body(mut self, body: impl Into<String>) -> Self {
        self.body = Some(body.into()); self
    }
    fn cc(mut self, addr: impl Into<String>) -> Self {
        self.cc.push(addr.into()); self
    }
    fn build(self) -> Result<Email, String> {
        let to = self.to.filter(|s| !s.is_empty())
            .ok_or("'to' is required")?;
        let subject = self.subject.filter(|s| !s.is_empty())
            .ok_or("'subject' is required")?;
        Ok(Email { to, subject, body: self.body, cc: self.cc })
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    #[test]
    fn valid_email() {
        let email = EmailBuilder::new()
            .to("alice@example.com")
            .subject("Hello")
            .build();
        assert!(email.is_ok());
    }
    #[test]
    fn missing_to_fails() {
        let email = EmailBuilder::new().subject("Hello").build();
        assert!(email.is_err());
    }
}
}

Collections — Vec, HashMap, and Iterators §§ZH§§ 集合：Vec、HashMap 与迭代器

Vec<T> vs List<T>
Vec&lt;T&gt; 与 List<T> 对照

What you’ll learn: Vec<T> compared with List<T>, HashMap compared with Dictionary, safe access patterns and why Rust returns Option instead of throwing, plus the ownership consequences of storing values inside collections.
本章将学到什么： 对照理解 Vec<T> 和 List<T>，HashMap 和 Dictionary，理解 Rust 为什么更喜欢返回 Option 而不是直接抛异常，以及集合在所有权语义下会带来哪些变化。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Vec<T> is Rust’s closest equivalent to C#’s List<T>, but the ownership model changes how it behaves when passed around.
Vec<T> 可以理解成 Rust 里最接近 List<T> 的东西，但一旦开始跨函数传递、借用、修改，所有权规则就会立刻把差异拉开。

C# List<T>
C# 的 List<T>

// C# List<T> - Reference type, heap allocated
var numbers = new List<int>();
numbers.Add(1);
numbers.Add(2);
numbers.Add(3);

// Pass to method - reference is copied
ProcessList(numbers);
Console.WriteLine(numbers.Count);  // Still accessible

void ProcessList(List<int> list)
{
    list.Add(4);  // Modifies original list
    Console.WriteLine($"Count in method: {list.Count}");
}

Rust Vec<T>
Rust 的 Vec<T>

#![allow(unused)]
fn main() {
// Rust Vec<T> - Owned type, heap allocated
let mut numbers = Vec::new();
numbers.push(1);
numbers.push(2);
numbers.push(3);

// Method that takes ownership
process_vec(numbers);
// println!("{:?}", numbers);  // ❌ Error: numbers was moved

// Method that borrows
let mut numbers = vec![1, 2, 3];  // vec! macro for convenience
process_vec_borrowed(&mut numbers);
println!("{:?}", numbers);  // ✅ Still accessible

fn process_vec(mut vec: Vec<i32>) {  // Takes ownership
    vec.push(4);
    println!("Count in method: {}", vec.len());
    // vec is dropped here
}

fn process_vec_borrowed(vec: &mut Vec<i32>) {  // Borrows mutably
    vec.push(4);
    println!("Count in method: {}", vec.len());
}
}

这里最容易把 C# 开发者晃一下的点，就是“把集合传给函数”这件事。
在 C# 里通常只是拷了一份引用；在 Rust 里，如果函数签名写的是 Vec<T>，那就是所有权转移。要继续用原变量，就得改成借用，别装糊涂。

Creating and Initializing Vectors
创建和初始化向量

// C# List initialization
var numbers = new List<int> { 1, 2, 3, 4, 5 };
var empty = new List<int>();
var sized = new List<int>(10);  // Initial capacity

// From other collections
var fromArray = new List<int>(new[] { 1, 2, 3 });

#![allow(unused)]
fn main() {
// Rust Vec initialization
let numbers = vec![1, 2, 3, 4, 5];  // vec! macro
let empty: Vec<i32> = Vec::new();   // Type annotation needed for empty
let sized = Vec::with_capacity(10); // Pre-allocate capacity

// From iterator
let from_range: Vec<i32> = (1..=5).collect();
let from_array = vec![1, 2, 3];
}

Rust 这边 vec![] 基本就是日常主力。
Vec::new()、with_capacity()、collect() 也都很常见，但只要是直接写固定内容，vec![] 的观感最好，读起来也利索。

Common Operations Comparison
常见操作对照

// C# List operations
var list = new List<int> { 1, 2, 3 };

list.Add(4);                    // Add element
list.Insert(0, 0);              // Insert at index
list.Remove(2);                 // Remove first occurrence
list.RemoveAt(1);               // Remove at index
list.Clear();                   // Remove all

int first = list[0];            // Index access
int count = list.Count;         // Get count
bool contains = list.Contains(3); // Check if contains

#![allow(unused)]
fn main() {
// Rust Vec operations
let mut vec = vec![1, 2, 3];

vec.push(4);                    // Add element
vec.insert(0, 0);               // Insert at index
vec.retain(|&x| x != 2);        // Remove elements (functional style)
vec.remove(1);                  // Remove at index
vec.clear();                    // Remove all

let first = vec[0];             // Index access (panics if out of bounds)
let safe_first = vec.get(0);    // Safe access, returns Option<&T>
let count = vec.len();          // Get count
let contains = vec.contains(&3); // Check if contains
}

这里最该盯住的是 get()。
直接索引 vec[0] 在越界时会 panic，vec.get(0) 才是安全访问入口。Rust 很喜欢把“可能失败”显式写出来，不会假装一切都能拿到值。

Safe Access Patterns
安全访问模式

// C# - Exception-based bounds checking
public int SafeAccess(List<int> list, int index)
{
    try
    {
        return list[index];
    }
    catch (ArgumentOutOfRangeException)
    {
        return -1;  // Default value
    }
}

// Rust - Option-based safe access
fn safe_access(vec: &Vec<i32>, index: usize) -> Option<i32> {
    vec.get(index).copied()  // Returns Option<i32>
}

fn main() {
    let vec = vec![1, 2, 3];
    
    // Safe access patterns
    match vec.get(10) {
        Some(value) => println!("Value: {}", value),
        None => println!("Index out of bounds"),
    }
    
    // Or with unwrap_or
    let value = vec.get(10).copied().unwrap_or(-1);
    println!("Value: {}", value);
}

Rust 的思路很直白：既然越界是正常可能性之一，那就把它编码进返回类型。
所以这里不是捕异常，而是返回 Option。调用方必须决定怎么处理 None，这个决定也会被代码明明白白写出来。

HashMap vs Dictionary
HashMap 与 Dictionary 对照

HashMap is Rust’s equivalent to C#’s Dictionary<K, V>.
HashMap 基本就是 Rust 里对应 Dictionary<K, V> 的那一位，但它同样会受到所有权和借用规则影响。

C# Dictionary
C# 的 Dictionary

// C# Dictionary<TKey, TValue>
var scores = new Dictionary<string, int>
{
    ["Alice"] = 100,
    ["Bob"] = 85,
    ["Charlie"] = 92
};

// Add/Update
scores["Dave"] = 78;
scores["Alice"] = 105;  // Update existing

// Safe access
if (scores.TryGetValue("Eve", out int score))
{
    Console.WriteLine($"Eve's score: {score}");
}
else
{
    Console.WriteLine("Eve not found");
}

// Iteration
foreach (var kvp in scores)
{
    Console.WriteLine($"{kvp.Key}: {kvp.Value}");
}

Rust HashMap
Rust 的 HashMap

#![allow(unused)]
fn main() {
use std::collections::HashMap;

// Create and initialize HashMap
let mut scores = HashMap::new();
scores.insert("Alice".to_string(), 100);
scores.insert("Bob".to_string(), 85);
scores.insert("Charlie".to_string(), 92);

// Or use from iterator
let scores: HashMap<String, i32> = [
    ("Alice".to_string(), 100),
    ("Bob".to_string(), 85),
    ("Charlie".to_string(), 92),
].into_iter().collect();

// Add/Update
let mut scores = scores;  // Make mutable
scores.insert("Dave".to_string(), 78);
scores.insert("Alice".to_string(), 105);  // Update existing

// Safe access
match scores.get("Eve") {
    Some(score) => println!("Eve's score: {}", score),
    None => println!("Eve not found"),
}

// Iteration
for (name, score) in &scores {
    println!("{}: {}", name, score);
}
}

读 HashMap 时，要把“插入会移动键和值”这件事记脑子里。
特别是 String 这种非 Copy 类型，插进去以后原变量就别再想着继续随便用了，除非是借用、克隆，或者本来就打算把所有权交进去。

HashMap Operations
HashMap 常见操作

// C# Dictionary operations
var dict = new Dictionary<string, int>();

dict["key"] = 42;                    // Insert/update
bool exists = dict.ContainsKey("key"); // Check existence
bool removed = dict.Remove("key");    // Remove
dict.Clear();                        // Clear all

// Get with default
int value = dict.GetValueOrDefault("missing", 0);

#![allow(unused)]
fn main() {
use std::collections::HashMap;

// Rust HashMap operations
let mut map = HashMap::new();

map.insert("key".to_string(), 42);   // Insert/update
let exists = map.contains_key("key"); // Check existence
let removed = map.remove("key");      // Remove, returns Option<V>
map.clear();                         // Clear all

// Entry API for advanced operations
let mut map = HashMap::new();
map.entry("key".to_string()).or_insert(42);  // Insert if not exists
map.entry("key".to_string()).and_modify(|v| *v += 1); // Modify if exists

// Get with default
let value = map.get("missing").copied().unwrap_or(0);
}

entry() 是 HashMap 里最值得尽快掌握的接口之一。
很多“如果不存在就插入，存在就修改”的操作，写成 entry 风格以后既省查找次数，也更不容易写出啰嗦分支。

Ownership with HashMap Keys and Values
HashMap 中键和值的所有权

#![allow(unused)]
fn main() {
// Understanding ownership with HashMap
fn ownership_example() {
    let mut map = HashMap::new();
    
    // String keys and values are moved into the map
    let key = String::from("name");
    let value = String::from("Alice");
    
    map.insert(key, value);
    // println!("{}", key);   // ❌ Error: key was moved
    // println!("{}", value); // ❌ Error: value was moved
    
    // Access via references
    if let Some(name) = map.get("name") {
        println!("Name: {}", name);  // Borrowing the value
    }
}

// Using &str keys (no ownership transfer)
fn string_slice_keys() {
    let mut map = HashMap::new();
    
    map.insert("name", "Alice");     // &str keys and values
    map.insert("age", "30");
    
    // No ownership issues with string literals
    println!("Name exists: {}", map.contains_key("name"));
}
}

这段就是典型的“Rust 不让糊涂账过关”。
字符串一旦被移动进 HashMap，原变量就结束了。反过来，如果键和值本身就是 'static 的字符串字面量，那自然就轻松很多，因为它们本来就不需要被所有权管理得那么紧。

Working with Collections
操作集合

Iteration Patterns
迭代模式

// C# iteration patterns
var numbers = new List<int> { 1, 2, 3, 4, 5 };

// For loop with index
for (int i = 0; i < numbers.Count; i++)
{
    Console.WriteLine($"Index {i}: {numbers[i]}");
}

// Foreach loop
foreach (int num in numbers)
{
    Console.WriteLine(num);
}

// LINQ methods
var doubled = numbers.Select(x => x * 2).ToList();
var evens = numbers.Where(x => x % 2 == 0).ToList();

#![allow(unused)]
fn main() {
// Rust iteration patterns
let numbers = vec![1, 2, 3, 4, 5];

// For loop with index
for (i, num) in numbers.iter().enumerate() {
    println!("Index {}: {}", i, num);
}

// For loop over values
for num in &numbers {  // Borrow each element
    println!("{}", num);
}

// Iterator methods (like LINQ)
let doubled: Vec<i32> = numbers.iter().map(|x| x * 2).collect();
let evens: Vec<i32> = numbers.iter().filter(|&x| x % 2 == 0).cloned().collect();

// Or more efficiently, consuming iterator
let doubled: Vec<i32> = numbers.into_iter().map(|x| x * 2).collect();
}

Rust 的 for 本质上也是围着迭代器转，所以“集合怎么被迭代”这件事比 C# 更重要一点。
是只读借用、可变借用，还是把元素本体直接拿走，这三种选择都会影响后续还能不能继续用原集合。

Iterator vs IntoIterator vs Iter
iter、into_iter、iter_mut 的区别

#![allow(unused)]
fn main() {
// Understanding different iteration methods
fn iteration_methods() {
    let vec = vec![1, 2, 3, 4, 5];
    
    // 1. iter() - borrows elements (&T)
    for item in vec.iter() {
        println!("{}", item);  // item is &i32
    }
    // vec is still usable here
    
    // 2. into_iter() - takes ownership (T)
    for item in vec.into_iter() {
        println!("{}", item);  // item is i32
    }
    // vec is no longer usable here
    
    let mut vec = vec![1, 2, 3, 4, 5];
    
    // 3. iter_mut() - mutable borrows (&mut T)
    for item in vec.iter_mut() {
        *item *= 2;  // item is &mut i32
    }
    println!("{:?}", vec);  // [2, 4, 6, 8, 10]
}
}

这三个接口一定要区分清楚。
很多借用检查器报错，说到底就是迭代方式选错了。iter() 是借，into_iter() 是拿走，iter_mut() 是独占可变借用。脑子里把这三张牌摆正，后面能少吃不少苦头。

Collecting Results
收集结果

// C# - Processing collections with potential errors
public List<int> ParseNumbers(List<string> inputs)
{
    var results = new List<int>();
    foreach (string input in inputs)
    {
        if (int.TryParse(input, out int result))
        {
            results.Add(result);
        }
        // Silently skip invalid inputs
    }
    return results;
}

// Rust - Explicit error handling with collect
fn parse_numbers(inputs: Vec<String>) -> Result<Vec<i32>, std::num::ParseIntError> {
    inputs.into_iter()
        .map(|s| s.parse::<i32>())  // Returns Result<i32, ParseIntError>
        .collect()                  // Collects into Result<Vec<i32>, ParseIntError>
}

// Alternative: Filter out errors
fn parse_numbers_filter(inputs: Vec<String>) -> Vec<i32> {
    inputs.into_iter()
        .filter_map(|s| s.parse::<i32>().ok())  // Keep only Ok values
        .collect()
}

fn main() {
    let inputs = vec!["1".to_string(), "2".to_string(), "invalid".to_string(), "4".to_string()];
    
    // Version that fails on first error
    match parse_numbers(inputs.clone()) {
        Ok(numbers) => println!("All parsed: {:?}", numbers),
        Err(error) => println!("Parse error: {}", error),
    }
    
    // Version that skips errors
    let numbers = parse_numbers_filter(inputs);
    println!("Successfully parsed: {:?}", numbers);  // [1, 2, 4]
}

这段特别能体现 Rust 的风格差异。
到底是“遇到一个错就整体失败”，还是“跳过错项继续收集成功结果”，在返回类型和迭代器链里会写得明明白白，不会混成一坨含糊逻辑。

Exercises
练习

var result = students
    .Where(s => s.Grade >= 90)
    .OrderByDescending(s => s.Grade)
    .Select(s => $"{s.Name}: {s.Grade}")
    .Take(3)
    .ToList();

#![allow(unused)]
fn main() {
struct Student { name: String, grade: u32 }
}

#[derive(Debug)]
struct Student { name: String, grade: u32 }

fn top_students(students: &mut [Student]) -> Vec<String> {
    students.sort_by(|a, b| b.grade.cmp(&a.grade)); // sort descending
    students.iter()
        .filter(|s| s.grade >= 90)
        .take(3)
        .map(|s| format!("{}: {}", s.name, s.grade))
        .collect()
}

fn main() {
    let mut students = vec![
        Student { name: "Alice".into(), grade: 95 },
        Student { name: "Bob".into(), grade: 88 },
        Student { name: "Carol".into(), grade: 92 },
        Student { name: "Dave".into(), grade: 97 },
        Student { name: "Eve".into(), grade: 91 },
    ];
    let result = top_students(&mut students);
    assert_eq!(result, vec!["Dave: 97", "Alice: 95", "Carol: 92"]);
    println!("{result:?}");
}

Enums and Pattern Matching §§ZH§§ 枚举与模式匹配

Algebraic Data Types vs C# Unions
代数数据类型与 C# 联合类型对照

What you’ll learn: Rust’s algebraic data types, meaning enums that can carry data, compared with C#’s more limited discriminated-union workarounds; match expressions with exhaustive checking, guard clauses, and nested destructuring patterns.
本章将学到什么： 对照理解 Rust 的代数数据类型，也就是“可携带数据的 enum”，以及 C# 里相对受限的判别联合替代写法；同时掌握带穷尽检查的 match 表达式、守卫条件和嵌套解构模式。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

C# Discriminated Unions (Limited)
C# 的判别联合写法（能力有限）

// C# - Limited union support with inheritance
public abstract class Result
{
    public abstract T Match<T>(Func<Success, T> onSuccess, Func<Error, T> onError);
}

public class Success : Result
{
    public string Value { get; }
    public Success(string value) => Value = value;
    
    public override T Match<T>(Func<Success, T> onSuccess, Func<Error, T> onError)
        => onSuccess(this);
}

public class Error : Result
{
    public string Message { get; }
    public Error(string message) => Message = message;
    
    public override T Match<T>(Func<Success, T> onSuccess, Func<Error, T> onError)
        => onError(this);
}

// C# 9+ Records with pattern matching (better)
public abstract record Shape;
public record Circle(double Radius) : Shape;
public record Rectangle(double Width, double Height) : Shape;

public static double Area(Shape shape) => shape switch
{
    Circle(var radius) => Math.PI * radius * radius,
    Rectangle(var width, var height) => width * height,
    _ => throw new ArgumentException("Unknown shape")  // [ERROR] Runtime error possible
};

Rust Algebraic Data Types (Enums)
Rust 代数数据类型（Enum）

#![allow(unused)]
fn main() {
// Rust - True algebraic data types with exhaustive pattern matching
#[derive(Debug, Clone)]
pub enum Result<T, E> {
    Ok(T),
    Err(E),
}

#[derive(Debug, Clone)]
pub enum Shape {
    Circle { radius: f64 },
    Rectangle { width: f64, height: f64 },
    Triangle { base: f64, height: f64 },
}

impl Shape {
    pub fn area(&self) -> f64 {
        match self {
            Shape::Circle { radius } => std::f64::consts::PI * radius * radius,
            Shape::Rectangle { width, height } => width * height,
            Shape::Triangle { base, height } => 0.5 * base * height,
            // [OK] Compiler error if any variant is missing!
        }
    }
}

// Advanced: Enums can hold different types
#[derive(Debug)]
pub enum Value {
    Integer(i64),
    Float(f64),
    Text(String),
    Boolean(bool),
    List(Vec<Value>),  // Recursive types!
}

impl Value {
    pub fn type_name(&self) -> &'static str {
        match self {
            Value::Integer(_) => "integer",
            Value::Float(_) => "float",
            Value::Text(_) => "text",
            Value::Boolean(_) => "boolean",
            Value::List(_) => "list",
        }
    }
}
}

这块差别非常大。
C# 里想做“不同分支携带不同数据”的模型，往往要靠继承、record、手写 Match 方法或者第三方库来拼；Rust 里 enum 天生就是干这个的，而且编译器还会盯着每个分支是不是都处理到了。

graph TD
    subgraph "C# Discriminated Unions (Workarounds)"
        CS_ABSTRACT["abstract class Result<br/>抽象基类"]
        CS_SUCCESS["class Success : Result<br/>成功分支类"]
        CS_ERROR["class Error : Result<br/>错误分支类"]
        CS_MATCH["Manual Match method<br/>or switch expressions<br/>手写 Match 或 switch"]
        CS_RUNTIME["[ERROR] Runtime exceptions<br/>for missing cases<br/>漏分支时可能在运行时炸"]
        CS_HEAP["[ERROR] Heap allocation<br/>for class inheritance<br/>继承对象通常走堆分配"]
        
        CS_ABSTRACT --> CS_SUCCESS
        CS_ABSTRACT --> CS_ERROR
        CS_SUCCESS --> CS_MATCH
        CS_ERROR --> CS_MATCH
        CS_MATCH --> CS_RUNTIME
        CS_ABSTRACT --> CS_HEAP
    end
    
    subgraph "Rust Algebraic Data Types"
        RUST_ENUM["enum Shape { ... }<br/>enum 定义"]
        RUST_VARIANTS["Circle { radius }<br/>Rectangle { width, height }<br/>Triangle { base, height }"]
        RUST_MATCH["match shape { ... }<br/>模式匹配"]
        RUST_EXHAUSTIVE["[OK] Exhaustive checking<br/>Compile-time guarantee<br/>编译期穷尽检查"]
        RUST_STACK["[OK] Efficient layout<br/>Memory use is explicit<br/>内存布局更明确"]
        RUST_ZERO["[OK] Zero-cost abstraction<br/>零成本抽象"]
        
        RUST_ENUM --> RUST_VARIANTS
        RUST_VARIANTS --> RUST_MATCH
        RUST_MATCH --> RUST_EXHAUSTIVE
        RUST_ENUM --> RUST_STACK
        RUST_STACK --> RUST_ZERO
    end
    
    style CS_RUNTIME fill:#ffcdd2,color:#000
    style CS_HEAP fill:#fff3e0,color:#000
    style RUST_EXHAUSTIVE fill:#c8e6c9,color:#000
    style RUST_STACK fill:#c8e6c9,color:#000
    style RUST_ZERO fill:#c8e6c9,color:#000

Enums and Pattern Matching
Enum 与模式匹配

Rust enums are far more expressive than C# enums. They can carry data and are one of the foundations of type-safe program design in Rust.
Rust 的 enum 比 C# 的 enum 强太多了。它不只是“几个命名常量”，而是能直接承载数据，并且是 Rust 类型安全设计里最核心的基石之一。

C# Enum Limitations
C# enum 的局限

// C# enum - just named constants
public enum Status
{
    Pending,
    Approved,
    Rejected
}

// C# enum with backing values
public enum HttpStatusCode
{
    OK = 200,
    NotFound = 404,
    InternalServerError = 500
}

// Need separate classes for complex data
public abstract class Result
{
    public abstract bool IsSuccess { get; }
}

public class Success : Result
{
    public string Value { get; }
    public override bool IsSuccess => true;
    
    public Success(string value)
    {
        Value = value;
    }
}

public class Error : Result
{
    public string Message { get; }
    public override bool IsSuccess => false;
    
    public Error(string message)
    {
        Message = message;
    }
}

Rust Enum Power
Rust enum 的能力

#![allow(unused)]
fn main() {
// Simple enum (like C# enum)
#[derive(Debug, PartialEq)]
enum Status {
    Pending,
    Approved,
    Rejected,
}

// Enum with data (this is where Rust shines!)
#[derive(Debug)]
enum Result<T, E> {
    Ok(T),      // Success variant holding value of type T
    Err(E),     // Error variant holding error of type E
}

// Complex enum with different data types
#[derive(Debug)]
enum Message {
    Quit,                       // No data
    Move { x: i32, y: i32 },   // Struct-like variant
    Write(String),             // Tuple-like variant
    ChangeColor(i32, i32, i32), // Multiple values
}

// Real-world example: HTTP Response
#[derive(Debug)]
enum HttpResponse {
    Ok { body: String, headers: Vec<String> },
    NotFound { path: String },
    InternalError { message: String, code: u16 },
    Redirect { location: String },
}
}

如果只把 Rust enum 当成“能带点字段的增强版枚举”，那就低估它了。
它真正猛的地方在于：一个类型就能完整描述一组互斥状态，而且每个状态带什么数据都能写死在类型定义里。这种表达力会一路影响错误处理、协议建模、状态机设计和命令解析。

Pattern Matching with Match
使用 match 做模式匹配

// C# switch statement (limited)
public string HandleStatus(Status status)
{
    switch (status)
    {
        case Status.Pending:
            return "Waiting for approval";
        case Status.Approved:
            return "Request approved";
        case Status.Rejected:
            return "Request rejected";
        default:
            return "Unknown status"; // Always need default
    }
}

// C# pattern matching (C# 8+)
public string HandleResult(Result result)
{
    return result switch
    {
        Success success => $"Success: {success.Value}",
        Error error => $"Error: {error.Message}",
        _ => "Unknown result" // Still need catch-all
    };
}

#![allow(unused)]
fn main() {
// Rust match - exhaustive and powerful
fn handle_status(status: Status) -> String {
    match status {
        Status::Pending => "Waiting for approval".to_string(),
        Status::Approved => "Request approved".to_string(),
        Status::Rejected => "Request rejected".to_string(),
        // No default needed - compiler ensures exhaustiveness
    }
}

// Pattern matching with data extraction
fn handle_result<T, E>(result: Result<T, E>) -> String 
where 
    T: std::fmt::Debug,
    E: std::fmt::Debug,
{
    match result {
        Result::Ok(value) => format!("Success: {:?}", value),
        Result::Err(error) => format!("Error: {:?}", error),
        // Exhaustive - no default needed
    }
}

// Complex pattern matching
fn handle_message(msg: Message) -> String {
    match msg {
        Message::Quit => "Goodbye!".to_string(),
        Message::Move { x, y } => format!("Move to ({}, {})", x, y),
        Message::Write(text) => format!("Write: {}", text),
        Message::ChangeColor(r, g, b) => format!("Change color to RGB({}, {}, {})", r, g, b),
    }
}

// HTTP response handling
fn handle_http_response(response: HttpResponse) -> String {
    match response {
        HttpResponse::Ok { body, headers } => {
            format!("Success! Body: {}, Headers: {:?}", body, headers)
        },
        HttpResponse::NotFound { path } => {
            format!("404: Path '{}' not found", path)
        },
        HttpResponse::InternalError { message, code } => {
            format!("Error {}: {}", code, message)
        },
        HttpResponse::Redirect { location } => {
            format!("Redirect to: {}", location)
        },
    }
}
}

match 的价值不是“语法比 switch 花哨”，而是它能把数据提取和分支覆盖检查揉成一个东西。
在 C# 里，经常得靠默认分支兜底；在 Rust 里，少写一个分支，编译器就跟着拍桌子。这就是为什么很多逻辑一旦改成 enum + match，代码会明显更扎实。

Guards and Advanced Patterns
守卫条件与进阶模式

#![allow(unused)]
fn main() {
// Pattern matching with guards
fn describe_number(x: i32) -> String {
    match x {
        n if n < 0 => "negative".to_string(),
        0 => "zero".to_string(),
        n if n < 10 => "single digit".to_string(),
        n if n < 100 => "double digit".to_string(),
        _ => "large number".to_string(),
    }
}

// Matching ranges
fn describe_age(age: u32) -> String {
    match age {
        0..=12 => "child".to_string(),
        13..=19 => "teenager".to_string(),
        20..=64 => "adult".to_string(),
        65.. => "senior".to_string(),
    }
}

// Destructuring structs and tuples
}

这类高级模式真正好用的地方，在于它能把“判断条件”和“数据结构形状”一起表达出来。
守卫、范围匹配、结构体解构、元组解构都属于这一挂。写得熟了以后，会发现很多 if / else 套娃都能被压扁成更清爽的 match。

#![allow(unused)]
fn main() {
// Starter code — fill in the blanks
#[derive(Debug)]
enum Command {
    // TODO: Add variants for Quit, Echo(String), Move { x: i32, y: i32 }, Count(u32)
}

fn parse_command(input: &str) -> Result<Command, String> {
    let parts: Vec<&str> = input.splitn(2, ' ').collect();
    // TODO: match on parts[0] and parse arguments
    todo!()
}

fn execute(cmd: &Command) -> String {
    // TODO: match on each variant and return a description
    todo!()
}
}

#![allow(unused)]
fn main() {
#[derive(Debug)]
enum Command {
    Quit,
    Echo(String),
    Move { x: i32, y: i32 },
    Count(u32),
}

fn parse_command(input: &str) -> Result<Command, String> {
    let parts: Vec<&str> = input.splitn(2, ' ').collect();
    match parts[0] {
        "quit" => Ok(Command::Quit),
        "echo" => {
            let msg = parts.get(1).unwrap_or(&"").to_string();
            Ok(Command::Echo(msg))
        }
        "move" => {
            let args = parts.get(1).ok_or("move requires 'x y'")?;
            let coords: Vec<&str> = args.split_whitespace().collect();
            let x = coords.get(0).ok_or("missing x")?.parse::<i32>().map_err(|e| e.to_string())?;
            let y = coords.get(1).ok_or("missing y")?.parse::<i32>().map_err(|e| e.to_string())?;
            Ok(Command::Move { x, y })
        }
        "count" => {
            let n = parts.get(1).ok_or("count requires a number")?
                .parse::<u32>().map_err(|e| e.to_string())?;
            Ok(Command::Count(n))
        }
        other => Err(format!("Unknown command: {other}")),
    }
}

fn execute(cmd: &Command) -> String {
    match cmd {
        Command::Quit           => "Goodbye!".to_string(),
        Command::Echo(msg)      => msg.clone(),
        Command::Move { x, y }  => format!("Moving to ({x}, {y})"),
        Command::Count(n)       => format!("Counted to {n}"),
    }
}
}

Exhaustive Matching and Null Safety §§ZH§§ 穷尽匹配与空安全

Exhaustive Pattern Matching: Compiler Guarantees vs Runtime Errors
穷尽模式匹配：编译器保证与运行时错误的对照

What you’ll learn: Why C# switch expressions can still miss cases while Rust match catches missing branches at compile time, how Option<T> differs from Nullable<T> for null safety, and how custom Result<T, E> error types fit into the same model.
本章将学到什么： 理解为什么 C# 的 switch 表达式依旧可能漏分支，而 Rust 的 match 会在编译期把缺漏揪出来；同时对照 Option<T> 与 Nullable<T> 的空值安全思路，并看清自定义 Result<T, E> 错误类型怎样和这套模型接起来。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

C# Switch Expressions - Still Incomplete
C# switch 表达式：看着全，实际上未必全

// C# switch expressions look exhaustive but aren't guaranteed
public enum HttpStatus { Ok, NotFound, ServerError, Unauthorized }

public string HandleResponse(HttpStatus status) => status switch
{
    HttpStatus.Ok => "Success",
    HttpStatus.NotFound => "Resource not found",
    HttpStatus.ServerError => "Internal error",
    // Missing Unauthorized case — compiles with warning CS8524, but NOT an error!
    // Runtime: SwitchExpressionException if status is Unauthorized
};

// Even with nullable warnings, this compiles:
public class User 
{
    public string Name { get; set; }
    public bool IsActive { get; set; }
}

public string ProcessUser(User? user) => user switch
{
    { IsActive: true } => $"Active: {user.Name}",
    { IsActive: false } => $"Inactive: {user.Name}",
    // Missing null case — compiler warning CS8655, but NOT an error!
    // Runtime: SwitchExpressionException when user is null
};

// Adding an enum variant later doesn't break compilation of existing switches
public enum HttpStatus 
{ 
    Ok, 
    NotFound, 
    ServerError, 
    Unauthorized,
    Forbidden  // Adding this produces another CS8524 warning but doesn't break compilation!
}

Rust Pattern Matching - True Exhaustiveness
Rust 模式匹配：真正的穷尽检查

#![allow(unused)]
fn main() {
#[derive(Debug)]
enum HttpStatus {
    Ok,
    NotFound, 
    ServerError,
    Unauthorized,
}

fn handle_response(status: HttpStatus) -> &'static str {
    match status {
        HttpStatus::Ok => "Success",
        HttpStatus::NotFound => "Resource not found", 
        HttpStatus::ServerError => "Internal error",
        HttpStatus::Unauthorized => "Authentication required",
        // Compiler ERROR if any case is missing!
        // This literally will not compile
    }
}

// Adding a new variant breaks compilation everywhere it's used
#[derive(Debug)]
enum HttpStatus {
    Ok,
    NotFound,
    ServerError, 
    Unauthorized,
    Forbidden,  // Adding this breaks compilation in handle_response()
}
// The compiler forces you to handle ALL cases

// Option<T> pattern matching is also exhaustive
fn process_optional_value(value: Option<i32>) -> String {
    match value {
        Some(n) => format!("Got value: {}", n),
        None => "No value".to_string(),
        // Forgetting either case = compilation error
    }
}
}

Rust 在这里最硬核的一点，就是“新增分支以后，旧代码必须跟着改”。
这件事在某些人眼里像麻烦，但其实是大礼。因为类型一旦演化，编译器会把所有受影响的位置全翻出来，不让隐藏 bug 悄悄混进生产环境。

graph TD
    subgraph "C# Pattern Matching Limitations"
        CS_SWITCH["switch expression<br/>switch 表达式"]
        CS_WARNING["⚠️ Compiler warnings only<br/>多数只是警告"]
        CS_COMPILE["✅ Compiles successfully<br/>照样能编译"]
        CS_RUNTIME["💥 Runtime exceptions<br/>运行时炸锅"]
        CS_DEPLOY["❌ Bugs reach production<br/>缺陷进生产"]
        CS_SILENT["😰 Silent failures on enum changes<br/>enum 变化时静悄悄漏处理"]
        
        CS_SWITCH --> CS_WARNING
        CS_WARNING --> CS_COMPILE
        CS_COMPILE --> CS_RUNTIME
        CS_RUNTIME --> CS_DEPLOY
        CS_SWITCH --> CS_SILENT
    end
    
    subgraph "Rust Exhaustive Matching"
        RUST_MATCH["match expression<br/>match 表达式"]
        RUST_ERROR["🛑 Compilation fails<br/>直接编译失败"]
        RUST_FIX["✅ Must handle all cases<br/>必须补齐分支"]
        RUST_SAFE["✅ Zero runtime surprises<br/>运行时意外更少"]
        RUST_EVOLUTION["🔄 Enum changes break compilation<br/>类型演化会触发编译错误"]
        RUST_REFACTOR["🛠️ Forced refactoring<br/>被迫做完整重构修补"]
        
        RUST_MATCH --> RUST_ERROR
        RUST_ERROR --> RUST_FIX
        RUST_FIX --> RUST_SAFE
        RUST_MATCH --> RUST_EVOLUTION
        RUST_EVOLUTION --> RUST_REFACTOR
    end
    
    style CS_RUNTIME fill:#ffcdd2,color:#000
    style CS_DEPLOY fill:#ffcdd2,color:#000
    style CS_SILENT fill:#ffcdd2,color:#000
    style RUST_SAFE fill:#c8e6c9,color:#000
    style RUST_REFACTOR fill:#c8e6c9,color:#000

Null Safety: Nullable<T> vs Option<T>
空值安全：Nullable<T> 与 Option<T> 对照

C# Null Handling Evolution
C# 空值处理的演进

// C# - Traditional null handling (error-prone)
public class User
{
    public string Name { get; set; }  // Can be null!
    public string Email { get; set; } // Can be null!
}

public string GetUserDisplayName(User user)
{
    if (user?.Name != null)  // Null conditional operator
    {
        return user.Name;
    }
    return "Unknown User";
}

// C# 8+ Nullable Reference Types
public class User
{
    public string Name { get; set; }    // Non-nullable
    public string? Email { get; set; }  // Explicitly nullable
}

// C# Nullable<T> for value types
int? maybeNumber = GetNumber();
if (maybeNumber.HasValue)
{
    Console.WriteLine(maybeNumber.Value);
}

Rust Option<T> System
Rust 的 Option<T> 体系

#![allow(unused)]
fn main() {
// Rust - Explicit null handling with Option<T>
#[derive(Debug)]
pub struct User {
    name: String,           // Never null
    email: Option<String>,  // Explicitly optional
}

impl User {
    pub fn get_display_name(&self) -> &str {
        &self.name  // No null check needed - guaranteed to exist
    }
    
    pub fn get_email_or_default(&self) -> String {
        self.email
            .as_ref()
            .map(|e| e.clone())
            .unwrap_or_else(|| "no-email@example.com".to_string())
    }
}

// Pattern matching forces handling of None case
fn handle_optional_user(user: Option<User>) {
    match user {
        Some(u) => println!("User: {}", u.get_display_name()),
        None => println!("No user found"),
        // Compiler error if None case is not handled!
    }
}
}

Rust 的思路是：与其让所有引用都默认可能为空，再靠规则提醒开发者小心，不如把“可选”这件事直接写进类型里。
于是 Option<T> 不是语言边角料，而是到处都能接得上的核心建模工具。只要类型写成 Option<T>，调用方就得面对 None，躲不过去。

graph TD
    subgraph "C# Null Handling Evolution"
        CS_NULL["Traditional: string name<br/>[ERROR] Can be null<br/>传统引用随时可能为 null"]
        CS_NULLABLE["Nullable&lt;T&gt;: int? value<br/>[OK] Explicit for value types<br/>值类型有显式可空包装"]
        CS_NRT["Nullable Reference Types<br/>string? name<br/>[WARNING] Warnings only<br/>引用类型更多还是警告级别"]
        
        CS_RUNTIME["Runtime NullReferenceException<br/>[ERROR] Can still crash<br/>运行时依旧可能空引用崩溃"]
        CS_NULL --> CS_RUNTIME
        CS_NRT -.-> CS_RUNTIME
        
        CS_CHECKS["Manual null checks<br/>if (obj?.Property != null)<br/>到处手写判空"]
    end
    
    subgraph "Rust Option<T> System"
        RUST_OPTION["Option&lt;T&gt;<br/>Some(value) | None"]
        RUST_FORCE["Compiler forces handling<br/>[OK] Cannot ignore None<br/>编译器强制处理 None"]
        RUST_MATCH["Pattern matching<br/>match option { ... }<br/>模式匹配"]
        RUST_METHODS["Rich API<br/>.map(), .unwrap_or(), .and_then()<br/>组合方法丰富"]
        
        RUST_OPTION --> RUST_FORCE
        RUST_FORCE --> RUST_MATCH
        RUST_FORCE --> RUST_METHODS
        
        RUST_SAFE["Compile-time null safety<br/>[OK] No null pointer exceptions<br/>编译期空值安全"]
        RUST_MATCH --> RUST_SAFE
        RUST_METHODS --> RUST_SAFE
    end
    
    style CS_RUNTIME fill:#ffcdd2,color:#000
    style RUST_SAFE fill:#c8e6c9,color:#000
    style CS_NRT fill:#fff3e0,color:#000
    style RUST_FORCE fill:#c8e6c9,color:#000

#![allow(unused)]
fn main() {
#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn describe_point(point: Point) -> String {
    match point {
        Point { x: 0, y: 0 } => "origin".to_string(),
        Point { x: 0, y } => format!("on y-axis at y={}", y),
        Point { x, y: 0 } => format!("on x-axis at x={}", x),
        Point { x, y } if x == y => format!("on diagonal at ({}, {})", x, y),
        Point { x, y } => format!("point at ({}, {})", x, y),
    }
}
}

这个例子说明 match 不只是枚举专属。
结构体、元组、常量、范围、守卫条件都能一起上。很多“数据结构长什么样”和“当前逻辑该怎么分支”之间的关系，写在一处就讲明白了。

Option and Result Types
Option 与 Result 类型

// C# nullable reference types (C# 8+)
public class PersonService
{
    private Dictionary<int, string> people = new();
    
    public string? FindPerson(int id)
    {
        return people.TryGetValue(id, out string? name) ? name : null;
    }
    
    public string GetPersonOrDefault(int id)
    {
        return FindPerson(id) ?? "Unknown";
    }
    
    // Exception-based error handling
    public void SavePerson(int id, string name)
    {
        if (string.IsNullOrEmpty(name))
            throw new ArgumentException("Name cannot be empty");
        
        people[id] = name;
    }
}

use std::collections::HashMap;

// Rust uses Option<T> instead of null
struct PersonService {
    people: HashMap<i32, String>,
}

impl PersonService {
    fn new() -> Self {
        PersonService {
            people: HashMap::new(),
        }
    }
    
    // Returns Option<T> - no null!
    fn find_person(&self, id: i32) -> Option<&String> {
        self.people.get(&id)
    }
    
    // Pattern matching on Option
    fn get_person_or_default(&self, id: i32) -> String {
        match self.find_person(id) {
            Some(name) => name.clone(),
            None => "Unknown".to_string(),
        }
    }
    
    // Using Option methods (more functional style)
    fn get_person_or_default_functional(&self, id: i32) -> String {
        self.find_person(id)
            .map(|name| name.clone())
            .unwrap_or_else(|| "Unknown".to_string())
    }
    
    // Result<T, E> for error handling
    fn save_person(&mut self, id: i32, name: String) -> Result<(), String> {
        if name.is_empty() {
            return Err("Name cannot be empty".to_string());
        }
        
        self.people.insert(id, name);
        Ok(())
    }
    
    // Chaining operations
    fn get_person_length(&self, id: i32) -> Option<usize> {
        self.find_person(id).map(|name| name.len())
    }
}

fn main() {
    let mut service = PersonService::new();
    
    // Handle Result
    match service.save_person(1, "Alice".to_string()) {
        Ok(()) => println!("Person saved successfully"),
        Err(error) => println!("Error: {}", error),
    }
    
    // Handle Option
    match service.find_person(1) {
        Some(name) => println!("Found: {}", name),
        None => println!("Person not found"),
    }
    
    // Functional style with Option
    let name_length = service.get_person_length(1)
        .unwrap_or(0);
    println!("Name length: {}", name_length);
    
    // Question mark operator for early returns
    fn try_operation(service: &mut PersonService) -> Result<String, String> {
        service.save_person(2, "Bob".to_string())?; // Early return if error
        let name = service.find_person(2).ok_or("Person not found")?; // Convert Option to Result
        Ok(format!("Hello, {}", name))
    }
    
    match try_operation(&mut service) {
        Ok(message) => println!("{}", message),
        Err(error) => println!("Operation failed: {}", error),
    }
}

Option 和 Result 这对组合拳几乎贯穿 Rust 日常。
前者表达“可能没有值”，后者表达“可能失败而且要说明原因”。很多 API 一眼看过去就能知道：这里到底是查不到、还是执行失败，这比把所有问题都塞进异常或 null 里干净得多。

Custom Error Types
自定义错误类型

#![allow(unused)]
fn main() {
// Define custom error enum
#[derive(Debug)]
enum PersonError {
    NotFound(i32),
    InvalidName(String),
    DatabaseError(String),
}

impl std::fmt::Display for PersonError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            PersonError::NotFound(id) => write!(f, "Person with ID {} not found", id),
            PersonError::InvalidName(name) => write!(f, "Invalid name: '{}'", name),
            PersonError::DatabaseError(msg) => write!(f, "Database error: {}", msg),
        }
    }
}

impl std::error::Error for PersonError {}

// Enhanced PersonService with custom errors
impl PersonService {
    fn save_person_enhanced(&mut self, id: i32, name: String) -> Result<(), PersonError> {
        if name.is_empty() || name.len() > 50 {
            return Err(PersonError::InvalidName(name));
        }
        
        // Simulate database operation that might fail
        if id < 0 {
            return Err(PersonError::DatabaseError("Negative IDs not allowed".to_string()));
        }
        
        self.people.insert(id, name);
        Ok(())
    }
    
    fn find_person_enhanced(&self, id: i32) -> Result<&String, PersonError> {
        self.people.get(&id).ok_or(PersonError::NotFound(id))
    }
}

fn demo_error_handling() {
    let mut service = PersonService::new();
    
    // Handle different error types
    match service.save_person_enhanced(-1, "Invalid".to_string()) {
        Ok(()) => println!("Success"),
        Err(PersonError::NotFound(id)) => println!("Not found: {}", id),
        Err(PersonError::InvalidName(name)) => println!("Invalid name: {}", name),
        Err(PersonError::DatabaseError(msg)) => println!("DB Error: {}", msg),
    }
}
}

一旦业务稍微复杂一点，就别再一直 Result<T, String> 糊弄了。
自定义错误枚举会让错误来源、语义、展示方式都清清楚楚，后面无论是日志、重试、分类处理还是接口返回，都更好拿捏。

Exercises
练习

string GetCityName(User? user)
{
    if (user != null)
        if (user.Address != null)
            if (user.Address.City != null)
                return user.Address.City.ToUpper();
    return "UNKNOWN";
}

#![allow(unused)]
fn main() {
struct User { address: Option<Address> }
struct Address { city: Option<String> }
}

struct User { address: Option<Address> }
struct Address { city: Option<String> }

fn get_city_name(user: Option<&User>) -> String {
    user.and_then(|u| u.address.as_ref())
        .and_then(|a| a.city.as_ref())
        .map(|c| c.to_uppercase())
        .unwrap_or_else(|| "UNKNOWN".to_string())
}

fn main() {
    let user = User {
        address: Some(Address { city: Some("seattle".to_string()) }),
    };
    assert_eq!(get_city_name(Some(&user)), "SEATTLE");
    assert_eq!(get_city_name(None), "UNKNOWN");

    let no_city = User { address: Some(Address { city: None }) };
    assert_eq!(get_city_name(Some(&no_city)), "UNKNOWN");
}

Ownership and Borrowing §§ZH§§ 所有权与借用

Understanding Ownership
理解所有权

What you’ll learn: Rust’s ownership system, why let s2 = s1 invalidates s1 unlike C# reference copying, the three ownership rules, Copy vs move types, borrowing with & and &mut, and how the borrow checker replaces garbage collection.
本章将学到什么： 理解 Rust 的所有权系统，理解为什么 let s2 = s1 会让 s1 失效而不是像 C# 那样复制引用，掌握三条所有权规则，分清 Copy 类型和移动类型，理解 &、&mut 借用，以及借用检查器如何替代垃圾回收。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

Ownership is Rust’s most distinctive feature and usually the biggest conceptual jump for C# developers. The trick is to stop treating it as mysticism and instead read it as a set of concrete rules about who is responsible for a value at any moment.
所有权是 Rust 最有辨识度的特性，也往往是 C# 开发者迈过去最费劲的一坎。关键是别把它看成玄学，而是把它当成一套非常具体的规则：在任何时刻，谁负责这个值，谁能使用它，谁该在作用域结束时把它清理掉。

C# Memory Model (Review)
C# 内存模型回顾

// C# - Automatic memory management
public void ProcessData()
{
    var data = new List<int> { 1, 2, 3, 4, 5 };
    ProcessList(data);
    // data is still accessible here
    Console.WriteLine(data.Count);  // Works fine
    
    // GC will clean up when no references remain
}

public void ProcessList(List<int> list)
{
    list.Add(6);  // Modifies the original list
}

Rust Ownership Rules
Rust 所有权规则

1. Each value has exactly one owner unless shared ownership is made explicit with types like Rc<T> or Arc<T>.
   每个值在默认情况下都只有一个拥有者，除非显式引入 Rc<T>、Arc<T> 这类共享所有权方案。
2. When the owner goes out of scope, the value is dropped and cleanup happens deterministically.
   拥有者离开作用域时，值就会被销毁，清理时机是确定的，不靠 GC 碰运气。
3. Ownership can be transferred by moving the value.
   所有权可以被转移，也就是常说的 move。

#![allow(unused)]
fn main() {
// Rust - Explicit ownership management
fn process_data() {
    let data = vec![1, 2, 3, 4, 5];  // data owns the vector
    process_list(data);              // Ownership moved to function
    // println!("{:?}", data);       // ❌ Error: data no longer owned here
}

fn process_list(mut list: Vec<i32>) {  // list now owns the vector
    list.push(6);
    // list is dropped here when function ends
}
}

这三条规则其实不绕，就是很严。
一旦接受“值在某个时刻只能有一个明确负责者”，很多报错都会突然变得有逻辑。Rust 不是故意刁难，而是在逼代码把资源归属说清楚。

Understanding “Move” for C# Developers
C# 开发者怎么理解 move

// C# - References are copied, objects stay in place
// (Only reference types — classes — work this way;
//  C# value types like struct behave differently)
var original = new List<int> { 1, 2, 3 };
var reference = original;  // Both variables point to same object
original.Add(4);
Console.WriteLine(reference.Count);  // 4 - same object

#![allow(unused)]
fn main() {
// Rust - Ownership is transferred
let original = vec![1, 2, 3];
let moved = original;       // Ownership transferred
// println!("{:?}", original);  // ❌ Error: original no longer owns the data
println!("{:?}", moved);    // ✅ Works: moved now owns the data
}

这里最大的心理落差就在于：C# 的“赋值”经常只是多了一个指向同一对象的引用；Rust 的“赋值”在很多类型上代表所有权转交。
所以很多刚上手的人会觉得“怎么赋个值原变量就死了”，其实不是原变量死了，是责任被正式交出去了。

Copy Types vs Move Types
Copy 类型与 move 类型

#![allow(unused)]
fn main() {
// Copy types (like C# value types) - copied, not moved
let x = 5;        // i32 implements Copy
let y = x;        // x is copied to y
println!("{}", x); // ✅ Works: x is still valid

// Move types (like C# reference types) - moved, not copied  
let s1 = String::from("hello");  // String doesn't implement Copy
let s2 = s1;                     // s1 is moved to s2
// println!("{}", s1);           // ❌ Error: s1 is no longer valid
}

并不是所有 Rust 类型都会 move。
像整数、布尔、字符这类小而固定的值，通常实现了 Copy，赋值就是复制；而像 String、Vec<T>、大多数 struct 这类拥有资源的类型，默认就是 move。这条线要早点分清，不然后面会老在脑内打架。

Practical Example: Swapping Values
实战例子：交换值

// C# - Simple reference swapping
public void SwapLists(ref List<int> a, ref List<int> b)
{
    var temp = a;
    a = b;
    b = temp;
}

#![allow(unused)]
fn main() {
// Rust - Ownership-aware swapping
fn swap_vectors(a: &mut Vec<i32>, b: &mut Vec<i32>) {
    std::mem::swap(a, b);  // Built-in swap function
}

// Or manual approach
fn manual_swap() {
    let mut a = vec![1, 2, 3];
    let mut b = vec![4, 5, 6];
    
    let temp = a;  // Move a to temp
    a = b;         // Move b to a
    b = temp;      // Move temp to b
    
    println!("a: {:?}, b: {:?}", a, b);
}
}

这类例子很适合把 move 想明白。
所谓 move，不一定意味着“底层内存真的被搬来搬去”，更准确地说，是变量和它所拥有资源之间的归属关系在变。

Borrowing Basics
借用基础

Borrowing in Rust is a bit like passing references in C#, except the compiler actually enforces the safety contract instead of trusting everyone to behave.
Rust 的借用有点像 C# 里的引用传递，但区别在于：C# 往往只是提供机制，开发者自己负责别出乱子；Rust 则是编译器亲自盯着，谁乱来谁别过编译。

C# Reference Parameters
C# 的引用参数

// C# - ref and out parameters
public void ModifyValue(ref int value)
{
    value += 10;
}

public void ReadValue(in int value)  // readonly reference
{
    Console.WriteLine(value);
}

public bool TryParse(string input, out int result)
{
    return int.TryParse(input, out result);
}

Rust Borrowing
Rust 借用

// Rust - borrowing with & and &mut
fn modify_value(value: &mut i32) {  // Mutable borrow
    *value += 10;
}

fn read_value(value: &i32) {        // Immutable borrow
    println!("{}", value);
}

fn main() {
    let mut x = 5;
    
    read_value(&x);      // Borrow immutably
    modify_value(&mut x); // Borrow mutably
    
    println!("{}", x);   // x is still owned here
}

这里要养成一个习惯：看到 &T 就想“只读借用”，看到 &mut T 就想“独占可变借用”。
这不是语法细枝末节，而是 Rust 代码阅读的基本功。很多 API 的语义，其实在参数类型上已经写得明明白白了。

Borrowing Rules (Enforced at Compile Time!)
借用规则（编译期强制执行）

#![allow(unused)]
fn main() {
fn borrowing_rules() {
    let mut data = vec![1, 2, 3];
    
    // Rule 1: Multiple immutable borrows are OK
    let r1 = &data;
    let r2 = &data;
    println!("{:?} {:?}", r1, r2);  // ✅ Works
    
    // Rule 2: Only one mutable borrow at a time
    let r3 = &mut data;
    // let r4 = &mut data;  // ❌ Error: cannot borrow mutably twice
    // let r5 = &data;      // ❌ Error: cannot borrow immutably while borrowed mutably
    
    r3.push(4);  // Use the mutable borrow
    // r3 goes out of scope here
    
    // Rule 3: Can borrow again after previous borrows end
    let r6 = &data;  // ✅ Works now
    println!("{:?}", r6);
}
}

这几条规则看起来死板，但它们正是 Rust 能把数据竞争和悬垂引用挡在编译阶段的原因。
“多个只读可以同时存在，但可变借用必须独占”这条一旦吃透，后面大量借用检查器报错都会自己解开一半。

C# vs Rust: Reference Safety
C# 与 Rust 的引用安全对照

// C# - Potential runtime errors
public class ReferenceSafety
{
    private List<int> data = new List<int>();
    
    public List<int> GetData() => data;  // Returns reference to internal data
    
    public void UnsafeExample()
    {
        var reference = GetData();
        
        // Another thread could modify data here!
        Thread.Sleep(1000);
        
        // reference might be invalid or changed
        reference.Add(42);  // Potential race condition
    }
}

#![allow(unused)]
fn main() {
// Rust - Compile-time safety
pub struct SafeContainer {
    data: Vec<i32>,
}

impl SafeContainer {
    // Return immutable borrow - caller can't modify
    // Prefer &[i32] over &Vec<i32> — accept the broadest type
    pub fn get_data(&self) -> &[i32] {
        &self.data
    }
    
    // Return mutable borrow - exclusive access guaranteed
    pub fn get_data_mut(&mut self) -> &mut Vec<i32> {
        &mut self.data
    }
}

fn safe_example() {
    let mut container = SafeContainer { data: vec![1, 2, 3] };
    
    let reference = container.get_data();
    // container.get_data_mut();  // ❌ Error: can't borrow mutably while immutably borrowed
    
    println!("{:?}", reference);  // Use immutable reference
    // reference goes out of scope here
    
    let mut_reference = container.get_data_mut();  // ✅ Now OK
    mut_reference.push(4);
}
}

Rust 很喜欢把“什么时候能改，什么时候只能看”写成类型规则。
所以 API 设计也会跟着更清楚。返回 &[i32] 就是只读视图，返回 &mut Vec<i32> 就是明确放出独占修改权，没有模糊地带。

Move Semantics
Move 语义

C# Value Types vs Reference Types
C# 值类型与引用类型

// C# - Value types are copied
struct Point
{
    public int X { get; set; }
    public int Y { get; set; }
}

var p1 = new Point { X = 1, Y = 2 };
var p2 = p1;  // Copy
p2.X = 10;
Console.WriteLine(p1.X);  // Still 1

// C# - Reference types share the object
var list1 = new List<int> { 1, 2, 3 };
var list2 = list1;  // Reference copy
list2.Add(4);
Console.WriteLine(list1.Count);  // 4 - same object

Rust Move Semantics
Rust 的 move 语义

#![allow(unused)]
fn main() {
// Rust - Move by default for non-Copy types
#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}

fn move_example() {
    let p1 = Point { x: 1, y: 2 };
    let p2 = p1;  // Move (not copy)
    // println!("{:?}", p1);  // ❌ Error: p1 was moved
    println!("{:?}", p2);    // ✅ Works
}

// To enable copying, implement Copy trait
#[derive(Debug, Copy, Clone)]
struct CopyablePoint {
    x: i32,
    y: i32,
}

fn copy_example() {
    let p1 = CopyablePoint { x: 1, y: 2 };
    let p2 = p1;  // Copy (because it implements Copy)
    println!("{:?}", p1);  // ✅ Works
    println!("{:?}", p2);  // ✅ Works
}
}

这一步经常能让人理解一个关键事实：Rust 不是“所有 struct 都不能复制”，而是“默认别偷偷复制可能很重或者会造成语义歧义的值”。
如果一个类型足够小、语义上也适合按位复制，就让它实现 Copy。如果不适合，那就老老实实走 move。

When Values Are Moved
值会在什么时候被 move

#![allow(unused)]
fn main() {
fn demonstrate_moves() {
    let s = String::from("hello");
    
    // 1. Assignment moves
    let s2 = s;  // s moved to s2
    
    // 2. Function calls move
    take_ownership(s2);  // s2 moved into function
    
    // 3. Returning from functions moves
    let s3 = give_ownership();  // Return value moved to s3
    
    println!("{}", s3);  // s3 is valid
}

fn take_ownership(s: String) {
    println!("{}", s);
    // s is dropped here
}

fn give_ownership() -> String {
    String::from("yours")  // Ownership moved to caller
}
}

只要参数类型或赋值行为要求拿值本体，move 就会发生。
这也是为什么看函数签名特别重要。很多时候问题根本不在调用点，而在于被调用函数要的是拥有者，还是只借一下。

Avoiding Moves with Borrowing
用借用避免 move

#![allow(unused)]
fn main() {
fn demonstrate_borrowing() {
    let s = String::from("hello");
    
    // Borrow instead of move
    let len = calculate_length(&s);  // s is borrowed
    println!("'{}' has length {}", s, len);  // s is still valid
}

fn calculate_length(s: &String) -> usize {
    s.len()  // s is not owned, so it's not dropped
}
}

很多新手阶段的修法，说白了就是一句话：别拿走，先借。
当然也不是所有地方都该借，有些地方就该清清楚楚地转交所有权。但只要函数只是读一下数据，不打算接管生命周期，那借用通常就是更自然的设计。

Memory Management: GC vs RAII
内存管理：GC 与 RAII 对照

C# Garbage Collection
C# 垃圾回收

// C# - Automatic memory management
public class Person
{
    public string Name { get; set; }
    public List<string> Hobbies { get; set; } = new List<string>();
    
    public void AddHobby(string hobby)
    {
        Hobbies.Add(hobby);  // Memory allocated automatically
    }
    
    // No explicit cleanup needed - GC handles it
    // But IDisposable pattern for resources
}

using var file = new FileStream("data.txt", FileMode.Open);
// 'using' ensures Dispose() is called

Rust Ownership and RAII
Rust 的所有权与 RAII

#![allow(unused)]
fn main() {
// Rust - Compile-time memory management
pub struct Person {
    name: String,
    hobbies: Vec<String>,
}

impl Person {
    pub fn add_hobby(&mut self, hobby: String) {
        self.hobbies.push(hobby);  // Memory management tracked at compile time
    }
    
    // Drop trait automatically implemented - cleanup is guaranteed
    // Compare to C#'s IDisposable:
    //   C#:   using var file = new FileStream(...)    // Dispose() called at end of using block
    //   Rust: let file = File::open(...)?             // drop() called at end of scope — no 'using' needed
}

// RAII - Resource Acquisition Is Initialization
{
    let file = std::fs::File::open("data.txt")?;
    // File automatically closed when 'file' goes out of scope
    // No 'using' statement needed - handled by type system
}
}

Rust 不是“没有内存管理”，而是把很多管理工作前置到了编译期。
GC 的优势是省心，代价是运行时开销和清理时机不确定；RAII 的优势是确定性强、零运行时成本，代价是得先把所有权和借用这套脑回路练出来。

graph TD
    subgraph "C# Memory Management"
        CS_ALLOC["Object Allocation<br/>new Person()"]
        CS_HEAP["Managed Heap<br/>托管堆"]
        CS_REF["References point to heap<br/>引用指向堆对象"]
        CS_GC_CHECK["GC periodically checks<br/>for unreachable objects<br/>周期性扫描不可达对象"]
        CS_SWEEP["Mark and sweep<br/>标记清扫"]
        CS_PAUSE["[ERROR] GC pause times<br/>可能有停顿"]
        
        CS_ALLOC --> CS_HEAP
        CS_HEAP --> CS_REF
        CS_REF --> CS_GC_CHECK
        CS_GC_CHECK --> CS_SWEEP
        CS_SWEEP --> CS_PAUSE
        
        CS_ISSUES["[ERROR] Non-deterministic cleanup<br/>[ERROR] Memory pressure<br/>[ERROR] Finalization complexity<br/>[OK] Easy to use"]
    end
    
    subgraph "Rust Ownership System"
        RUST_ALLOC["Value Creation<br/>Person { ... }"]
        RUST_OWNER["Single owner<br/>单一拥有者"]
        RUST_BORROW["Borrowing system<br/>&T, &mut T"]
        RUST_SCOPE["Scope-based cleanup<br/>Drop trait"]
        RUST_COMPILE["Compile-time verification<br/>编译期验证"]
        
        RUST_ALLOC --> RUST_OWNER
        RUST_OWNER --> RUST_BORROW
        RUST_BORROW --> RUST_SCOPE
        RUST_SCOPE --> RUST_COMPILE
        
        RUST_BENEFITS["[OK] Deterministic cleanup<br/>[OK] Zero runtime cost<br/>[OK] No memory leaks by default<br/>[ERROR] Learning curve"]
    end
    
    style CS_ISSUES fill:#ffebee,color:#000
    style RUST_BENEFITS fill:#e8f5e8,color:#000
    style CS_PAUSE fill:#ffcdd2,color:#000
    style RUST_COMPILE fill:#c8e6c9,color:#000

#![allow(unused)]
fn main() {
// 1. Move after use
fn problem_1() {
    let name = String::from("Alice");
    let greeting = format!("Hello, {name}!");
    let upper = name.to_uppercase();  // hint: borrow instead of move
    println!("{greeting} — {upper}");
}

// 2. Mutable + immutable borrow overlap
fn problem_2() {
    let mut numbers = vec![1, 2, 3];
    let first = &numbers[0];
    numbers.push(4);            // hint: reorder operations
    println!("first = {first}");
}

// 3. Returning a reference to a local
fn problem_3() -> String {
    let s = String::from("hello");
    s   // hint: return owned value, not &str
}
}

#![allow(unused)]
fn main() {
// 1. format! already borrows — the fix is that format! takes a reference.
//    The original code actually compiles! But if we had `let greeting = name;`
//    then fix by using &name:
fn solution_1() {
    let name = String::from("Alice");
    let greeting = format!("Hello, {}!", &name); // borrow
    let upper = name.to_uppercase();             // name still valid
    println!("{greeting} — {upper}");
}

// 2. Use the immutable borrow before the mutable operation:
fn solution_2() {
    let mut numbers = vec![1, 2, 3];
    let first = numbers[0]; // copy the i32 value (i32 is Copy)
    numbers.push(4);
    println!("first = {first}");
}

// 3. Return the owned String (already correct — common beginner confusion):
fn solution_3() -> String {
    let s = String::from("hello");
    s // ownership transferred to caller — this is the correct pattern
}
}

Memory Safety Deep Dive §§ZH§§ 内存安全深入解析

References vs Pointers
引用与指针

What you’ll learn: Rust references vs C# pointers and unsafe contexts, lifetime basics, and why compile-time safety proofs are stronger than C#’s runtime checks (bounds checking, null guards).
本章将学到什么： Rust 引用和 C# 指针、unsafe 场景之间的区别，生命周期基础，以及为什么 Rust 的编译期安全证明通常比 C# 运行时检查更强。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

C# Pointers (Unsafe Context)
C# 的指针与 unsafe 上下文

// C# unsafe pointers (rarely used)
unsafe void UnsafeExample()
{
    int value = 42;
    int* ptr = &value;  // Pointer to value
    *ptr = 100;         // Dereference and modify
    Console.WriteLine(value);  // 100
}

在 C# 里，指针并不是主流日常工具。大部分业务代码压根碰不到，只有进到 unsafe 上下文才会露面。
这背后其实也说明一件事：C# 的常规安全模型主要靠运行时和 GC 撑着，裸指针属于“确实知道自己在干嘛时才去碰”的区域。

Rust References (Safe by Default)
Rust 引用：默认就是安全的

#![allow(unused)]
fn main() {
// Rust references (always safe)
fn safe_example() {
    let mut value = 42;
    let ptr = &mut value;  // Mutable reference
    *ptr = 100;           // Dereference and modify
    println!("{}", value); // 100
}

// No "unsafe" keyword needed - borrow checker ensures safety
}

Rust 这里看上去也有“像指针一样可以解引用的东西”，但本质不是一回事。&T 和 &mut T 是受类型系统和借用检查器保护的引用，不是随便乱飞的裸地址。
也正因为如此，大多数场景根本不需要 unsafe，编译器已经把很多越界操作和悬垂引用直接卡死了。

Lifetime Basics for C# Developers
给 C# 开发者看的生命周期基础

// C# - Can return references that might become invalid
public class LifetimeIssues
{
    public string GetFirstWord(string input)
    {
        return input.Split(' ')[0];  // Returns new string (safe)
    }
    
    public unsafe char* GetFirstChar(string input)
    {
        // This would be dangerous - returning pointer to managed memory
        fixed (char* ptr = input)
            return ptr;  // ❌ Bad: ptr becomes invalid after method ends
    }
}

#![allow(unused)]
fn main() {
// Rust - Lifetime checking prevents dangling references
fn get_first_word(input: &str) -> &str {
    input.split_whitespace().next().unwrap_or("")
    // ✅ Safe: returned reference has same lifetime as input
}

fn invalid_reference() -> &str {
    let temp = String::from("hello");
    &temp  // ❌ Compile error: temp doesn't live long enough
    // temp would be dropped at end of function
}

fn valid_reference() -> String {
    let temp = String::from("hello");
    temp  // ✅ Works: ownership is transferred to caller
}
}

生命周期这玩意让不少 C# 开发者第一次看 Rust 时头都大，但它说穿了就是：编译器在追踪“这个引用到底能活多久”。
如果返回的引用指向一个函数里马上就会被释放的局部值，Rust 直接编译报错，根本不给跑到线上再悬垂的机会。

Memory Safety: Runtime Checks vs Compile-Time Proofs
内存安全：运行时兜底与编译期证明

C# - Runtime Safety Net
C#：运行时安全网

// C# relies on runtime checks and GC
public class Buffer
{
    private byte[] data;
    
    public Buffer(int size)
    {
        data = new byte[size];
    }
    
    public void ProcessData(int index)
    {
        // Runtime bounds checking
        if (index >= data.Length)
            throw new IndexOutOfRangeException();
            
        data[index] = 42;  // Safe, but checked at runtime
    }
    
    // Memory leaks still possible with events/static references
    public static event Action<string> GlobalEvent;
    
    public void Subscribe()
    {
        GlobalEvent += HandleEvent;  // Can create memory leaks
        // Forgot to unsubscribe - object won't be collected
    }
    
    private void HandleEvent(string message) { /* ... */ }
    
    // Null reference exceptions are still possible
    public void ProcessUser(User user)
    {
        Console.WriteLine(user.Name.ToUpper());  // NullReferenceException if user.Name is null
    }
    
    // Array access can fail at runtime
    public int GetValue(int[] array, int index)
    {
        return array[index];  // IndexOutOfRangeException possible
    }
}

Rust - Compile-Time Guarantees
Rust：编译期保证

#![allow(unused)]
fn main() {
struct Buffer {
    data: Vec<u8>,
}

impl Buffer {
    fn new(size: usize) -> Self {
        Buffer {
            data: vec![0; size],
        }
    }
    
    fn process_data(&mut self, index: usize) {
        // Bounds checking can be optimized away by compiler when proven safe
        if let Some(item) = self.data.get_mut(index) {
            *item = 42;  // Safe access, proven at compile time
        }
        // Or use indexing with explicit bounds check:
        // self.data[index] = 42;  // Panics in debug, but memory-safe
    }
    
    // Memory leaks impossible - ownership system prevents them
    fn process_with_closure<F>(&mut self, processor: F) 
    where F: FnOnce(&mut Vec<u8>)
    {
        processor(&mut self.data);
        // When processor goes out of scope, it's automatically cleaned up
        // No way to create dangling references or memory leaks
    }
    
    // Null pointer dereferences impossible - no null pointers!
    fn process_user(&self, user: &User) {
        println!("{}", user.name.to_uppercase());  // user.name cannot be null
    }
    
    // Array access is bounds-checked or explicitly unsafe
    fn get_value(array: &[i32], index: usize) -> Option<i32> {
        array.get(index).copied()  // Returns None if out of bounds
    }
    
    // Or explicitly unsafe if you know what you're doing:
    /// # Safety
    /// `index` must be less than `array.len()`.
    unsafe fn get_value_unchecked(array: &[i32], index: usize) -> i32 {
        *array.get_unchecked(index)  // Fast but must prove bounds manually
    }
}

struct User {
    name: String,  // String cannot be null in Rust
}

// Ownership prevents use-after-free
fn ownership_example() {
    let data = vec![1, 2, 3, 4, 5];
    let reference = &data[0];  // Borrow data
    
    // drop(data);  // ERROR: cannot drop while borrowed
    println!("{}", reference);  // This is guaranteed safe
}

// Borrowing prevents data races
fn borrowing_example(data: &mut Vec<i32>) {
    let first = &data[0];  // Immutable borrow
    // data.push(6);  // ERROR: cannot mutably borrow while immutably borrowed
    println!("{}", first);  // Guaranteed no data race
}
}

这里的差别得抓准：C# 更像是“程序跑起来时，运行时帮忙看着点”；Rust 则是“很多事在程序没跑之前，编译器就已经替着审完了”。
例如空引用、越界访问、借用期间修改底层容器这类问题，Rust 会尽量前移到编译阶段解决，而不是等到线上抛异常。

graph TD
    subgraph "C# Runtime Safety"
        CS_RUNTIME["Runtime Checks"]
        CS_GC["Garbage Collector"]
        CS_EXCEPTIONS["Exception Handling"]
        CS_BOUNDS["Runtime bounds checking"]
        CS_NULL["Null reference exceptions"]
        CS_LEAKS["Memory leaks possible"]
        CS_OVERHEAD["Performance overhead"]
        
        CS_RUNTIME --> CS_BOUNDS
        CS_RUNTIME --> CS_NULL
        CS_GC --> CS_LEAKS
        CS_EXCEPTIONS --> CS_OVERHEAD
    end
    
    subgraph "Rust Compile-Time Safety"
        RUST_OWNERSHIP["Ownership System"]
        RUST_BORROWING["Borrow Checker"]
        RUST_TYPES["Type System"]
        RUST_ZERO_COST["Zero-cost abstractions"]
        RUST_NO_NULL["No null pointers"]
        RUST_NO_LEAKS["No memory leaks"]
        RUST_FAST["Optimal performance"]
        
        RUST_OWNERSHIP --> RUST_NO_LEAKS
        RUST_BORROWING --> RUST_NO_NULL
        RUST_TYPES --> RUST_ZERO_COST
        RUST_ZERO_COST --> RUST_FAST
    end
    
    style CS_NULL fill:#ffcdd2,color:#000
    style CS_LEAKS fill:#ffcdd2,color:#000
    style CS_OVERHEAD fill:#fff3e0,color:#000
    style RUST_NO_NULL fill:#c8e6c9,color:#000
    style RUST_NO_LEAKS fill:#c8e6c9,color:#000
    style RUST_FAST fill:#c8e6c9,color:#000

这图说白了就是一句话：C# 靠运行时安全网，Rust 靠编译期契约。前者上手更温和，后者约束更硬。
代价当然也有，Rust 在写代码时会更较真，但换来的结果是很多 bug 类别会被整批干掉。

Exercises
练习

public List<int> GetEvenNumbers(List<int> numbers)
{
    var result = new List<int>();
    foreach (var n in numbers)
    {
        if (n % 2 == 0)
        {
            result.Add(n);
            numbers.Remove(n);  // Bug: modifying collection while iterating
        }
    }
    return result;
}

fn get_even_numbers(numbers: &mut Vec<i32>) -> Vec<i32> {
    let mut result = Vec::new();
    for &n in numbers.iter() {
        if n % 2 == 0 {
            result.push(n);
            // numbers.retain(|&x| x != n);
            // ❌ ERROR: cannot borrow `*numbers` as mutable because
            //    it is also borrowed as immutable (by the iterator)
        }
    }
    result
}

// Idiomatic Rust: use partition or retain
fn get_even_numbers_idiomatic(numbers: &mut Vec<i32>) -> Vec<i32> {
    let evens: Vec<i32> = numbers.iter().copied().filter(|n| n % 2 == 0).collect();
    numbers.retain(|n| n % 2 != 0); // remove evens after iteration
    evens
}

fn main() {
    let mut nums = vec![1, 2, 3, 4, 5, 6];
    let evens = get_even_numbers_idiomatic(&mut nums);
    assert_eq!(evens, vec![2, 4, 6]);
    assert_eq!(nums, vec![1, 3, 5]);
}

Lifetimes Deep Dive §§ZH§§ 生命周期深入解析

Lifetimes: Telling the Compiler How Long References Live
生命周期：告诉编译器引用能活多久

What you’ll learn: Why lifetimes exist, how lifetime annotation syntax works, what elision rules do for you, how structs borrow data, what 'static really means, and how to fix common borrow checker errors.
本章将学到什么： 生命周期为什么存在，生命周期标注语法怎么读，省略规则替人做了什么，结构体借用数据时该怎么写，'static 真正表示什么，以及几类常见借用检查器报错该怎么修。

Difficulty: 🔴 Advanced
难度： 🔴 高级

C# developers almost never think about the lifetime of a reference. The garbage collector tracks reachability and keeps objects alive as needed. Rust has no GC, so the compiler needs proof that every reference is valid for as long as it is used. Lifetimes are that proof.
写 C# 的时候，几乎不会盯着“某个引用到底还能活多久”这种问题发愁。GC 会追踪可达性，能活多久它自己兜着。Rust 没有 GC，所以编译器必须提前拿到证据，确认每个引用在被使用期间始终有效。生命周期就是这份证据。

Why Lifetimes Exist
为什么会有生命周期

#![allow(unused)]
fn main() {
// This won't compile — the compiler can't prove the returned reference is valid
fn longest(a: &str, b: &str) -> &str {
    if a.len() > b.len() { a } else { b }
}
// ERROR: missing lifetime specifier
// The compiler does not know whether the output borrows from `a` or `b`
}

The function body is obvious to a human, but not to the compiler. Returning a reference means Rust must know which input that output is tied to. Without that relationship being stated, the compiler refuses to guess.
这段函数对人来说很直白，但对编译器来说还差关键信息。只要返回的是引用，Rust 就必须知道这个输出到底和哪个输入绑在一起。这个关系没写清楚，编译器就不会替代码瞎猜。

Lifetime Annotations
生命周期标注

// Lifetime 'a says: the returned reference lives at least as long as both inputs
fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() > b.len() { a } else { b }
}

fn main() {
    let result;
    let string1 = String::from("long string");
    {
        let string2 = String::from("xyz");
        result = longest(&string1, &string2);
        println!("Longest: {result}"); // both references still valid here
    }
    // println!("{result}"); // ERROR: string2 doesn't live long enough
}

The annotation does not extend any lifetime. It only describes the relationship: the returned reference cannot outlive the shorter of the two inputs.
这个标注不会凭空把什么东西“续命”。它只是描述关系：返回值绝对不会比两个输入里更短的那个活得更久。

C# Comparison
和 C# 的对照

// C# — GC keeps objects alive while references remain reachable
string Longest(string a, string b) => a.Length > b.Length ? a : b;

// No lifetime annotations needed
// But also no compile-time proof about borrowing relationships

Lifetime Elision Rules
生命周期省略规则

Most of the time, explicit lifetime annotations are not needed because the compiler applies three elision rules automatically:
大多数时候，其实不用手写生命周期，因为编译器会自动应用三条省略规则：

#![allow(unused)]
fn main() {
// Equivalent — the compiler inserts lifetimes automatically
fn first_word(s: &str) -> &str { /* ... */ }           // elided
fn first_word<'a>(s: &'a str) -> &'a str { /* ... */ } // explicit

// But this requires explicit annotation — two inputs, one borrowed output
fn longest<'a>(a: &'a str, b: &'a str) -> &'a str { /* ... */ }
}

Struct Lifetimes
结构体里的生命周期

// A struct that borrows data rather than owning it
struct Excerpt<'a> {
    text: &'a str,
}

impl<'a> Excerpt<'a> {
    fn new(text: &'a str) -> Self {
        Excerpt { text }
    }

    fn first_sentence(&self) -> &str {
        self.text.split('.').next().unwrap_or(self.text)
    }
}

fn main() {
    let novel = String::from("Call me Ishmael. Some years ago...");
    let excerpt = Excerpt::new(&novel);
    println!("First sentence: {}", excerpt.first_sentence());
}

class Excerpt
{
    public string Text { get; }
    public Excerpt(string text) => Text = text;
    public string FirstSentence() => Text.Split('.')[0];
}

A struct that stores references must always carry explicit lifetime parameters. There is no elision shortcut for stored borrows, because the compiler needs the relationship written directly into the type.
只要结构体里存的是引用，就一定得显式带生命周期参数。这里没有什么省略捷径，因为编译器需要把这种借用关系直接写进类型本身。

The 'static Lifetime
'static 生命周期

#![allow(unused)]
fn main() {
// 'static means the value can remain valid for the entire program
let s: &'static str = "I'm a string literal";

// Common places you see 'static:
// 1. string literals
// 2. global constants
// 3. thread::spawn closures
std::thread::spawn(move || {
    println!("{s}");
});

// 'static does NOT mean "magically immortal"
let owned = String::from("hello");
// owned is not 'static, but it can be moved into a thread
}

'static is easy to overuse. It does not mean “make this live forever.” It means “this value is valid for as long as the whole program could need it.” Many values do not need that constraint, and forcing 'static where it is unnecessary usually makes APIs worse.
'static 特别容易被滥用。它不是“把这个东西变成永生”，而是“这个值在整个程序期间都可以保持有效”。很多值根本不需要这么强的约束，没事硬塞一个 'static，通常只会把 API 搞得更别扭。

Common Borrow Checker Errors and Fixes
常见借用检查器报错与修法

Visualizing Lifetime Scopes
把生命周期作用域画出来

graph TD
    subgraph "Scope Visualization<br/>作用域示意"
        direction TB
        A["fn main()"] --> B["let s1 = String::from('hello')"]
        B --> C["{ // inner scope<br/>内层作用域"]
        C --> D["let s2 = String::from('world')"]
        D --> E["let r = longest(&s1, &s2)"]
        E --> F["println!('{r}') both alive<br/>这里两者都还活着"]
        F --> G["} // s2 dropped here<br/>这里 s2 被释放"]
        G --> H["println!('{r}') error<br/>这里就出错了"]
    end

    style F fill:#c8e6c9,color:#000
    style H fill:#ffcdd2,color:#000

Multiple Lifetime Parameters
多个生命周期参数

Sometimes inputs come from different sources and should not be forced to share the same lifetime:
有些时候，多个输入来自不同来源，本来就不该被强行绑成同一个生命周期：

// Two independent lifetimes: output borrows only from 'a
fn first_with_context<'a, 'b>(data: &'a str, _context: &'b str) -> &'a str {
    data.split(',').next().unwrap_or(data)
}

fn main() {
    let data = String::from("alice,bob,charlie");
    let result;
    {
        let context = String::from("user lookup");
        result = first_with_context(&data, &context);
    }
    println!("{result}");
}

string FirstWithContext(string data, string context) => data.Split(',')[0];

Rust can express “the output borrows from A but not from B” directly in the type signature. GC languages usually do not need to express that relationship, but they also cannot prove it statically.
Rust 可以把“输出借用自 A，但和 B 没关系”这种信息直接写进类型签名。GC 语言通常不需要表达这种关系，但也因此无法在编译期证明它。

Real-World Lifetime Patterns
真实代码里的生命周期模式

Pattern 1: Iterator returning references
模式 1：返回引用的迭代结果

#![allow(unused)]
fn main() {
struct CsvRow<'a> {
    fields: Vec<&'a str>,
}

fn parse_csv_line(line: &str) -> CsvRow<'_> {
    CsvRow {
        fields: line.split(',').collect(),
    }
}
}

Pattern 2: Return owned when in doubt
模式 2：拿不准就先返回拥有型数据

#![allow(unused)]
fn main() {
fn format_greeting(first: &str, last: &str) -> String {
    format!("Hello, {first} {last}!")
}

// Borrow only when:
// 1. allocation cost matters
// 2. the lifetime relationship is clear
}

Pattern 3: Lifetime bounds on generics
模式 3：泛型上的生命周期约束

#![allow(unused)]
fn main() {
fn store_reference<'a, T: 'a>(cache: &mut Vec<&'a T>, item: &'a T) {
    cache.push(item);
}

fn make_printer<'a>(text: &'a str) -> Box<dyn std::fmt::Display + 'a> {
    Box::new(text)
}
}

When to Reach for 'static
什么时候才该用 'static

#![allow(unused)]
fn main() {
struct Config {
    db_url: String,
    api_key: String,
}

// TODO: Add lifetime annotations
fn get_connection_info(config: &Config) -> (&str, &str) {
    (&config.db_url, &config.api_key)
}

// TODO: This struct borrows from Config — add lifetime parameter
struct ConnectionInfo {
    db_url: &str,
    api_key: &str,
}
}

#![allow(unused)]
fn main() {
struct Config {
    db_url: String,
    api_key: String,
}

// Rule 2 applies: one input lifetime is assigned to outputs
fn get_connection_info(config: &Config) -> (&str, &str) {
    (&config.db_url, &config.api_key)
}

struct ConnectionInfo<'a> {
    db_url: &'a str,
    api_key: &'a str,
}

fn make_info<'a>(config: &'a Config) -> ConnectionInfo<'a> {
    ConnectionInfo {
        db_url: &config.db_url,
        api_key: &config.api_key,
    }
}
}

Smart Pointers — Beyond Single Ownership §§ZH§§ 智能指针：超越单一所有权

Smart Pointers: When Single Ownership Isn’t Enough
智能指针：当单一所有权已经不够用时

What you’ll learn: Box<T>, Rc<T>, Arc<T>, Cell<T>, RefCell<T>, and Cow<'a, T> — when to use each, how they compare to C#’s GC-managed references, Drop as Rust’s IDisposable, Deref coercion, and a decision tree for choosing the right smart pointer.
本章将学到什么： Box<T>、Rc<T>、Arc<T>、Cell<T>、RefCell<T> 和 Cow<'a, T> 各自该在什么场景使用，它们和 C# 垃圾回收引用的差别，Drop 如何对应 Rust 里的 IDisposable 思想，什么是 Deref 强制解引用，以及如何用决策树挑对智能指针。

Difficulty: 🔴 Advanced
难度： 🔴 高级

In C#, almost every object is effectively managed through GC-backed references. In Rust, single ownership is the default. But once shared ownership, heap allocation, or interior mutability enters the picture, smart pointers become the real toolset.
在 C# 里，几乎所有对象最终都托管在 GC 管理的引用体系下。Rust 则把单一所有权当默认模型。一旦碰到共享所有权、堆分配或者内部可变性，智能指针这一套家伙才算正式上场。

Box<T> — Simple Heap Allocation
Box<T>：最直接的堆分配

#![allow(unused)]
fn main() {
// Stack allocation (default in Rust)
let x = 42;           // on the stack

// Heap allocation with Box
let y = Box::new(42); // on the heap, like C# `new int(42)` (boxed)
println!("{}", y);    // auto-derefs: prints 42

// Common use: recursive types (can't know size at compile time)
#[derive(Debug)]
enum List {
    Cons(i32, Box<List>),  // Box gives a known pointer size
    Nil,
}

let list = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil))));
}

// C# — everything on the heap already (reference types)
// Box<T> is only needed in Rust because stack is the default
var list = new LinkedListNode<int>(1);  // always heap-allocated

Rc<T> — Shared Ownership (Single Thread)
Rc<T>：单线程共享所有权

#![allow(unused)]
fn main() {
use std::rc::Rc;

// Multiple owners of the same data — like multiple C# references
let shared = Rc::new(vec![1, 2, 3]);
let clone1 = Rc::clone(&shared); // reference count: 2
let clone2 = Rc::clone(&shared); // reference count: 3

println!("Count: {}", Rc::strong_count(&shared)); // 3
// Data is dropped when last Rc goes out of scope

// Common use: shared configuration, graph nodes, tree structures
}

Arc<T> — Shared Ownership (Thread-Safe)
Arc<T>：线程安全的共享所有权

#![allow(unused)]
fn main() {
use std::sync::Arc;
use std::thread;

// Arc = Atomic Reference Counting — safe to share across threads
let data = Arc::new(vec![1, 2, 3]);

let handles: Vec<_> = (0..3).map(|i| {
    let data = Arc::clone(&data);
    thread::spawn(move || {
        println!("Thread {i}: {:?}", data);
    })
}).collect();

for h in handles { h.join().unwrap(); }
}

// C# — all references are thread-safe by default (GC handles it)
var data = new List<int> { 1, 2, 3 };
// Can share freely across threads (but mutation is still unsafe!)

Cell<T> and RefCell<T> — Interior Mutability
Cell<T> 与 RefCell<T>：内部可变性

#![allow(unused)]
fn main() {
use std::cell::RefCell;

// Sometimes you need to mutate data behind a shared reference.
// RefCell moves borrow checking from compile time to runtime.
struct Logger {
    entries: RefCell<Vec<String>>,
}

impl Logger {
    fn new() -> Self {
        Logger { entries: RefCell::new(Vec::new()) }
    }

    fn log(&self, msg: &str) { // &self, not &mut self!
        self.entries.borrow_mut().push(msg.to_string());
    }

    fn dump(&self) {
        for entry in self.entries.borrow().iter() {
            println!("{entry}");
        }
    }
}
// RefCell panics at runtime if borrow rules are violated
// Use sparingly — prefer compile-time checking when possible
}

RefCell<T> is the classic escape hatch when mutation has to happen behind &self. The trade-off is brutal and simple: compile-time guarantees are traded for runtime checks, and violations become panics.
RefCell<T> 就是那种“明明手里只有 &self，但还非改不可”时的逃生门。代价也很直白：把原本的编译期保证换成运行时检查，一旦借用规则被破坏，程序就会 panic。

Cow<’a, str> — Clone on Write
Cow<'a, str>：写时复制

#![allow(unused)]
fn main() {
use std::borrow::Cow;

// Sometimes you have a &str that MIGHT need to become a String
fn normalize(input: &str) -> Cow<'_, str> {
    if input.contains('\t') {
        // Only allocate when we need to modify
        Cow::Owned(input.replace('\t', "    "))
    } else {
        // Borrow the original — zero allocation
        Cow::Borrowed(input)
    }
}

let clean = normalize("hello");           // Cow::Borrowed — no allocation
let dirty = normalize("hello\tworld");    // Cow::Owned — allocated
// Both can be used as &str via Deref
println!("{clean} / {dirty}");
}

Drop: Rust’s IDisposable
Drop：Rust 里的 IDisposable 对应物

In C#, IDisposable plus using takes care of resource cleanup. In Rust, the equivalent idea is the Drop trait, but the important distinction is that cleanup is automatic rather than opt-in.
在 C# 里，资源回收往往靠 IDisposable 配合 using。Rust 里对应的是 Drop trait，但最大的差别在于：Rust 的清理是自动发生的，不需要额外记得去“进入某个模式”。

// C# — must remember to use 'using' or call Dispose()
using var file = File.OpenRead("data.bin");
// Dispose() called at end of scope

// Forgetting 'using' is a resource leak!
var file2 = File.OpenRead("data.bin");
// GC will eventually finalize, but timing is unpredictable

// Rust — Drop runs automatically when value goes out of scope
{
    let file = File::open("data.bin")?;
    // use file...
}   // file.drop() called HERE, deterministically — no 'using' needed

// Custom Drop (like implementing IDisposable)
struct TempFile {
    path: std::path::PathBuf,
}

impl Drop for TempFile {
    fn drop(&mut self) {
        // Guaranteed to run when TempFile goes out of scope
        let _ = std::fs::remove_file(&self.path);
        println!("Cleaned up {:?}", self.path);
    }
}

fn main() {
    let tmp = TempFile { path: "scratch.tmp".into() };
    // ... use tmp ...
}   // scratch.tmp deleted automatically here

Key difference from C#: In Rust, every type can have deterministic cleanup. Nothing relies on “remembering to call Dispose later”. Once the owner leaves scope, Drop runs. This is classic RAII.
和 C# 最大的差别： 在 Rust 里，任何类型都可以拥有确定性的清理时机。不会再靠“回头记得调用 Dispose”这种人肉纪律。所有者一出作用域，Drop 就执行。这就是经典 RAII。

Rule: If a type owns a resource such as a file handle, network connection, lock guard, or temporary file, implement Drop. The ownership system guarantees it runs exactly once.
经验法则： 只要类型里握着文件句柄、网络连接、锁守卫、临时文件这类资源，就该认真考虑 Drop。所有权系统会保证它只执行一次。

Deref Coercion: Automatic Smart Pointer Unwrapping
Deref 强制解引用：自动拆开智能指针

Rust automatically unwraps smart pointers when calling methods or passing values to functions. This is called Deref coercion.
Rust 在调用方法和传参时，会自动帮忙拆开智能指针，这就叫 Deref coercion。

#![allow(unused)]
fn main() {
let boxed: Box<String> = Box::new(String::from("hello"));

// Deref coercion chain: Box<String> -> String -> str
println!("Length: {}", boxed.len());   // calls str::len() — auto-deref!

fn greet(name: &str) {
    println!("Hello, {name}");
}

let s = String::from("Alice");
greet(&s);       // &String -> &str via Deref coercion
greet(&boxed);   // &Box<String> -> &String -> &str — two levels!
}

// C# has no true equivalent
// The closest thing is user-defined implicit conversion operators

Why this matters: APIs can accept &str rather than &String, &[T] rather than &Vec<T>, and &T rather than &Box<T>. Call sites stay clean, and ownership details do not leak all over every function signature.
这为什么重要： 这样 API 就能统一接收 &str 而不是 &String，接收 &[T] 而不是 &Vec<T>，接收 &T 而不是 &Box<T>。调用点更干净，所有权细节也不用污染每个函数签名。

Rc vs Arc: When to Use Which
Rc 和 Arc 到底怎么选

Rule of thumb: Start with Rc. If the compiler complains that the value must cross threads or be Send + Sync, that is the signal to move to Arc.
简单经验： 先从 Rc 开始。编译器一旦开始提醒“这玩意儿要跨线程”或者“需要 Send + Sync”，那就说明该上 Arc 了。

Decision Tree: Which Smart Pointer?
决策树：到底该选哪个智能指针

graph TD
    START["Need shared ownership<br/>or heap allocation?<br/>需要共享所有权<br/>或者堆分配吗？"]
    HEAP["Just need heap allocation?<br/>只是需要堆分配吗？"]
    SHARED["Shared ownership needed?<br/>需要共享所有权吗？"]
    THREADED["Shared across threads?<br/>会跨线程共享吗？"]
    MUTABLE["Need interior mutability?<br/>需要内部可变性吗？"]
    MAYBE_OWN["Sometimes borrowed,<br/>sometimes owned?<br/>有时借用，有时拥有吗？"]

    BOX["Use Box&lt;T&gt;<br/>用 Box&lt;T&gt;"]
    RC["Use Rc&lt;T&gt;<br/>用 Rc&lt;T&gt;"]
    ARC["Use Arc&lt;T&gt;<br/>用 Arc&lt;T&gt;"]
    REFCELL["Use RefCell&lt;T&gt;<br/>or Rc&lt;RefCell&lt;T&gt;&gt;<br/>用 RefCell&lt;T&gt;<br/>或 Rc&lt;RefCell&lt;T&gt;&gt;"]
    MUTEX["Use Arc&lt;Mutex&lt;T&gt;&gt;<br/>用 Arc&lt;Mutex&lt;T&gt;&gt;"]
    COW["Use Cow&lt;'a, T&gt;<br/>用 Cow&lt;'a, T&gt;"]
    OWN["Use owned type<br/>(String, Vec, etc.)<br/>直接使用拥有所有权的类型"]

    START -->|Yes<br/>是| HEAP
    START -->|No<br/>否| OWN
    HEAP -->|Yes<br/>是| BOX
    HEAP -->|Shared<br/>共享| SHARED
    SHARED -->|Single thread<br/>单线程| RC
    SHARED -->|Multi thread<br/>多线程| THREADED
    THREADED -->|Read only<br/>只读| ARC
    THREADED -->|Read + write<br/>可读可写| MUTEX
    RC -->|Need mutation?<br/>还要修改？| MUTABLE
    MUTABLE -->|Yes<br/>是| REFCELL
    MAYBE_OWN -->|Yes<br/>是| COW

    style BOX fill:#e3f2fd,color:#000
    style RC fill:#e8f5e8,color:#000
    style ARC fill:#c8e6c9,color:#000
    style REFCELL fill:#fff3e0,color:#000
    style MUTEX fill:#fff3e0,color:#000
    style COW fill:#e3f2fd,color:#000
    style OWN fill:#f5f5f5,color:#000

Crates and Modules §§ZH§§ crate 与模块

Modules and Crates: Code Organization
模块与 crate：代码组织方式

What you’ll learn: Rust’s module system vs C# namespaces and assemblies, pub/pub(crate)/pub(super) visibility, file-based module organization, and how crates map to .NET assemblies.
本章将学到什么： Rust 的模块系统和 C# 命名空间、程序集之间的对应关系，pub / pub(crate) / pub(super) 这几种可见性，基于文件的模块组织方式，以及 crate 如何映射到 .NET 程序集。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Understanding Rust’s module system is essential for organizing code and managing dependencies. For C# developers, this is analogous to understanding namespaces, assemblies, and NuGet packages.
想把 Rust 项目组织得顺，模块系统是绕不过去的。对 C# 开发者来说，可以把它类比成命名空间、程序集和 NuGet 包这几层概念叠在一起理解。

Rust Modules vs C# Namespaces
Rust 模块与 C# 命名空间

C# Namespace Organization
C# 的命名空间组织方式

// File: Models/User.cs
namespace MyApp.Models
{
    public class User
    {
        public string Name { get; set; }
        public int Age { get; set; }
    }
}

// File: Services/UserService.cs
using MyApp.Models;

namespace MyApp.Services
{
    public class UserService
    {
        public User CreateUser(string name, int age)
        {
            return new User { Name = name, Age = age };
        }
    }
}

// File: Program.cs
using MyApp.Models;
using MyApp.Services;

namespace MyApp
{
    class Program
    {
        static void Main(string[] args)
        {
            var service = new UserService();
            var user = service.CreateUser("Alice", 30);
        }
    }
}

Rust Module Organization
Rust 的模块组织方式

// File: src/models.rs
pub struct User {
    pub name: String,
    pub age: u32,
}

impl User {
    pub fn new(name: String, age: u32) -> User {
        User { name, age }
    }
}

// File: src/services.rs
use crate::models::User;

pub struct UserService;

impl UserService {
    pub fn create_user(name: String, age: u32) -> User {
        User::new(name, age)
    }
}

// File: src/lib.rs (or main.rs)
pub mod models;
pub mod services;

use models::User;
use services::UserService;

fn main() {
    let service = UserService;
    let user = UserService::create_user("Alice".to_string(), 30);
}

从感觉上说，C# 的命名空间更像“逻辑分组”；Rust 的模块除了分组，还直接参与可见性和编译结构的塑形。
也就是说，Rust 模块不是纯标签，它会真实决定哪些名字能被看到，哪些实现能被复用。

Module Hierarchy and Visibility
模块层级与可见性

graph TD
    Crate["crate (root)<br/>crate 根"] --> ModA["mod data<br/>data 模块"]
    Crate --> ModB["mod api<br/>api 模块"]
    ModA --> SubA1["pub struct Repo<br/>完全公开"]
    ModA --> SubA2["fn helper<br/>私有"]
    ModB --> SubB1["pub fn handle()<br/>公开"]
    ModB --> SubB2["pub(crate) fn internal()<br/>crate 内公开"]
    ModB --> SubB3["pub(super) fn parent_only()<br/>仅父模块可见"]

    style SubA1 fill:#c8e6c9,color:#000
    style SubA2 fill:#ffcdd2,color:#000
    style SubB1 fill:#c8e6c9,color:#000
    style SubB2 fill:#fff9c4,color:#000
    style SubB3 fill:#fff9c4,color:#000

🟢 Green = public everywhere  |  🟡 Yellow = restricted visibility  |  🔴 Red = private
🟢 绿色表示完全公开，🟡 黄色表示受限公开，🔴 红色表示私有。

C# Visibility Modifiers
C# 的可见性修饰符

namespace MyApp.Data
{
    public class Repository
    {
        private string connectionString;
        internal void Connect() { }
        protected virtual void Initialize() { }
        public void Save(object data) { }
    }
}

Rust Visibility Rules
Rust 的可见性规则

#![allow(unused)]
fn main() {
// Everything is private by default in Rust
mod data {
    struct Repository {
        connection_string: String,
    }
    
    impl Repository {
        fn new() -> Repository {
            Repository {
                connection_string: "localhost".to_string(),
            }
        }
        
        pub fn connect(&self) {
        }
        
        pub(crate) fn initialize(&self) {
        }
        
        pub(super) fn internal_method(&self) {
        }
    }
    
    pub struct PublicRepository {
        pub data: String,
        private_data: String,
    }
}

pub use data::PublicRepository;
}

Rust 这里有个很重要的直觉差异：默认私有，而且私有是按模块边界来算，不是按类边界来算。
所以一个 API 是否暴露出去，往往先看模块树怎么切，再看 pub 怎么标，而不是先去找“类上写了什么修饰符”。

Module File Organization
模块文件组织方式

C# Project Structure
C# 的项目结构

MyApp/
├── MyApp.csproj
├── Models/
│   ├── User.cs
│   └── Product.cs
├── Services/
│   ├── UserService.cs
│   └── ProductService.cs
├── Controllers/
│   └── ApiController.cs
└── Program.cs

Rust Module File Structure
Rust 的模块文件结构

my_app/
├── Cargo.toml
└── src/
    ├── main.rs (or lib.rs)
    ├── models/
    │   ├── mod.rs
    │   ├── user.rs
    │   └── product.rs
    ├── services/
    │   ├── mod.rs
    │   ├── user_service.rs
    │   └── product_service.rs
    └── controllers/
        ├── mod.rs
        └── api_controller.rs

Module Declaration Patterns
模块声明模式

#![allow(unused)]
fn main() {
// src/models/mod.rs
pub mod user;
pub mod product;

pub use user::User;
pub use product::Product;

// src/main.rs
mod models;
mod services;

use models::{User, Product};
use services::UserService;

// Or import the entire module
use models::user::*;
}

Rust 这套文件布局一开始会让 C# 开发者有点疑惑，因为文件名、目录名和 mod 声明是绑定在一起的。
但一旦习惯后，好处也很明显：代码结构和可见性边界通常能保持一致，不容易东一块西一块地散掉。

Crates vs .NET Assemblies
crate 与 .NET 程序集

Understanding Crates
怎么理解 crate

In Rust, a crate is the fundamental unit of compilation and distribution, similar to how an assembly works in .NET.
在 Rust 里，crate 是最基础的编译与分发单位。对 C# 开发者来说，可以先把它类比成 .NET 里的 assembly。

C# Assembly Model
C# 的程序集模型

// MyLibrary.dll - Compiled assembly
namespace MyLibrary
{
    public class Calculator
    {
        public int Add(int a, int b) => a + b;
    }
}

// MyApp.exe - Executable assembly that references MyLibrary.dll
using MyLibrary;

class Program
{
    static void Main()
    {
        var calc = new Calculator();
        Console.WriteLine(calc.Add(2, 3));
    }
}

Rust Crate Model
Rust 的 crate 模型

# Cargo.toml for library crate
[package]
name = "my_calculator"
version = "0.1.0"
edition = "2021"

[lib]
name = "my_calculator"

#![allow(unused)]
fn main() {
// src/lib.rs - Library crate
pub struct Calculator;

impl Calculator {
    pub fn add(&self, a: i32, b: i32) -> i32 {
        a + b
    }
}
}

# Cargo.toml for binary crate that uses the library
[package]
name = "my_app"
version = "0.1.0"
edition = "2021"

[dependencies]
my_calculator = { path = "../my_calculator" }

// src/main.rs - Binary crate
use my_calculator::Calculator;

fn main() {
    let calc = Calculator;
    println!("{}", calc.add(2, 3));
}

Crate Types Comparison
crate 类型对照

Workspace vs Solution
workspace 与 solution

C# Solution Structure
C# 的 solution 结构

<Solution>
    <Project Include="WebApi/WebApi.csproj" />
    <Project Include="Business/Business.csproj" />
    <Project Include="DataAccess/DataAccess.csproj" />
    <Project Include="Tests/Tests.csproj" />
</Solution>

Rust Workspace Structure
Rust 的 workspace 结构

# Cargo.toml at workspace root
[workspace]
members = [
    "web_api",
    "business",
    "data_access",
    "tests"
]

[workspace.dependencies]
serde = "1.0"
tokio = "1.0"

# web_api/Cargo.toml
[package]
name = "web_api"
version = "0.1.0"
edition = "2021"

[dependencies]
business = { path = "../business" }
serde = { workspace = true }
tokio = { workspace = true }

Rust 的 workspace 和 C# solution 很像，都是多项目管理容器。
但 Rust 这里还有一个挺实用的点：[workspace.dependencies] 能把公共依赖版本统一收住，免得每个子 crate 各写各的，最后版本飘得乱七八糟。

Exercises
练习

namespace MyApp.Services { public class AuthService { } }
namespace MyApp.Services { internal class TokenStore { } }
namespace MyApp.Models { public class User { } }
namespace MyApp.Models { public class Session { } }

src/
├── lib.rs
├── services/
│   ├── mod.rs
│   ├── auth_service.rs
│   └── token_store.rs
└── models/
    ├── mod.rs
    ├── user.rs
    └── session.rs

// src/lib.rs
pub mod services;
pub mod models;

// src/services/mod.rs
mod token_store;
pub mod auth_service;

// src/services/auth_service.rs
use super::token_store::TokenStore;

pub struct AuthService;

impl AuthService {
    pub fn login(&self) { /* uses TokenStore internally */ }
}

// src/services/token_store.rs
pub(super) struct TokenStore;

// src/models/mod.rs
pub mod user;
pub mod session;

// src/models/user.rs
pub struct User {
    pub name: String,
}

// src/models/session.rs
pub struct Session {
    pub user_id: u64,
}

Package Management — Cargo vs NuGet §§ZH§§ 包管理：Cargo 与 NuGet 对比

Package Management: Cargo vs NuGet
包管理：Cargo 与 NuGet 对照

What you’ll learn: Cargo.toml vs .csproj, version specifiers, Cargo.lock, feature flags for conditional compilation, and common Cargo commands mapped to their NuGet/dotnet equivalents.
本章将学到什么： Cargo.toml 和 .csproj 的对应关系，版本约束写法，Cargo.lock 的作用，条件编译里的 feature flag，以及常见 Cargo 命令和 NuGet / dotnet 命令之间的映射。

Difficulty: 🟢 Beginner
难度： 🟢 入门

Dependency Declaration
依赖声明

C# NuGet Dependencies
C# 的 NuGet 依赖

<!-- MyApp.csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>
  
  <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageReference Include="Serilog" Version="3.0.1" />
  <PackageReference Include="Microsoft.AspNetCore.App" />
  
  <ProjectReference Include="../MyLibrary/MyLibrary.csproj" />
</Project>

Rust Cargo Dependencies
Rust 的 Cargo 依赖

# Cargo.toml
[package]
name = "my_app"
version = "0.1.0"
edition = "2021"

[dependencies]
serde_json = "1.0"               # From crates.io (like NuGet)
serde = { version = "1.0", features = ["derive"] }  # With features
log = "0.4"
tokio = { version = "1.0", features = ["full"] }

# Local dependencies (like ProjectReference)
my_library = { path = "../my_library" }

# Git dependencies
my_git_crate = { git = "https://github.com/user/repo" }

# Development dependencies (like test packages)
[dev-dependencies]
criterion = "0.5"               # Benchmarking
proptest = "1.0"               # Property testing

Version Management
版本管理

C# Package Versioning
C# 的包版本管理

<!-- Centralized package management (Directory.Packages.props) -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  
  <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
  <PackageVersion Include="Serilog" Version="3.0.1" />
</Project>

<!-- packages.lock.json for reproducible builds -->

Rust Version Management
Rust 的版本管理

# Cargo.toml - Semantic versioning
[dependencies]
serde = "1.0"        # Compatible with 1.x.x (>=1.0.0, <2.0.0)
log = "0.4.17"       # Compatible with 0.4.x (>=0.4.17, <0.5.0)
regex = "=1.5.4"     # Exact version
chrono = "^0.4"      # Caret requirements (default)
uuid = "~1.3.0"      # Tilde requirements (>=1.3.0, <1.4.0)

# Cargo.lock - Exact versions for reproducible builds (auto-generated)
[[package]]
name = "serde"
version = "1.0.163"
# ... exact dependency tree

Package Sources
包源

C# Package Sources
C# 的包源

<!-- nuget.config -->
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="MyCompanyFeed" value="https://pkgs.dev.azure.com/company/_packaging/feed/nuget/v3/index.json" />
  </packageSources>
</configuration>

Rust Package Sources
Rust 的包源

# .cargo/config.toml
[source.crates-io]
replace-with = "my-awesome-registry"

[source.my-awesome-registry]
registry = "https://my-intranet:8080/index"

# Alternative registries
[registries]
my-registry = { index = "https://my-intranet:8080/index" }

# In Cargo.toml
[dependencies]
my_crate = { version = "1.0", registry = "my-registry" }

Common Commands Comparison
常用命令对照

Features: Conditional Compilation
Feature：条件编译

C# Conditional Compilation
C# 条件编译

#if DEBUG
    Console.WriteLine("Debug mode");
#elif RELEASE
    Console.WriteLine("Release mode");
#endif

// Project file features
<PropertyGroup Condition="'$(Configuration)'=='Debug'">
    <DefineConstants>DEBUG;TRACE</DefineConstants>
</PropertyGroup>

Rust Feature Gates
Rust 的 Feature Gate

# Cargo.toml
[features]
default = ["json"]              # Default features
json = ["serde_json"]          # Feature that enables serde_json
xml = ["serde_xml"]            # Alternative serialization
advanced = ["json", "xml"]     # Composite feature

[dependencies]
serde_json = { version = "1.0", optional = true }
serde_xml = { version = "0.4", optional = true }

#![allow(unused)]
fn main() {
// Conditional compilation based on features
#[cfg(feature = "json")]
use serde_json;

#[cfg(feature = "xml")]
use serde_xml;

pub fn serialize_data(data: &MyStruct) -> String {
    #[cfg(feature = "json")]
    return serde_json::to_string(data).unwrap();
    
    #[cfg(feature = "xml")]
    return serde_xml::to_string(data).unwrap();
    
    #[cfg(not(any(feature = "json", feature = "xml")))]
    return "No serialization feature enabled".to_string();
}
}

Using External Crates
使用外部 crate

Popular Crates for C# Developers
适合 C# 开发者的常见 crate

Example: HTTP Client Migration
示例：HTTP 客户端迁移

// C# HttpClient usage
public class ApiClient
{
    private readonly HttpClient _httpClient;
    
    public async Task<User> GetUserAsync(int id)
    {
        var response = await _httpClient.GetAsync($"/users/{id}");
        var json = await response.Content.ReadAsStringAsync();
        return JsonConvert.DeserializeObject<User>(json);
    }
}

#![allow(unused)]
fn main() {
// Rust reqwest usage
use reqwest;
use serde::Deserialize;

#[derive(Deserialize)]
struct User {
    id: u32,
    name: String,
}

struct ApiClient {
    client: reqwest::Client,
}

impl ApiClient {
    async fn get_user(&self, id: u32) -> Result<User, reqwest::Error> {
        let user = self.client
            .get(&format!("https://api.example.com/users/{}", id))
            .send()
            .await?
            .json::<User>()
            .await?;
        
        Ok(user)
    }
}
}

Workspaces vs Monorepos
Workspace 与 Monorepo

Python Monorepo (typical)
Python 里的典型 Monorepo

# Python monorepo (various approaches, no standard)
myproject/
├── pyproject.toml           # Root project
├── packages/
│   ├── core/
│   │   ├── pyproject.toml   # Each package has its own config
│   │   └── src/core/...
│   ├── api/
│   │   ├── pyproject.toml
│   │   └── src/api/...
│   └── cli/
│       ├── pyproject.toml
│       └── src/cli/...
# Tools: poetry workspaces, pip -e ., uv workspaces — no standard

Rust Workspace
Rust Workspace

# Rust — Cargo.toml at root
[workspace]
members = [
    "core",
    "api",
    "cli",
]

# Shared dependencies across workspace
[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }

# Rust workspace structure — standardized, built into Cargo
myproject/
├── Cargo.toml               # Workspace root
├── Cargo.lock               # Single lock file for all crates
├── core/
│   ├── Cargo.toml            # [dependencies] serde.workspace = true
│   └── src/lib.rs
├── api/
│   ├── Cargo.toml
│   └── src/lib.rs
└── cli/
    ├── Cargo.toml
    └── src/main.rs

# Workspace commands
cargo build                  # Build everything
cargo test                   # Test everything
cargo build -p core          # Build just the core crate
cargo test -p api            # Test just the api crate
cargo clippy --all           # Lint everything

Key insight: Rust workspaces are first-class, built into Cargo. Python monorepos require third-party tools (poetry, uv, pants) with varying levels of support. In a Rust workspace, all crates share a single Cargo.lock, ensuring consistent dependency versions across the project.
关键认识：Rust 的 workspace 是 Cargo 一等公民，原生就支持。Python 的 monorepo 通常得靠 poetry、uv、pants 这类第三方工具，支持程度参差不齐。Rust workspace 里所有 crate 共用一个 Cargo.lock，因此整仓依赖版本始终一致。

Exercises
练习

mod kitchen {
    fn secret_recipe() -> &'static str { "42 spices" }
    pub fn menu() -> &'static str { "Today's special" }

    pub mod staff {
        pub fn cook() -> String {
            format!("Cooking with {}", super::secret_recipe())
        }
    }
}

fn main() {
    println!("{}", kitchen::menu());             // Line A
    println!("{}", kitchen::secret_recipe());     // Line B
    println!("{}", kitchen::staff::cook());       // Line C
}

Error Handling §§ZH§§ 错误处理

Exceptions vs Result<T, E>
异常与 Result<T, E> 的对照

What you’ll learn: Why Rust replaces exceptions with Result<T, E> and Option<T>, how the ? operator keeps propagation concise, and why explicit error handling removes the hidden control flow common in C# try / catch code.
本章将学习： Rust 为什么用 Result<T, E> 和 Option<T> 取代异常，? 怎样让错误传播保持简洁，以及显式错误处理为什么能消除 C# try / catch 代码里常见的隐藏控制流。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

See also: Crate-Level Error Types for production-oriented error patterns with thiserror and anyhow, and Essential Crates for the wider error-handling ecosystem.
延伸阅读： Crate 级错误类型 会介绍面向生产环境的 thiserror 与 anyhow 用法，核心 Crate 会继续展开错误处理生态。

C# Exception-Based Error Handling
C# 的异常式错误处理

// C# - Exception-based error handling
public class UserService
{
    public User GetUser(int userId)
    {
        if (userId <= 0)
        {
            throw new ArgumentException("User ID must be positive");
        }

        var user = database.FindUser(userId);
        if (user == null)
        {
            throw new UserNotFoundException($"User {userId} not found");
        }

        return user;
    }

    public async Task<string> GetUserEmailAsync(int userId)
    {
        try
        {
            var user = GetUser(userId);
            return user.Email ?? throw new InvalidOperationException("User has no email");
        }
        catch (UserNotFoundException ex)
        {
            logger.Warning("User not found: {UserId}", userId);
            return "noreply@company.com";
        }
        catch (Exception ex)
        {
            logger.Error(ex, "Unexpected error getting user email");
            throw; // Re-throw
        }
    }
}

Rust Result-Based Error Handling
Rust 基于 Result 的错误处理

#![allow(unused)]
fn main() {
use std::fmt;

#[derive(Debug)]
pub enum UserError {
    InvalidId(i32),
    NotFound(i32),
    NoEmail,
    DatabaseError(String),
}

impl fmt::Display for UserError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            UserError::InvalidId(id) => write!(f, "Invalid user ID: {}", id),
            UserError::NotFound(id) => write!(f, "User {} not found", id),
            UserError::NoEmail => write!(f, "User has no email address"),
            UserError::DatabaseError(msg) => write!(f, "Database error: {}", msg),
        }
    }
}

impl std::error::Error for UserError {}

pub struct UserService {
    // database connection, etc.
}

impl UserService {
    pub fn get_user(&self, user_id: i32) -> Result<User, UserError> {
        if user_id <= 0 {
            return Err(UserError::InvalidId(user_id));
        }

        self.database_find_user(user_id)
            .ok_or(UserError::NotFound(user_id))
    }

    pub fn get_user_email(&self, user_id: i32) -> Result<String, UserError> {
        let user = self.get_user(user_id)?;

        user.email
            .ok_or(UserError::NoEmail)
    }

    pub fn get_user_email_or_default(&self, user_id: i32) -> String {
        match self.get_user_email(user_id) {
            Ok(email) => email,
            Err(UserError::NotFound(_)) => {
                log::warn!("User not found: {}", user_id);
                "noreply@company.com".to_string()
            }
            Err(err) => {
                log::error!("Error getting user email: {}", err);
                "error@company.com".to_string()
            }
        }
    }
}
}

In C#, failure can jump out of a method at runtime by throwing. In Rust, the function signature itself says whether failure is possible and what form it takes.
在 C# 里，失败可以通过抛异常在运行时突然从方法里跳出去；而在 Rust 里，函数签名会提前说明“这里可能失败”，以及“失败会长成什么样”。

graph TD
    subgraph "C# Exception Model<br/>C# 异常模型"
        CS_CALL["Method Call<br/>方法调用"]
        CS_SUCCESS["Success Path<br/>成功路径"]
        CS_EXCEPTION["throw Exception<br/>抛出异常"]
        CS_STACK["Stack unwinding<br/>栈展开"]
        CS_CATCH["try/catch block<br/>捕获异常"]
        CS_HIDDEN["[ERROR] Hidden control flow<br/>[ERROR] Runtime cost<br/>[ERROR] Easy to ignore<br/>隐藏控制流、运行时成本、容易漏看"]

        CS_CALL --> CS_SUCCESS
        CS_CALL --> CS_EXCEPTION
        CS_EXCEPTION --> CS_STACK
        CS_STACK --> CS_CATCH
        CS_EXCEPTION --> CS_HIDDEN
    end

    subgraph "Rust Result Model<br/>Rust Result 模型"
        RUST_CALL["Function Call<br/>函数调用"]
        RUST_OK["Ok(value)"]
        RUST_ERR["Err(error)"]
        RUST_MATCH["match result"]
        RUST_QUESTION["? operator<br/>提前返回"]
        RUST_EXPLICIT["[OK] Explicit handling<br/>[OK] No hidden flow<br/>[OK] Hard to ignore<br/>显式处理、无隐藏分支、难以忽略"]

        RUST_CALL --> RUST_OK
        RUST_CALL --> RUST_ERR
        RUST_OK --> RUST_MATCH
        RUST_ERR --> RUST_MATCH
        RUST_ERR --> RUST_QUESTION
        RUST_MATCH --> RUST_EXPLICIT
        RUST_QUESTION --> RUST_EXPLICIT
    end

    style CS_HIDDEN fill:#ffcdd2,color:#000
    style RUST_EXPLICIT fill:#c8e6c9,color:#000
    style CS_STACK fill:#fff3e0,color:#000
    style RUST_QUESTION fill:#c8e6c9,color:#000

The ? Operator: Propagating Errors Concisely
? 运算符：简洁地向上传播错误

// C# - Exception propagation (implicit)
public async Task<string> ProcessFileAsync(string path)
{
    var content = await File.ReadAllTextAsync(path);
    var processed = ProcessContent(content);
    return processed;
}

#![allow(unused)]
fn main() {
fn process_file(path: &str) -> Result<String, ConfigError> {
    let content = read_config(path)?;
    let processed = process_content(&content)?;
    Ok(processed)
}

fn process_content(content: &str) -> Result<String, ConfigError> {
    if content.is_empty() {
        Err(ConfigError::InvalidFormat)
    } else {
        Ok(content.to_uppercase())
    }
}
}

The practical effect is similar to letting an exception bubble up, but ? is visible in the source and only works when the return type already admits failure.
从效果上看，? 和“让异常继续往上冒”有点像，但它会明确写在源码里，而且只有当函数返回类型本来就允许失败时才能使用。

Option<T> for Nullable Values
用 Option<T> 处理可空值

// C# - Nullable reference types
public string? FindUserName(int userId)
{
    var user = database.FindUser(userId);
    return user?.Name;
}

public void ProcessUser(int userId)
{
    string? name = FindUserName(userId);
    if (name != null)
    {
        Console.WriteLine($"User: {name}");
    }
    else
    {
        Console.WriteLine("User not found");
    }
}

#![allow(unused)]
fn main() {
fn find_user_name(user_id: u32) -> Option<String> {
    if user_id == 1 {
        Some("Alice".to_string())
    } else {
        None
    }
}

fn process_user(user_id: u32) {
    match find_user_name(user_id) {
        Some(name) => println!("User: {}", name),
        None => println!("User not found"),
    }

    if let Some(name) = find_user_name(user_id) {
        println!("User: {}", name);
    } else {
        println!("User not found");
    }
}
}

Rust splits “optional value” and “error value” into Option<T> and Result<T, E>. That separation removes a huge amount of ambiguity that often accumulates in nullable APIs.
Rust 会把“值可能不存在”和“调用发生错误”分别交给 Option<T> 与 Result<T, E> 表达。这种拆分能消掉可空 API 里常见的大量歧义。

Combining Option and Result
把 Option 和 Result 组合起来

fn safe_divide(a: f64, b: f64) -> Option<f64> {
    if b != 0.0 {
        Some(a / b)
    } else {
        None
    }
}

fn parse_and_divide(a_str: &str, b_str: &str) -> Result<Option<f64>, ParseFloatError> {
    let a: f64 = a_str.parse()?;
    let b: f64 = b_str.parse()?;
    Ok(safe_divide(a, b))
}

use std::num::ParseFloatError;

fn main() {
    match parse_and_divide("10.0", "2.0") {
        Ok(Some(result)) => println!("Result: {}", result),
        Ok(None) => println!("Division by zero"),
        Err(error) => println!("Parse error: {}", error),
    }
}

This pattern is common: Result says the operation itself may fail, while Option inside it says the successful operation may legitimately produce “no value”.
这种嵌套很常见：外层 Result 表示操作本身可能失败，内层 Option 表示即便操作成功，也可能合理地产生“没有值”这个结果。

#![allow(unused)]
fn main() {
use std::io;

// TODO: Define AppError with variants:
//   Io(io::Error), Json(serde_json::Error), Validation(String)
// TODO: Implement Display and Error traits
// TODO: Implement From<io::Error> and From<serde_json::Error>
// TODO: Define type alias: type Result<T> = std::result::Result<T, AppError>;

fn load_config(path: &str) -> Result<Config> {
    let content = std::fs::read_to_string(path)?;
    let config: Config = serde_json::from_str(&content)?;
    if config.name.is_empty() {
        return Err(AppError::Validation("name cannot be empty".into()));
    }
    Ok(config)
}
}

#![allow(unused)]
fn main() {
use std::io;
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("I/O error: {0}")]
    Io(#[from] io::Error),

    #[error("JSON error: {0}")]
    Json(#[from] serde_json::Error),

    #[error("Validation: {0}")]
    Validation(String),
}

pub type Result<T> = std::result::Result<T, AppError>;

#[derive(serde::Deserialize)]
struct Config {
    name: String,
    port: u16,
}

fn load_config(path: &str) -> Result<Config> {
    let content = std::fs::read_to_string(path)?;
    let config: Config = serde_json::from_str(&content)?;
    if config.name.is_empty() {
        return Err(AppError::Validation("name cannot be empty".into()));
    }
    Ok(config)
}
}

Crate-Level Error Types and Result Aliases §§ZH§§ crate 级错误类型与 Result 别名

Crate-Level Error Types and Result Aliases
crate 级错误类型与 Result 别名

What you’ll learn: The production pattern of defining a per-crate error enum with thiserror, creating a Result<T> type alias, and when to choose thiserror (libraries) vs anyhow (applications).
本章将学到什么： 在生产代码里如何为每个 crate 定义统一错误枚举，如何配合 thiserror 和 Result<T> 别名减掉样板代码，以及 thiserror 和 anyhow 到底该怎么选。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

A critical pattern for production Rust: define a per-crate error enum and a Result type alias to eliminate boilerplate.
生产级 Rust 里有个特别重要的套路：给当前 crate 定义一个统一错误枚举，再配一个 Result 类型别名。这样错误处理会规整很多，也能少写一堆重复签名。

The Pattern
基本模式

#![allow(unused)]
fn main() {
// src/error.rs
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("Database error: {0}")]
    Database(#[from] sqlx::Error),

    #[error("HTTP error: {0}")]
    Http(#[from] reqwest::Error),

    #[error("Serialization error: {0}")]
    Serialization(#[from] serde_json::Error),

    #[error("Validation error: {message}")]
    Validation { message: String },

    #[error("Not found: {entity} with id {id}")]
    NotFound { entity: String, id: String },
}

/// Crate-wide Result alias — every function returns this
pub type Result<T> = std::result::Result<T, AppError>;
}

这个模式的重点，是把“项目里到底可能出哪些业务错误、依赖错误、边界错误”统一摆到一个中心位置。
这样后面无论是数据库模块、HTTP 模块还是序列化模块，错误最终都会往同一套领域错误里收，不会每个地方各写各的口径。

Usage Throughout Your Crate
在整个 crate 里统一使用

#![allow(unused)]
fn main() {
use crate::error::{AppError, Result};

pub async fn get_user(id: Uuid) -> Result<User> {
    let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)
        .fetch_optional(&pool)
        .await?;  // sqlx::Error → AppError::Database via #[from]

    user.ok_or_else(|| AppError::NotFound {
        entity: "User".into(),
        id: id.to_string(),
    })
}

pub async fn create_user(req: CreateUserRequest) -> Result<User> {
    if req.name.trim().is_empty() {
        return Err(AppError::Validation {
            message: "Name cannot be empty".into(),
        });
    }
    // ...
}
}

这里 #[from] 的价值非常大。它让 ? 不只是“提前返回错误”，还顺手完成了“底层库错误自动映射到上层错误类型”这一步。
也就是说，sqlx::Error、reqwest::Error、serde_json::Error 这种底层错误可以自然抬升成当前 crate 的公共错误模型，代码会干净很多。

C# Comparison
和 C# 的对照

// C# equivalent pattern
public class AppException : Exception
{
    public string ErrorCode { get; }
    public AppException(string code, string message) : base(message)
    {
        ErrorCode = code;
    }
}

// But in C#, callers don't know what exceptions to expect!
// In Rust, the error type is in the function signature.

这就是 Rust 和 C# 错误模型一个非常显眼的差别。C# 里可以定义一堆异常类型，但调用方从函数签名里通常看不出具体会抛什么。
Rust 则把错误类型老老实实写进签名里，谁调用，谁就得明确面对这件事。没有“先跑起来再说，出问题靠异常满天飞”那种模糊地带。

Why This Matters
为什么这一套很重要

• thiserror generates Display and Error impls automatically
  thiserror 会自动生成 Display 和 Error 实现。
• #[from] enables the ? operator to convert library errors automatically
  #[from] 让 ? 可以自动完成底层错误到上层错误的转换。
• The Result<T> alias means every function signature is clean: fn foo() -> Result<Bar>
Result<T> 别名能让函数签名更干净，例如直接写成 fn foo() -> Result<Bar>。
• Unlike C# exceptions, callers see all possible error variants in the type
  和 C# 异常不同，调用方能从类型里直接看到错误模型的边界。

这种统一错误模型，带来的不只是“好看”。它会直接影响 API 可读性、模块边界、测试编写方式以及后续日志和监控上报的一致性。
项目一旦变大，没有统一错误层，后面十有八九会变成一锅粥。

thiserror vs anyhow: When to Use Which
thiserror 和 anyhow 到底怎么选

Two crates dominate Rust error handling. Choosing between them is the first decision you’ll make:
Rust 错误处理里最常见的两套工具就是 thiserror 和 anyhow。很多项目一上来就得先做这个选择：

#![allow(unused)]
fn main() {
// thiserror — for LIBRARIES (callers need to match on error variants)
use thiserror::Error;

#[derive(Error, Debug)]
pub enum StorageError {
    #[error("File not found: {path}")]
    NotFound { path: String },

    #[error("Permission denied: {0}")]
    PermissionDenied(String),

    #[error(transparent)]
    Io(#[from] std::io::Error),
}

pub fn read_config(path: &str) -> Result<String, StorageError> {
    std::fs::read_to_string(path).map_err(|e| match e.kind() {
        std::io::ErrorKind::NotFound => StorageError::NotFound { path: path.into() },
        std::io::ErrorKind::PermissionDenied => StorageError::PermissionDenied(path.into()),
        _ => StorageError::Io(e),
    })
}
}

// anyhow — for APPLICATIONS (just propagate errors, don't define types)
use anyhow::{Context, Result};

fn main() -> Result<()> {
    let config = std::fs::read_to_string("config.toml")
        .context("Failed to read config file")?;

    let port: u16 = config.parse()
        .context("Failed to parse port number")?;

    println!("Listening on port {port}");
    Ok(())
}
// anyhow::Result<T> = Result<T, anyhow::Error>
// .context() adds human-readable context to any error

// C# comparison:
// thiserror ≈ defining custom exception classes with specific properties
// anyhow ≈ catching Exception and wrapping with message:
//   throw new InvalidOperationException("Failed to read config", ex);

Guideline: If your code is a library (other code calls it), use thiserror. If your code is an application (the final binary), use anyhow. Many projects use both — thiserror for the library crate’s public API, anyhow in the main() binary.
经验建议： 如果代码是库，也就是会被别的代码依赖调用，优先用 thiserror；如果代码是最终应用程序，尤其是 main() 侧，优先用 anyhow。很多真实项目会两者一起用：库层暴露结构化错误，应用层用 anyhow 汇总和补充上下文。

Error Recovery Patterns
错误恢复模式

C# developers are used to try/catch blocks that recover from specific exceptions. Rust uses combinators on Result for the same purpose:
C# 开发者比较熟的是 try/catch。Rust 没有那套异常机制，常见替代写法是围着 Result 做组合和转换：

#![allow(unused)]
fn main() {
use std::fs;

// Pattern 1: Recover with a fallback value
let config = fs::read_to_string("config.toml")
    .unwrap_or_else(|_| String::from("port = 8080"));  // default if missing

// Pattern 2: Recover from specific errors, propagate others
fn read_or_create(path: &str) -> Result<String, std::io::Error> {
    match fs::read_to_string(path) {
        Ok(content) => Ok(content),
        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
            let default = String::from("# new file");
            fs::write(path, &default)?;
            Ok(default)
        }
        Err(e) => Err(e),  // propagate permission errors, etc.
    }
}

// Pattern 3: Add context before propagating
use anyhow::Context;

fn load_config() -> anyhow::Result<Config> {
    let text = fs::read_to_string("config.toml")
        .context("Failed to read config.toml")?;
    let config: Config = toml::from_str(&text)
        .context("Failed to parse config.toml")?;
    Ok(config)
}

// Pattern 4: Map errors to your domain type
fn parse_port(s: &str) -> Result<u16, AppError> {
    s.parse::<u16>()
        .map_err(|_| AppError::Validation {
            message: format!("Invalid port: {s}"),
        })
}
}

// C# equivalents:
try { config = File.ReadAllText("config.toml"); }
catch (FileNotFoundException) { config = "port = 8080"; }  // Pattern 1

try { /* ... */ }
catch (FileNotFoundException) { /* create file */ }        // Pattern 2
catch { throw; }                                            // re-throw others

When to recover vs propagate:
什么时候恢复，什么时候继续上抛：

• Recover when the error has a sensible default or retry strategy
  有合理默认值或重试策略时，可以就地恢复。
• Propagate with ? when the caller should decide what to do
  如果该由调用方决定后续行为，就用 ? 往上抛。
• Add context (.context()) at module boundaries to build an error trail
  跨模块边界时最好补上 .context()，把错误链说明白。

Rust 这套错误恢复方式乍看没有异常那么“潇洒”，但它的优点是路径透明。恢复逻辑、映射逻辑、补上下文的时机，全都明明白白写在代码里。
项目越复杂，这种显式性越值钱。

Exercises
练习

#![allow(unused)]
fn main() {
use thiserror::Error;

#[derive(Error, Debug)]
pub enum RegistrationError {
    #[error("Email already registered: {0}")]
    DuplicateEmail(String),

    #[error("Password too weak: {0}")]
    WeakPassword(String),

    #[error("Database error")]
    Database(#[from] sqlx::Error),

    #[error("Rate limited — retry after {retry_after_secs}s")]
    RateLimited { retry_after_secs: u64 },
}

pub type Result<T> = std::result::Result<T, RegistrationError>;

pub fn register_user(email: &str, password: &str) -> Result<()> {
    if password.len() < 8 {
        return Err(RegistrationError::WeakPassword(
            "must be at least 8 characters".into(),
        ));
    }

    // This ? converts sqlx::Error → RegistrationError::Database automatically
    // db.check_email_unique(email).await?;

    // This is explicit construction for domain logic
    if email.contains("+spam") {
        return Err(RegistrationError::DuplicateEmail(email.to_string()));
    }

    Ok(())
}
}

Traits and Generics §§ZH§§ Trait 与泛型

Traits - Rust’s Interfaces
Trait：Rust 里的接口机制

What you’ll learn: Traits compared with C# interfaces, default method implementations, trait objects (dyn Trait) versus generic bounds (impl Trait), derived traits, common standard-library traits, associated types, and operator overloading through traits.
本章将学到什么： 对照理解 Trait 和 C# 接口的关系，掌握默认方法实现、trait object dyn Trait 与泛型约束 impl Trait 的区别，理解自动派生 trait、常见标准库 trait、关联类型，以及如何通过 trait 实现运算符重载。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

Traits are Rust’s mechanism for describing shared behavior. They play a role similar to interfaces in C#, but they also stretch into areas that C# interfaces do not cover, such as operator overloading and associated types.
Trait 是 Rust 用来描述“共享行为”的核心机制。它和 C# 的接口确实有相似之处，但它能覆盖的范围更大，像运算符重载、关联类型这些能力，都直接建在 trait 体系上。

C# Interface Comparison
先和 C# 接口对照一下

// C# interface definition
public interface IAnimal
{
    string Name { get; }
    void MakeSound();
    
    // Default implementation (C# 8+)
    string Describe()
    {
        return $"{Name} makes a sound";
    }
}

// C# interface implementation
public class Dog : IAnimal
{
    public string Name { get; }
    
    public Dog(string name)
    {
        Name = name;
    }
    
    public void MakeSound()
    {
        Console.WriteLine("Woof!");
    }
    
    // Can override default implementation
    public string Describe()
    {
        return $"{Name} is a loyal dog";
    }
}

// Generic constraints
public void ProcessAnimal<T>(T animal) where T : IAnimal
{
    animal.MakeSound();
    Console.WriteLine(animal.Describe());
}

Rust Trait Definition and Implementation
Rust Trait 的定义与实现

// Trait definition
trait Animal {
    fn name(&self) -> &str;
    fn make_sound(&self);
    
    // Default implementation
    fn describe(&self) -> String {
        format!("{} makes a sound", self.name())
    }
    
    // Default implementation using other trait methods
    fn introduce(&self) {
        println!("Hi, I'm {}", self.name());
        self.make_sound();
    }
}

// Struct definition
#[derive(Debug)]
struct Dog {
    name: String,
    breed: String,
}

impl Dog {
    fn new(name: String, breed: String) -> Dog {
        Dog { name, breed }
    }
}

// Trait implementation
impl Animal for Dog {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn make_sound(&self) {
        println!("Woof!");
    }
    
    // Override default implementation
    fn describe(&self) -> String {
        format!("{} is a loyal {} dog", self.name, self.breed)
    }
}

// Another implementation
#[derive(Debug)]
struct Cat {
    name: String,
    indoor: bool,
}

impl Animal for Cat {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn make_sound(&self) {
        println!("Meow!");
    }
    
    // Use default describe() implementation
}

// Generic function with trait bounds
fn process_animal<T: Animal>(animal: &T) {
    animal.make_sound();
    println!("{}", animal.describe());
    animal.introduce();
}

// Multiple trait bounds
fn process_animal_debug<T: Animal + std::fmt::Debug>(animal: &T) {
    println!("Debug: {:?}", animal);
    process_animal(animal);
}

fn main() {
    let dog = Dog::new("Buddy".to_string(), "Golden Retriever".to_string());
    let cat = Cat { name: "Whiskers".to_string(), indoor: true };
    
    process_animal(&dog);
    process_animal(&cat);
    
    process_animal_debug(&dog);
}

看到这里，可以先把 Trait 暂时理解成“接口加一堆额外超能力”。
默认方法、基于 trait 的泛型约束、和其他 trait 组合使用，这些在 C# 里也有影子，但 Rust 把它们揉得更紧、更统一。

Trait Objects and Dynamic Dispatch
Trait Object 与动态分发

// C# dynamic polymorphism
public void ProcessAnimals(List<IAnimal> animals)
{
    foreach (var animal in animals)
    {
        animal.MakeSound(); // Dynamic dispatch
        Console.WriteLine(animal.Describe());
    }
}

// Usage
var animals = new List<IAnimal>
{
    new Dog("Buddy"),
    new Cat("Whiskers"),
    new Dog("Rex")
};

ProcessAnimals(animals);

// Rust trait objects for dynamic dispatch
fn process_animals(animals: &[Box<dyn Animal>]) {
    for animal in animals {
        animal.make_sound(); // Dynamic dispatch
        println!("{}", animal.describe());
    }
}

// Alternative: using references
fn process_animal_refs(animals: &[&dyn Animal]) {
    for animal in animals {
        animal.make_sound();
        println!("{}", animal.describe());
    }
}

fn main() {
    // Using Box<dyn Trait>
    let animals: Vec<Box<dyn Animal>> = vec![
        Box::new(Dog::new("Buddy".to_string(), "Golden Retriever".to_string())),
        Box::new(Cat { name: "Whiskers".to_string(), indoor: true }),
        Box::new(Dog::new("Rex".to_string(), "German Shepherd".to_string())),
    ];
    
    process_animals(&animals);
    
    // Using references
    let dog = Dog::new("Buddy".to_string(), "Golden Retriever".to_string());
    let cat = Cat { name: "Whiskers".to_string(), indoor: true };
    
    let animal_refs: Vec<&dyn Animal> = vec![&dog, &cat];
    process_animal_refs(&animal_refs);
}

这里就开始出现 Rust 独有的取舍题了：到底要静态分发，还是动态分发。
C# 开发者经常习惯“接口一套上，先跑起来再说”；Rust 则会逼着在抽象能力、分配成本、调用方式之间先做决定，这一点后面会越来越频繁出现。

Derived Traits
派生 Trait

// Automatically derive common traits
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct Person {
    name: String,
    age: u32,
}

// What this generates (simplified):
impl std::fmt::Debug for Person {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Person")
            .field("name", &self.name)
            .field("age", &self.age)
            .finish()
    }
}

impl Clone for Person {
    fn clone(&self) -> Self {
        Person {
            name: self.name.clone(),
            age: self.age,
        }
    }
}

impl PartialEq for Person {
    fn eq(&self, other: &Self) -> bool {
        self.name == other.name && self.age == other.age
    }
}

// Usage
fn main() {
    let person1 = Person {
        name: "Alice".to_string(),
        age: 30,
    };
    
    let person2 = person1.clone(); // Clone trait
    
    println!("{:?}", person1); // Debug trait
    println!("Equal: {}", person1 == person2); // PartialEq trait
}

derive 是 Rust 里非常香的一块。
很多通用能力比如调试打印、克隆、比较、哈希，结构体字段本身已经足够表达语义时，就没必要手写一大堆模板实现，直接 #[derive(...)] 最省力。

Common Standard Library Traits
常见标准库 Trait

use std::collections::HashMap;

// Display trait for user-friendly output
impl std::fmt::Display for Person {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} (age {})", self.name, self.age)
    }
}

// From trait for conversions
impl From<(String, u32)> for Person {
    fn from((name, age): (String, u32)) -> Self {
        Person { name, age }
    }
}

// Into trait is automatically implemented when From is implemented
fn create_person() {
    let person: Person = ("Alice".to_string(), 30).into();
    println!("{}", person);
}

// Iterator trait implementation
struct PersonIterator {
    people: Vec<Person>,
    index: usize,
}

impl Iterator for PersonIterator {
    type Item = Person;
    
    fn next(&mut self) -> Option<Self::Item> {
        if self.index < self.people.len() {
            let person = self.people[self.index].clone();
            self.index += 1;
            Some(person)
        } else {
            None
        }
    }
}

impl Person {
    fn iterator(people: Vec<Person>) -> PersonIterator {
        PersonIterator { people, index: 0 }
    }
}

fn main() {
    let people = vec![
        Person::from(("Alice".to_string(), 30)),
        Person::from(("Bob".to_string(), 25)),
        Person::from(("Charlie".to_string(), 35)),
    ];
    
    // Use our custom iterator
    for person in Person::iterator(people.clone()) {
        println!("{}", person); // Uses Display trait
    }
}

这部分很值得建立“trait 是生态接线口”的感觉。
只要实现了对应 trait，类型就能自动接入标准库和常见惯用法。例如实现 Display 就能优雅打印，实现 From 就能进转换链，实现 Iterator 就能进 for 循环和迭代器生态。

use std::f64::consts::PI;

trait Drawable {
    fn area(&self) -> f64;

    fn draw(&self) {
        println!("Drawing shape with area {:.2}", self.area());
    }
}

struct Circle { radius: f64 }
struct Rect   { w: f64, h: f64 }

impl Drawable for Circle {
    fn area(&self) -> f64 { PI * self.radius * self.radius }
}

impl Drawable for Rect {
    fn area(&self) -> f64 { self.w * self.h }
}

fn total_area(shapes: &[Box<dyn Drawable>]) -> f64 {
    shapes.iter().map(|s| s.area()).sum()
}

fn main() {
    let shapes: Vec<Box<dyn Drawable>> = vec![
        Box::new(Circle { radius: 5.0 }),
        Box::new(Rect { w: 4.0, h: 6.0 }),
        Box::new(Circle { radius: 2.0 }),
    ];
    for s in &shapes { s.draw(); }
    println!("Total area: {:.2}", total_area(&shapes));
}

Associated Types: Traits With Type Members
关联类型：Trait 里的类型成员

C# interfaces do not have a direct associated-type concept, but Rust traits do. The classic example is Iterator.
C# 接口里没有和“关联类型”完全对等的原生概念，而 Rust trait 有。最经典的例子就是 Iterator。

#![allow(unused)]
fn main() {
// The Iterator trait has an associated type 'Item'
trait Iterator {
    type Item;                         // Each implementor defines what Item is
    fn next(&mut self) -> Option<Self::Item>;
}

struct Counter { max: u32, current: u32 }

impl Iterator for Counter {
    type Item = u32;                   // This Counter yields u32 values
    fn next(&mut self) -> Option<u32> {
        if self.current < self.max {
            self.current += 1;
            Some(self.current)
        } else {
            None
        }
    }
}
}

In C#, IEnumerator<T> or IEnumerable<T> use generic parameters for this role. Rust’s associated types tie the type member to the implementation itself, which often makes trait bounds easier to read.
在 C# 里，IEnumerator<T>、IEnumerable<T> 主要靠泛型参数解决这个问题；Rust 的关联类型则把“这个实现到底产出什么类型”直接绑定在实现上。这样一来，很多约束写出来会更短、更清楚。

Operator Overloading via Traits
通过 Trait 做运算符重载

In C#, operator overloading is done by defining static operator methods. In Rust, every operator maps to a trait in std::ops.
C# 里写运算符重载，通常是定义静态 operator 方法；Rust 则是把每个运算符都映射成 std::ops 里的某个 trait。

#![allow(unused)]
fn main() {
use std::ops::Add;

#[derive(Debug, Clone, Copy)]
struct Vec2 { x: f64, y: f64 }

impl Add for Vec2 {
    type Output = Vec2;
    fn add(self, rhs: Vec2) -> Vec2 {
        Vec2 { x: self.x + rhs.x, y: self.y + rhs.y }
    }
}

let a = Vec2 { x: 1.0, y: 2.0 };
let b = Vec2 { x: 3.0, y: 4.0 };
let c = a + b;  // calls <Vec2 as Add>::add(a, b)
}

这部分再次说明了一件事：Trait 在 Rust 里不只是“面向对象接口”，它还是语言运算规则的挂载点。
一旦理解这一层，很多看起来分散的能力，比如格式化、比较、加法、迭代、转换，就会突然串起来。

Coherence: The Orphan Rule
一致性规则：孤儿规则

You can only implement a trait if the current crate owns either the trait or the type. This prevents conflicting implementations across crates.
Rust 规定：只有在当前 crate 拥有这个 trait，或者拥有这个类型时，才能写对应实现。这个限制就是常说的孤儿规则，它的目标是避免不同 crate 之间出现互相冲突的实现。

#![allow(unused)]
fn main() {
// ✅ OK — you own MyType
impl Display for MyType { ... }

// ✅ OK — you own MyTrait
impl MyTrait for String { ... }

// ❌ ERROR — you own neither Display nor String
impl Display for String { ... }
}

C# 没有这一层限制，所以扩展方法可以随便往外加。
Rust 则更保守一些，宁可先把实现边界卡严，也不想让生态里不同库对同一个组合各写一套实现，然后把调用方整懵。

impl Trait: Returning Traits Without Boxing
impl Trait：不装箱也能返回 Trait

C# interfaces can always be used as return types, and the runtime takes care of dispatch and allocation. Rust makes the decision explicit: static dispatch with impl Trait, or dynamic dispatch with dyn Trait.
C# 里接口当返回类型是常规操作，运行时会把后续分发和对象布局兜住；Rust 则要求把这件事说清楚，到底是 impl Trait 的静态分发，还是 dyn Trait 的动态分发。

impl Trait in Argument Position (Shorthand for Generics)
参数位置上的 impl Trait（泛型语法糖）

#![allow(unused)]
fn main() {
// These two are equivalent:
fn print_animal(animal: &impl Animal) { animal.make_sound(); }
fn print_animal<T: Animal>(animal: &T)  { animal.make_sound(); }

// impl Trait is just syntactic sugar for a generic parameter
// The compiler generates a specialized copy for each concrete type (monomorphization)
}

这里的 impl Trait 主要是让签名更短、更顺眼。
本质上还是泛型，编译器照样会做单态化，不是什么新的运行时机制。

impl Trait in Return Position (The Key Difference)
返回位置上的 impl Trait（这里才是重点）

// Return an iterator without exposing the concrete type
fn even_squares(limit: u32) -> impl Iterator<Item = u32> {
    (0..limit)
        .filter(|n| n % 2 == 0)
        .map(|n| n * n)
}
// The caller sees "some type that implements Iterator<Item = u32>"
// The actual type (Filter<Map<Range<u32>, ...>>) is unnameable — impl Trait solves this.

fn main() {
    for n in even_squares(20) {
        print!("{n} ");
    }
    // Output: 0 4 16 36 64 100 144 196 256 324
}

// C# — returning an interface (always dynamic dispatch, heap-allocated iterator object)
public IEnumerable<int> EvenSquares(int limit) =>
    Enumerable.Range(0, limit)
        .Where(n => n % 2 == 0)
        .Select(n => n * n);
// The return type hides the concrete iterator behind the IEnumerable interface
// Unlike Rust's Box<dyn Trait>, C# doesn't explicitly box — the runtime handles allocation

这一块是很多 C# 开发者第一次真正意识到 Rust 抽象成本不是“系统替你决定”的时刻。
返回 impl Trait 意味着：类型虽然藏起来了，但编译器仍然知道它的具体身份，所以还能继续做静态优化。

Returning Closures: impl Fn vs Box<dyn Fn>
返回闭包：impl Fn 与 Box<dyn Fn>

#![allow(unused)]
fn main() {
// Return a closure — you CANNOT name the closure type, so impl Fn is essential
fn make_adder(x: i32) -> impl Fn(i32) -> i32 {
    move |y| x + y
}

let add5 = make_adder(5);
println!("{}", add5(3)); // 8

// If you need to return DIFFERENT closures conditionally, you need Box:
fn choose_op(add: bool) -> Box<dyn Fn(i32, i32) -> i32> {
    if add {
        Box::new(|a, b| a + b)
    } else {
        Box::new(|a, b| a * b)
    }
}
// impl Trait requires a SINGLE concrete type; different closures are different types
}

// C# — delegates handle this naturally (always heap-allocated)
Func<int, int> MakeAdder(int x) => y => x + y;
Func<int, int, int> ChooseOp(bool add) => add ? (a, b) => a + b : (a, b) => a * b;

这里最该记住的一句就是：impl Trait 只能代表一个具体类型。
如果分支里返回的是两个不同闭包，那它们在 Rust 看来就是两个完全不同的匿名类型，这时就得退回 Box<dyn Fn> 这种动态分发方案。

The Dispatch Decision: impl Trait vs dyn Trait vs Generics
分发选择：impl Trait、dyn Trait 还是泛型

This choice becomes an architectural question very quickly in Rust. The following diagram gives the rough mental map.
这件事在 Rust 里很快就会上升成架构选择题。下面这张图就是一份大致的脑图。

graph TD
    START["Function accepts or returns<br/>a trait-based type?<br/>函数参数或返回值涉及 Trait？"]
    POSITION["Argument or return position?<br/>是在参数位置还是返回位置？"]
    ARG_SAME["All callers pass<br/>the same type?<br/>调用者传入的具体类型是否固定？"]
    RET_SINGLE["Always returns the<br/>same concrete type?<br/>是否始终返回同一个具体类型？"]
    COLLECTION["Storing in a collection<br/>or as struct field?<br/>要不要放进集合或结构体字段？"]

    GENERIC["Use generics<br/><code>fn foo&lt;T: Trait&gt;(x: T)</code>"]
    IMPL_ARG["Use impl Trait<br/><code>fn foo(x: impl Trait)</code>"]
    IMPL_RET["Use impl Trait<br/><code>fn foo() -> impl Trait</code>"]
    DYN_BOX["Use Box&lt;dyn Trait&gt;<br/>Dynamic dispatch"]
    DYN_REF["Use &dyn Trait<br/>Borrowed dynamic dispatch"]

    START --> POSITION
    POSITION -->|Argument| ARG_SAME
    POSITION -->|Return| RET_SINGLE
    ARG_SAME -->|"Yes (syntactic sugar)"| IMPL_ARG
    ARG_SAME -->|"Complex bounds/multiple uses"| GENERIC
    RET_SINGLE -->|Yes| IMPL_RET
    RET_SINGLE -->|"No (conditional types)"| DYN_BOX
    RET_SINGLE -->|"Heterogeneous collection"| COLLECTION
    COLLECTION -->|Owned| DYN_BOX
    COLLECTION -->|Borrowed| DYN_REF

    style GENERIC fill:#c8e6c9,color:#000
    style IMPL_ARG fill:#c8e6c9,color:#000
    style IMPL_RET fill:#c8e6c9,color:#000
    style DYN_BOX fill:#fff3e0,color:#000
    style DYN_REF fill:#fff3e0,color:#000

#![allow(unused)]
fn main() {
// Summary: from fastest to most flexible
fn static_dispatch(x: impl Display)             { /* fastest, no alloc */ }
fn generic_dispatch<T: Display + Clone>(x: T)    { /* fastest, multiple bounds */ }
fn dynamic_dispatch(x: &dyn Display)             { /* vtable lookup, no alloc */ }
fn boxed_dispatch(x: Box<dyn Display>)           { /* vtable lookup + heap alloc */ }
}

可以把这整段话压缩成一句土话：先默认静态分发，真有必要再上 dyn Trait。
也就是说，优先考虑泛型和 impl Trait；只有在确实需要异构集合、条件分支返回不同实现，或者必须持有 trait object 时，再接受动态分发和装箱成本。

Generic Constraints §§ZH§§ 泛型约束

Generic Constraints: where vs trait bounds
泛型约束：where 子句与 trait bound

What you’ll learn: Rust’s trait bounds vs C#’s where constraints, the where clause syntax, conditional trait implementations, associated types, and higher-ranked trait bounds (HRTBs).
本章将学到什么： Rust 的 trait bound 和 C# where 约束有什么区别，where 子句怎么写，条件式 trait 实现是什么，关联类型如何工作，以及高阶生命周期约束 HRTB 到底在解决什么问题。

Difficulty: 🔴 Advanced
难度： 🔴 高级

C# Generic Constraints
C# 的泛型约束

// C# Generic constraints with where clause
public class Repository<T> where T : class, IEntity, new()
{
    public T Create()
    {
        return new T();  // new() constraint allows parameterless constructor
    }
    
    public void Save(T entity)
    {
        if (entity.Id == 0)  // IEntity constraint provides Id property
        {
            entity.Id = GenerateId();
        }
        // Save to database
    }
}

// Multiple type parameters with constraints
public class Converter<TInput, TOutput> 
    where TInput : IConvertible
    where TOutput : class, new()
{
    public TOutput Convert(TInput input)
    {
        var output = new TOutput();
        // Conversion logic using IConvertible
        return output;
    }
}

// Variance in generics
public interface IRepository<out T> where T : IEntity
{
    IEnumerable<T> GetAll();  // Covariant - can return more derived types
}

public interface IWriter<in T> where T : IEntity
{
    void Write(T entity);  // Contravariant - can accept more base types
}

C# 的 where 约束，核心是在说“这个类型参数至少得长成什么样”。例如必须实现某接口、必须是引用类型、必须带无参构造函数。对 C# 开发者来说，这套写法很自然，因为它和类继承、接口、多态是一整套世界观。
但到了 Rust，思路就得拐个弯。Rust 的约束不是围着类层级打转，而是围着能力，也就是 trait 在组织。

Rust Generic Constraints with Trait Bounds
Rust 里的泛型约束：trait bound

#![allow(unused)]
fn main() {
use std::fmt::{Debug, Display};
use std::clone::Clone;

// Basic trait bounds
pub struct Repository<T> 
where 
    T: Clone + Debug + Default,
{
    items: Vec<T>,
}

impl<T> Repository<T> 
where 
    T: Clone + Debug + Default,
{
    pub fn new() -> Self {
        Repository { items: Vec::new() }
    }
    
    pub fn create(&self) -> T {
        T::default()  // Default trait provides default value
    }
    
    pub fn add(&mut self, item: T) {
        println!("Adding item: {:?}", item);  // Debug trait for printing
        self.items.push(item);
    }
    
    pub fn get_all(&self) -> Vec<T> {
        self.items.clone()  // Clone trait for duplication
    }
}

// Multiple trait bounds with different syntaxes
pub fn process_data<T, U>(input: T) -> U 
where 
    T: Display + Clone,
    U: From<T> + Debug,
{
    println!("Processing: {}", input);  // Display trait
    let cloned = input.clone();         // Clone trait
    let output = U::from(cloned);       // From trait for conversion
    println!("Result: {:?}", output);   // Debug trait
    output
}

// Associated types (similar to C# generic constraints)
pub trait Iterator {
    type Item;  // Associated type instead of generic parameter
    
    fn next(&mut self) -> Option<Self::Item>;
}

pub trait Collect<T> {
    fn collect<I: Iterator<Item = T>>(iter: I) -> Self;
}

// Higher-ranked trait bounds (advanced)
fn apply_to_all<F>(items: &[String], f: F) -> Vec<String>
where 
    F: for<'a> Fn(&'a str) -> String,  // Function works with any lifetime
{
    items.iter().map(|s| f(s)).collect()
}

// Conditional trait implementations
impl<T> PartialEq for Repository<T> 
where 
    T: PartialEq + Clone + Debug + Default,
{
    fn eq(&self, other: &Self) -> bool {
        self.items == other.items
    }
}
}

Rust 这里的味道完全不同。T: Clone + Debug + Default 的意思不是“T 继承了某些祖宗类型”，而是“T 必须具备这些能力”。这种能力导向的建模方式，和 C# 那种面向继承层级的约束相比，会更轻、更组合化。
说白了，Rust 更关心“这个类型能干什么”，而不是“它是谁的孩子”。

Why where Exists
为什么 Rust 也有 where 子句

Rust 当然也支持把约束写在尖括号里，例如 fn f<T: Clone + Debug>(x: T)。可一旦类型参数多起来、约束变复杂、还要带关联类型，那一行代码就会很快长得像拧麻花。
这时候 where 子句的价值就出来了：把函数签名和约束条件拆开，读起来不那么糊成一坨。

经验上可以这样记：
一个很实用的经验是：

• Short, simple bounds can stay inline: fn print<T: Display>(value: T)
  约束短而简单时，可以直接写在泛型参数里，例如 fn print<T: Display>(value: T)。
• Longer bounds, multiple type parameters, or associated-type requirements read better in where
  如果约束很长、类型参数很多、或者还带有关联类型要求，改写成 where 通常更清楚。

Associated Types vs More Type Parameters
关联类型与“继续加类型参数”的区别

对 C# 开发者来说，关联类型一开始经常有点绕，因为习惯了“需要表达一个类型关系，就再加一个泛型参数”。Rust 当然也能这么写，但很多时候关联类型更自然。
例如 Iterator 并不是“某种带一个额外泛型参数的 trait”，而是“这个 trait 自带一个产出类型 Item”。这样使用端更简洁，约束也更少歧义。

Conditional Implementations
条件式实现

impl<T> PartialEq for Repository<T> where T: PartialEq + Clone + Debug + Default 这种写法，是 Rust 泛型特别有力量的一点。
它表达的是：只有当 T 本身满足这些能力时，Repository<T> 才拥有 PartialEq。这是一种非常自然的“能力传播”模式。

C# 里通常更依赖接口层级或运行时行为来组织类似能力。Rust 则更喜欢把这种规则提前写进类型系统，让可不可以成立，在编译时就定死。
这也是 Rust 泛型虽然难啃，但一旦掌握后会非常顺手的原因之一。

Higher-Ranked Trait Bounds
高阶生命周期约束 HRTB

for<'a> Fn(&'a str) -> String 这种写法第一次看确实容易脑壳发紧。它的意思其实很朴素：这个函数或闭包，必须对任意生命周期的 &str 都成立。
换句话说，它不能偷偷依赖某个特定借用时长，而是要足够通用，来什么引用都能接住。

这在“把某个函数当作泛型参数传进去”时特别常见。C# 里这类事情很多时候由委托和运行时类型系统帮忙兜着，Rust 则要把借用关系说清楚。
看起来更复杂，但换来的好处是生命周期规则更精确，也更容易避免悬垂引用之类的毛病。

graph TD
    subgraph "C# Generic Constraints"
        CS_WHERE["where T : class, IInterface, new()"]
        CS_RUNTIME["[ERROR] Some runtime type checking<br/>Virtual method dispatch"]
        CS_VARIANCE["[OK] Covariance/Contravariance<br/>in/out keywords"]
        CS_REFLECTION["[ERROR] Runtime reflection possible<br/>typeof(T), is, as operators"]
        CS_BOXING["[ERROR] Value type boxing<br/>for interface constraints"]
        
        CS_WHERE --> CS_RUNTIME
        CS_WHERE --> CS_VARIANCE
        CS_WHERE --> CS_REFLECTION
        CS_WHERE --> CS_BOXING
    end
    
    subgraph "Rust Trait Bounds"
        RUST_WHERE["where T: Trait + Clone + Debug"]
        RUST_COMPILE["[OK] Compile-time resolution<br/>Monomorphization"]
        RUST_ZERO["[OK] Zero-cost abstractions<br/>No runtime overhead"]
        RUST_ASSOCIATED["[OK] Associated types<br/>More flexible than generics"]
        RUST_HKT["[OK] Higher-ranked trait bounds<br/>Advanced type relationships"]
        
        RUST_WHERE --> RUST_COMPILE
        RUST_WHERE --> RUST_ZERO
        RUST_WHERE --> RUST_ASSOCIATED
        RUST_WHERE --> RUST_HKT
    end
    
    subgraph "Flexibility Comparison"
        CS_FLEX["C# Flexibility<br/>[OK] Variance<br/>[OK] Runtime type info<br/>[ERROR] Performance cost"]
        RUST_FLEX["Rust Flexibility<br/>[OK] Zero cost<br/>[OK] Compile-time safety<br/>[ERROR] No variance (yet)"]
    end
    
    style CS_RUNTIME fill:#fff3e0,color:#000
    style CS_BOXING fill:#ffcdd2,color:#000
    style RUST_COMPILE fill:#c8e6c9,color:#000
    style RUST_ZERO fill:#c8e6c9,color:#000
    style CS_FLEX fill:#e3f2fd,color:#000
    style RUST_FLEX fill:#c8e6c9,color:#000

这张图背后的核心差异其实挺简单：C# 泛型约束给的是“面向对象体系里的资格说明”，Rust trait bound 给的是“编译期能力契约”。
一个更依赖运行时类型世界的配合，一个更偏向把抽象压到编译期解决。

Exercises
练习

public interface IRepository<T> where T : IEntity, new()
{
    T GetById(int id);
    IEnumerable<T> Find(Func<T, bool> predicate);
    void Save(T entity);
}

trait Entity: Clone {
    fn id(&self) -> u64;
}

trait Repository<T: Entity> {
    fn get_by_id(&self, id: u64) -> Option<&T>;
    fn find(&self, predicate: impl Fn(&T) -> bool) -> Vec<&T>;
    fn save(&mut self, entity: T);
}

struct InMemoryRepository<T> {
    items: Vec<T>,
}

impl<T: Entity> InMemoryRepository<T> {
    fn new() -> Self { Self { items: Vec::new() } }
}

impl<T: Entity> Repository<T> for InMemoryRepository<T> {
    fn get_by_id(&self, id: u64) -> Option<&T> {
        self.items.iter().find(|item| item.id() == id)
    }
    fn find(&self, predicate: impl Fn(&T) -> bool) -> Vec<&T> {
        self.items.iter().filter(|item| predicate(item)).collect()
    }
    fn save(&mut self, entity: T) {
        if let Some(pos) = self.items.iter().position(|e| e.id() == entity.id()) {
            self.items[pos] = entity;
        } else {
            self.items.push(entity);
        }
    }
}

#[derive(Clone, Debug)]
struct User { user_id: u64, name: String }

impl Entity for User {
    fn id(&self) -> u64 { self.user_id }
}

fn main() {
    let mut repo = InMemoryRepository::new();
    repo.save(User { user_id: 1, name: "Alice".into() });
    repo.save(User { user_id: 2, name: "Bob".into() });

    let found = repo.find(|u| u.name.starts_with('A'));
    assert_eq!(found.len(), 1);
}

Inheritance vs Composition §§ZH§§ 继承与组合

Inheritance vs Composition
继承与组合

What you’ll learn: Why Rust has no class inheritance, how traits + structs replace deep class hierarchies, and practical patterns for achieving polymorphism through composition.
本章将学到什么： 为什么 Rust 没有类继承，trait 加 struct 如何替代深层类层级，以及怎样用组合而不是继承实现多态。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

// C# - Class-based inheritance
public abstract class Animal
{
    public string Name { get; protected set; }
    public abstract void MakeSound();
    
    public virtual void Sleep()
    {
        Console.WriteLine($"{Name} is sleeping");
    }
}

public class Dog : Animal
{
    public Dog(string name) { Name = name; }
    
    public override void MakeSound()
    {
        Console.WriteLine("Woof!");
    }
    
    public void Fetch()
    {
        Console.WriteLine($"{Name} is fetching");
    }
}

// Interface-based contracts
public interface IFlyable
{
    void Fly();
}

public class Bird : Animal, IFlyable
{
    public Bird(string name) { Name = name; }
    
    public override void MakeSound()
    {
        Console.WriteLine("Tweet!");
    }
    
    public void Fly()
    {
        Console.WriteLine($"{Name} is flying");
    }
}

Rust Composition Model
Rust 的组合模型

#![allow(unused)]
fn main() {
// Rust - Composition over inheritance with traits
pub trait Animal {
    fn name(&self) -> &str;
    fn make_sound(&self);
    
    // Default implementation (like C# virtual methods)
    fn sleep(&self) {
        println!("{} is sleeping", self.name());
    }
}

pub trait Flyable {
    fn fly(&self);
}

// Separate data from behavior
#[derive(Debug)]
pub struct Dog {
    name: String,
}

#[derive(Debug)]
pub struct Bird {
    name: String,
    wingspan: f64,
}

// Implement behaviors for types
impl Animal for Dog {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn make_sound(&self) {
        println!("Woof!");
    }
}

impl Dog {
    pub fn new(name: String) -> Self {
        Dog { name }
    }
    
    pub fn fetch(&self) {
        println!("{} is fetching", self.name);
    }
}

impl Animal for Bird {
    fn name(&self) -> &str {
        &self.name
    }
    
    fn make_sound(&self) {
        println!("Tweet!");
    }
}

impl Flyable for Bird {
    fn fly(&self) {
        println!("{} is flying with {:.1}m wingspan", self.name, self.wingspan);
    }
}

// Multiple trait bounds (like multiple interfaces)
fn make_flying_animal_sound<T>(animal: &T) 
where 
    T: Animal + Flyable,
{
    animal.make_sound();
    animal.fly();
}
}

graph TD
    subgraph "C# Inheritance Hierarchy"
        CS_ANIMAL["Animal (abstract class)"]
        CS_DOG["Dog : Animal"]
        CS_BIRD["Bird : Animal, IFlyable"]
        CS_VTABLE["Virtual method dispatch<br/>Runtime cost"]
        CS_COUPLING["[ERROR] Tight coupling<br/>[ERROR] Diamond problem<br/>[ERROR] Deep hierarchies"]
        
        CS_ANIMAL --> CS_DOG
        CS_ANIMAL --> CS_BIRD
        CS_DOG --> CS_VTABLE
        CS_BIRD --> CS_VTABLE
        CS_ANIMAL --> CS_COUPLING
    end
    
    subgraph "Rust Composition Model"
        RUST_ANIMAL["trait Animal"]
        RUST_FLYABLE["trait Flyable"]
        RUST_DOG["struct Dog"]
        RUST_BIRD["struct Bird"]
        RUST_IMPL1["impl Animal for Dog"]
        RUST_IMPL2["impl Animal for Bird"]
        RUST_IMPL3["impl Flyable for Bird"]
        RUST_STATIC["Static dispatch<br/>Zero cost"]
        RUST_FLEXIBLE["[OK] Flexible composition<br/>[OK] No hierarchy limits<br/>[OK] Mix and match traits"]
        
        RUST_DOG --> RUST_IMPL1
        RUST_BIRD --> RUST_IMPL2
        RUST_BIRD --> RUST_IMPL3
        RUST_IMPL1 --> RUST_ANIMAL
        RUST_IMPL2 --> RUST_ANIMAL
        RUST_IMPL3 --> RUST_FLYABLE
        RUST_IMPL1 --> RUST_STATIC
        RUST_IMPL2 --> RUST_STATIC
        RUST_IMPL3 --> RUST_STATIC
        RUST_ANIMAL --> RUST_FLEXIBLE
        RUST_FLYABLE --> RUST_FLEXIBLE
    end
    
    style CS_COUPLING fill:#ffcdd2,color:#000
    style RUST_FLEXIBLE fill:#c8e6c9,color:#000
    style CS_VTABLE fill:#fff3e0,color:#000
    style RUST_STATIC fill:#c8e6c9,color:#000

Exercises
练习

public abstract class Shape { public abstract double Area(); }
public abstract class Shape3D : Shape { public abstract double Volume(); }
public class Cylinder : Shape3D
{
    public double Radius { get; }
    public double Height { get; }
    public Cylinder(double r, double h) { Radius = r; Height = h; }
    public override double Area() => 2.0 * Math.PI * Radius * (Radius + Height);
    public override double Volume() => Math.PI * Radius * Radius * Height;
}

use std::f64::consts::PI;

trait HasArea {
    fn area(&self) -> f64;
}

trait HasVolume {
    fn volume(&self) -> f64;
}

struct Cylinder {
    radius: f64,
    height: f64,
}

impl HasArea for Cylinder {
    fn area(&self) -> f64 {
        2.0 * PI * self.radius * (self.radius + self.height)
    }
}

impl HasVolume for Cylinder {
    fn volume(&self) -> f64 {
        PI * self.radius * self.radius * self.height
    }
}

fn print_shape_info(shape: &(impl HasArea + HasVolume)) {
    println!("Area:   {:.2}", shape.area());
    println!("Volume: {:.2}", shape.volume());
}

fn main() {
    let c = Cylinder { radius: 3.0, height: 5.0 };
    print_shape_info(&c);
}

From and Into Traits §§ZH§§ From 与 Into Trait

Type Conversions in Rust
Rust 中的类型转换

What you’ll learn: From/Into traits vs C#’s implicit/explicit operators, TryFrom/TryInto for fallible conversions, FromStr for parsing, and idiomatic string conversion patterns.
本章将学到什么： From / Into trait 和 C# 的隐式 / 显式转换运算符有何差别，TryFrom / TryInto 如何处理可能失败的转换，FromStr 如何用于解析，以及字符串转换的惯用写法。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

C# uses implicit/explicit conversions and casting operators. Rust uses the From and Into traits for safe, explicit conversions.
C# 主要依赖隐式 / 显式转换和 cast 运算符。Rust 则把安全、显式的转换放进 From 和 Into trait 里。

C# Conversion Patterns
C# 的转换模式

// C# implicit/explicit conversions
// C# 的隐式 / 显式转换
public class Temperature
{
    public double Celsius { get; }
    
    public Temperature(double celsius) { Celsius = celsius; }
    
    // Implicit conversion
    // 隐式转换
    public static implicit operator double(Temperature t) => t.Celsius;
    
    // Explicit conversion
    // 显式转换
    public static explicit operator Temperature(double d) => new Temperature(d);
}

double temp = new Temperature(100.0);  // implicit
Temperature t = (Temperature)37.5;     // explicit

Rust From and Into
Rust 里的 From 与 Into

#[derive(Debug)]
struct Temperature {
    celsius: f64,
}

impl From<f64> for Temperature {
    fn from(celsius: f64) -> Self {
        Temperature { celsius }
    }
}

impl From<Temperature> for f64 {
    fn from(temp: Temperature) -> f64 {
        temp.celsius
    }
}

fn main() {
    // From
    let temp = Temperature::from(100.0);
    
    // Into (automatically available when From is implemented)
    let temp2: Temperature = 37.5.into();
    
    // Works in function arguments too
    fn process_temp(temp: impl Into<Temperature>) {
        let t: Temperature = temp.into();
        println!("Temperature: {:.1}°C", t.celsius);
    }
    
    process_temp(98.6);
    process_temp(Temperature { celsius: 0.0 });
}

graph LR
    A["impl From<f64> for Temperature"] -->|"auto-generates"| B["impl Into<Temperature> for f64"]
    C["Temperature::from(37.5)"] -->|"explicit"| D["Temperature"]
    E["37.5.into()"] -->|"implicit via Into"| D
    F["fn process(t: impl Into<Temperature>)"] -->|"accepts both"| D

    style A fill:#c8e6c9,color:#000
    style B fill:#bbdefb,color:#000

Rule of thumb: Implement From, and you get Into for free. Callers can use whichever reads better.
经验法则： 只要实现了 From，Into 就会自动可用。调用方可以挑可读性更好的那种写法。

TryFrom for Fallible Conversions
用 TryFrom 处理可能失败的转换

use std::convert::TryFrom;

impl TryFrom<i32> for Temperature {
    type Error = String;
    
    fn try_from(value: i32) -> Result<Self, Self::Error> {
        if value < -273 {
            Err(format!("Temperature {}°C is below absolute zero", value))
        } else {
            Ok(Temperature { celsius: value as f64 })
        }
    }
}

fn main() {
    match Temperature::try_from(-300) {
        Ok(t) => println!("Valid: {:?}", t),
        Err(e) => println!("Error: {}", e),
    }
}

String Conversions
字符串转换

#![allow(unused)]
fn main() {
// ToString via Display trait
// 通过 Display trait 自动获得 ToString
impl std::fmt::Display for Temperature {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:.1}°C", self.celsius)
    }
}

// Now .to_string() works automatically
// 现在就能自动使用 .to_string()
let s = Temperature::from(100.0).to_string(); // "100.0°C"

// FromStr for parsing
// 用 FromStr 做解析
use std::str::FromStr;

impl FromStr for Temperature {
    type Err = String;
    
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let s = s.trim_end_matches("°C").trim();
        let celsius: f64 = s.parse().map_err(|e| format!("Invalid temp: {}", e))?;
        Ok(Temperature { celsius })
    }
}

let t: Temperature = "100.0°C".parse().unwrap();
}

Exercises
练习

use std::fmt;
use std::str::FromStr;

#[derive(Debug, Clone, Copy)]
struct Money { cents: i64 }

impl From<i64> for Money {
    fn from(dollars: i64) -> Self {
        Money { cents: dollars * 100 }
    }
}

impl TryFrom<f64> for Money {
    type Error = String;
    fn try_from(value: f64) -> Result<Self, Self::Error> {
        if value < 0.0 {
            Err(format!("negative amount: {value}"))
        } else {
            Ok(Money { cents: (value * 100.0).round() as i64 })
        }
    }
}

impl fmt::Display for Money {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "${}.{:02}", self.cents / 100, self.cents.abs() % 100)
    }
}

impl FromStr for Money {
    type Err = String;
    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let s = s.trim_start_matches('$');
        let val: f64 = s.parse().map_err(|e| format!("{e}"))?;
        Money::try_from(val)
    }
}

fn main() {
    let a = Money::from(10);                       // $10.00
    let b = Money::try_from(3.50).unwrap();         // $3.50
    let c: Money = "$7.25".parse().unwrap();        // $7.25
    println!("{a} + {b} + {c}");
}

Closures and Iterators §§ZH§§ 闭包与迭代器

Rust Closures
Rust 闭包

What you’ll learn: Closures with ownership-aware captures (Fn / FnMut / FnOnce) compared with C# lambdas, Rust iterators as a zero-cost alternative to LINQ, lazy vs eager evaluation, and parallel iteration with rayon.
本章将学到什么： 对照理解带所有权语义的 Rust 闭包捕获方式 Fn / FnMut / FnOnce，理解 Rust 迭代器怎样作为 LINQ 的零成本替代方案，并看清惰性求值、立即求值，以及 rayon 并行迭代的基本思路。

Difficulty: 🟡 Intermediate
难度： 🟡 进阶

Closures in Rust are similar to C# lambdas and delegates, but their captures are aware of ownership and borrowing.
Rust 的闭包和 C# 的 lambda、delegate 看起来很像，但真正的区别在捕获语义上。Rust 会把所有权、借用、可变性这些事情一起算进去，这也正是它后劲大的地方。

C# Lambdas and Delegates
C# 的 Lambda 与委托

// C# - Lambdas capture by reference
Func<int, int> doubler = x => x * 2;
Action<string> printer = msg => Console.WriteLine(msg);

// Closure capturing outer variables
int multiplier = 3;
Func<int, int> multiply = x => x * multiplier;
Console.WriteLine(multiply(5)); // 15

// LINQ uses lambdas extensively
var evens = numbers.Where(n => n % 2 == 0).ToList();

Rust Closures
Rust 闭包

#![allow(unused)]
fn main() {
// Rust closures - ownership-aware
let doubler = |x: i32| x * 2;
let printer = |msg: &str| println!("{}", msg);

// Closure capturing by reference (default for immutable)
let multiplier = 3;
let multiply = |x: i32| x * multiplier; // borrows multiplier
println!("{}", multiply(5)); // 15
println!("{}", multiplier); // still accessible

// Closure capturing by move
let data = vec![1, 2, 3];
let owns_data = move || {
    println!("{:?}", data); // data moved into closure
};
owns_data();
// println!("{:?}", data); // ERROR: data was moved

// Using closures with iterators
let numbers = vec![1, 2, 3, 4, 5];
let evens: Vec<&i32> = numbers.iter().filter(|&&n| n % 2 == 0).collect();
}

这段对照里最要命的区别就是 move。
在 C# 里，很多时候脑子里只需要想“能不能访问到外层变量”；在 Rust 里，还得继续问一句：它是借过来，还是拿走了所有权。这个判断会直接影响闭包能活多久、能不能多次调用、能不能跨线程跑。

Closure Types
闭包类型

// Fn - borrows captured values immutably
fn apply_fn(f: impl Fn(i32) -> i32, x: i32) -> i32 {
    f(x)
}

// FnMut - borrows captured values mutably
fn apply_fn_mut(mut f: impl FnMut(i32), values: &[i32]) {
    for &v in values {
        f(v);
    }
}

// FnOnce - takes ownership of captured values
fn apply_fn_once(f: impl FnOnce() -> Vec<i32>) -> Vec<i32> {
    f() // can only call once
}

fn main() {
    // Fn example
    let multiplier = 3;
    let result = apply_fn(|x| x * multiplier, 5);
    
    // FnMut example
    let mut sum = 0;
    apply_fn_mut(|x| sum += x, &[1, 2, 3, 4, 5]);
    println!("Sum: {}", sum); // 15
    
    // FnOnce example
    let data = vec![1, 2, 3];
    let result = apply_fn_once(move || data); // moves data
}

Fn、FnMut、FnOnce 乍一看像故意折腾人，实际上它们是在把“闭包到底怎么用捕获值”讲得很清楚。
只要把这三个名字记成“只读借用、可变借用、拿走所有权”，后面很多泛型 API 一下就能看懂，不至于瞅着 trait bound 发懵。

LINQ vs Rust Iterators
LINQ 与 Rust 迭代器对照

C# LINQ (Language Integrated Query)
C# LINQ（语言集成查询）

// C# LINQ - Declarative data processing
var numbers = new[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };

var result = numbers
    .Where(n => n % 2 == 0)           // Filter even numbers
    .Select(n => n * n)               // Square them
    .Where(n => n > 10)               // Filter > 10
    .OrderByDescending(n => n)        // Sort descending
    .Take(3)                          // Take first 3
    .ToList();                        // Materialize

// LINQ with complex objects
var users = GetUsers();
var activeAdults = users
    .Where(u => u.IsActive && u.Age >= 18)
    .GroupBy(u => u.Department)
    .Select(g => new {
        Department = g.Key,
        Count = g.Count(),
        AverageAge = g.Average(u => u.Age)
    })
    .OrderBy(x => x.Department)
    .ToList();

// Async LINQ (with additional libraries)
var results = await users
    .ToAsyncEnumerable()
    .WhereAwait(async u => await IsActiveAsync(u.Id))
    .SelectAwait(async u => await EnrichUserAsync(u))
    .ToListAsync();

Rust Iterators
Rust 迭代器

#![allow(unused)]
fn main() {
// Rust iterators - Lazy, zero-cost abstractions
let numbers = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

let result: Vec<i32> = numbers
    .iter()
    .filter(|&&n| n % 2 == 0)        // Filter even numbers
    .map(|&n| n * n)                 // Square them
    .filter(|&n| n > 10)             // Filter > 10
    .collect::<Vec<_>>()             // Collect to Vec
    .into_iter()
    .rev()                           // Reverse (descending sort)
    .take(3)                         // Take first 3
    .collect();                      // Materialize

// Complex iterator chains
use std::collections::HashMap;

#[derive(Debug, Clone)]
struct User {
    name: String,
    age: u32,
    department: String,
    is_active: bool,
}

fn process_users(users: Vec<User>) -> HashMap<String, (usize, f64)> {
    users
        .into_iter()
        .filter(|u| u.is_active && u.age >= 18)
        .fold(HashMap::new(), |mut acc, user| {
            let entry = acc.entry(user.department.clone()).or_insert((0, 0.0));
            entry.0 += 1;  // count
            entry.1 += user.age as f64;  // sum of ages
            acc
        })
        .into_iter()
        .map(|(dept, (count, sum))| (dept, (count, sum / count as f64)))  // average
        .collect()
}

// Parallel processing with rayon
use rayon::prelude::*;

fn parallel_processing(numbers: Vec<i32>) -> Vec<i32> {
    numbers
        .par_iter()                  // Parallel iterator
        .filter(|&&n| n % 2 == 0)
        .map(|&n| expensive_computation(n))
        .collect()
}

fn expensive_computation(n: i32) -> i32 {
    // Simulate heavy computation
    (0..1000).fold(n, |acc, _| acc + 1)
}
}

Rust 迭代器和 LINQ 的表面相似度很高，但底层心态差不少。
LINQ 很容易让人顺手 .ToList() 把中间结果全堆出来；Rust 迭代器默认更偏惰性，也更强调把整条变换链交给编译器优化成紧凑循环。这就是“写法像函数式，结果像手写循环”的那层意思。

graph TD
    subgraph "C# LINQ Characteristics"
        CS_LINQ["LINQ Expression<br/>LINQ 表达式"]
        CS_EAGER["Often eager evaluation<br/>(ToList(), ToArray())<br/>经常提前物化"]
        CS_REFLECTION["[ERROR] Some runtime reflection<br/>Expression trees<br/>可能掺杂运行时反射"]
        CS_ALLOCATIONS["[ERROR] Intermediate collections<br/>Garbage collection pressure<br/>中间集合带来 GC 压力"]
        CS_ASYNC["[OK] Async support<br/>(with additional libraries)<br/>可配合异步扩展"]
        CS_SQL["[OK] LINQ to SQL/EF integration<br/>能对接数据库查询"]
        
        CS_LINQ --> CS_EAGER
        CS_LINQ --> CS_REFLECTION
        CS_LINQ --> CS_ALLOCATIONS
        CS_LINQ --> CS_ASYNC
        CS_LINQ --> CS_SQL
    end
    
    subgraph "Rust Iterator Characteristics"
        RUST_ITER["Iterator Chain<br/>迭代器链"]
        RUST_LAZY["[OK] Lazy evaluation<br/>No work until .collect()<br/>默认惰性求值"]
        RUST_ZERO["[OK] Zero-cost abstractions<br/>Compiles to optimal loops<br/>零成本抽象"]
        RUST_NO_ALLOC["[OK] No intermediate allocations<br/>Stack-based processing<br/>尽量避免中间分配"]
        RUST_PARALLEL["[OK] Easy parallelization<br/>(rayon crate)<br/>容易并行化"]
        RUST_FUNCTIONAL["[OK] Functional programming<br/>Immutable by default<br/>偏函数式且默认不可变"]
        
        RUST_ITER --> RUST_LAZY
        RUST_ITER --> RUST_ZERO
        RUST_ITER --> RUST_NO_ALLOC
        RUST_ITER --> RUST_PARALLEL
        RUST_ITER --> RUST_FUNCTIONAL
    end
    
    subgraph "Performance Comparison"
        CS_PERF["C# LINQ Performance<br/>[ERROR] Allocation overhead<br/>[ERROR] Virtual dispatch<br/>[OK] Good enough for most cases<br/>多数业务场景够用"]
        RUST_PERF["Rust Iterator Performance<br/>[OK] Hand-optimized speed<br/>[OK] No allocations<br/>[OK] Compile-time optimization<br/>接近手工优化结果"]
    end
    
    style CS_REFLECTION fill:#ffcdd2,color:#000
    style CS_ALLOCATIONS fill:#fff3e0,color:#000
    style RUST_ZERO fill:#c8e6c9,color:#000
    style RUST_LAZY fill:#c8e6c9,color:#000
    style RUST_NO_ALLOC fill:#c8e6c9,color:#000
    style CS_PERF fill:#fff3e0,color:#000
    style RUST_PERF fill:#c8e6c9,color:#000

// C# — translate to Rust
record Employee(string Name, string Dept, int Salary);

var result = employees
    .Where(e => e.Salary > 50_000)
    .GroupBy(e => e.Dept)
    .Select(g => new {
        Department = g.Key,
        Count = g.Count(),
        AvgSalary = g.Average(e => e.Salary)
    })
    .OrderByDescending(x => x.AvgSalary)
    .ToList();

#![allow(unused)]
fn main() {
use std::collections::HashMap;

struct Employee { name: String, dept: String, salary: u32 }

#[derive(Debug)]
struct DeptStats { department: String, count: usize, avg_salary: f64 }

fn department_stats(employees: &[Employee]) -> Vec<DeptStats> {
    let mut by_dept: HashMap<&str, Vec<u32>> = HashMap::new();
    for e in employees.iter().filter(|e| e.salary > 50_000) {
        by_dept.entry(&e.dept).or_default().push(e.salary);
    }

    let mut stats: Vec<DeptStats> = by_dept
        .into_iter()
        .map(|(dept, salaries)| {
            let count = salaries.len();
            let avg = salaries.iter().sum::<u32>() as f64 / count as f64;
            DeptStats { department: dept.to_string(), count, avg_salary: avg }
        })
        .collect();

    stats.sort_by(|a, b| b.avg_salary.partial_cmp(&a.avg_salary).unwrap());
    stats
}
}

itertools: The Missing LINQ Operations
itertools：补齐 LINQ 味道更浓的操作

Standard Rust iterators already cover map, filter, fold, take, and collect, but C# developers will quickly notice the absence of familiar things like GroupBy, Chunk, SelectMany, or DistinctBy. The itertools crate fills many of those gaps.
标准库迭代器已经有 map、filter、fold、take、collect 这些核心能力，但 C# 开发者很快就会想起 GroupBy、Chunk、SelectMany、DistinctBy 这些顺手招式。itertools 干的就是补这块。

# Cargo.toml
[dependencies]
itertools = "0.12"

Side-by-Side: LINQ vs itertools
并排对照：LINQ 与 itertools

// C# — GroupBy
var byDept = employees.GroupBy(e => e.Department)
    .Select(g => new { Dept = g.Key, Count = g.Count() });

// C# — Chunk (batching)
var batches = items.Chunk(100);  // IEnumerable<T[]>

// C# — Distinct / DistinctBy
var unique = users.DistinctBy(u => u.Email);

// C# — SelectMany (flatten)
var allTags = posts.SelectMany(p => p.Tags);

// C# — Zip
var pairs = names.Zip(scores, (n, s) => new { Name = n, Score = s });

// C# — Sliding window
var windows = data.Zip(data.Skip(1), data.Skip(2))
    .Select(triple => (triple.First + triple.Second + triple.Third) / 3.0);

#![allow(unused)]
fn main() {
use itertools::Itertools;

// Rust — group_by (requires sorted input)
let by_dept = employees.iter()
    .sorted_by_key(|e| &e.department)
    .group_by(|e| &e.department);
for (dept, group) in &by_dept {
    println!("{}: {} employees", dept, group.count());
}

// Rust — chunks (batching)
let batches = items.iter().chunks(100);
for batch in &batches {
    process_batch(batch.collect::<Vec<_>>());
}

// Rust — unique / unique_by
let unique: Vec<_> = users.iter().unique_by(|u| &u.email).collect();

// Rust — flat_map (SelectMany equivalent — built-in!)
let all_tags: Vec<&str> = posts.iter().flat_map(|p| &p.tags).collect();

// Rust — zip (built-in!)
let pairs: Vec<_> = names.iter().zip(scores.iter()).collect();

// Rust — tuple_windows (sliding window)
let moving_avg: Vec<f64> = data.iter()
    .tuple_windows::<(_, _, _)>()
    .map(|(a, b, c)| (*a + *b + *c) as f64 / 3.0)
    .collect();
}

itertools 最大的价值，就是把很多“标准库故意没塞进去”的高阶操作补上。
但也别误会成“用了它才算正宗 Rust”。很多场景下，标准库迭代器加一小段显式代码已经很好；只有在可读性真的更好时，再把 itertools 搬上来会更舒服。

itertools Quick Reference
itertools 速查表