Rust 1.100.0 · 最新稳定版Edition 20242026 年 11 月 12 日发布

从零开始学 Rust:
一门让你「编译过,基本就对了」的语言

Rust 是一门系统级编程语言:没有垃圾回收,却能保证内存安全;性能比肩 C/C++,又自带现代化的包管理和工具链。它最难的地方——所有权与借用检查——也正是它最值得学的地方。本页已按最新版 Rust 1.100.0 与 Edition 2024 更新:从安装起就用新版默认设置,示例全部采用当前 idiomatic 写法——let 链、内联格式化、never type ! 这些新特性都会讲到。先跑起来,再逐个攻克核心概念,最后用小项目把知识焊死。

01安全所有权系统在编译期消灭悬垂引用、重复释放和数据竞争,不需要 GC。
02快速零成本抽象:高级写法不换运行时开销,编译产物是原生机器码。
03顺手Cargo 管依赖、构建、测试、文档一条龙;编译器报错自带修复建议。
Rust 的吉祥物螃蟹 Ferris,挥着钳子站在一台笔记本电脑和一摞书旁
这是 Ferris(读作 Ferris,来自 ferric「含铁的」)——Rust 社区的螃蟹吉祥物,学 Rust 的人自称 Rustacean。

第一步:把环境跑起来

Rust 的工具链由 rustup 管理:它负责安装编译器 rustc 和包管理器 cargo。整个过程十分钟左右,装完立刻写第一个程序。本页以 2026 年 11 月 12 日发布的最新稳定版 Rust 1.100.0 为准;已经装过 Rust 的人,先跑一次 rustup update stable 升到 1.100.0 再往下学。

终端 — 安装(macOS / Linux)
# 用官方脚本安装 rustup(Windows 请到 rustup.rs 下载安装器)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 已装过的人:更新到最新稳定版 1.100.0
rustup update stable

# 验证安装成功(应显示 1.100.0)
rustc --version   # rustc 1.100.0
cargo --version   # cargo 1.100.0
终端 — 创建并运行第一个项目
cargo new hello_rust   # 创建新项目
cd hello_rust
cargo run              # 编译 + 运行,一步到位
输出Hello, world!
src/main.rs — 你的第一个程序(Edition 2024)
fn main() {
    let name = "Ferris";
    let lang = "Rust 1.100";
    // 现代写法:变量直接内联进格式字符串
    println!("你好,{name}!让我们开始学 {lang}。");
}
运行 cargo run 的输出你好,Ferris!让我们开始学 Rust 1.100。
  • fn main 是每个可执行程序的入口,和 C 家族一样。
  • println! 带感叹号——它是个「宏」而不是函数,! 就是宏的标记。
  • 内联格式化 "{name}" 是现在的标准写法:变量直接写进字符串里,不用再在末尾按顺序对参数。老教程里的 "{}", name 依然能用,但新代码都这么写。
  • 变量默认不可变,let 声明后不能改值;要改得写 let mut。这是 Rust 的第一个「规矩」,后面会反复见到。
  • 项目结构记住三个东西就够了:Cargo.toml(配置与依赖)、src/main.rs(代码)、cargo run(运行)。注意:cargo new 现在生成的 Cargo.toml 里写的是 edition = "2024"——这是当前版本的默认语言版本,本页所有新语法都以它为前提,老教程的 2021 写法对照着看即可。

最新版有什么新东西:Rust 1.100 + Edition 2024

Rust 每 6 周发一个稳定版。当前最新是 1.100.0(2026 年 11 月 12 日发布),语言版本则是 Edition 2024(自 1.85 起成为新项目默认)。下面这六件事,是你现在学 Rust 和看老教程时最容易「对不上号」的地方——先有个印象,后面概念区还有专门一页带代码细讲。完整发布说明见 官方 1.100.0 发布公告。

1.100 · 头条

Never type ! 正式稳定

等了 10 年、历经 5 次稳定尝试,! 终于能在任何位置写出来了。它表示「这个计算永远不会产生值」——比如 panic!、死循环、直接 return。现在可以写 Result<T, !> 表示「不可能失败」,原来的 Infallible 类型也正式成为 ! 的别名。

Edition 2024 · 1.88 起

let 链:告别嵌套金字塔

在 if / while 条件里用 && 串起多个 let:if let Some(x) = a && let Some(y) = b && x > y { }。以前要嵌套三层 if let 的代码,现在一行写平。这是 Edition 2024 才有的语法,2021 项目里写会直接报错。

Edition 2024 · 1.85 起

异步闭包 async || { }

闭包终于能直接是异步的了:let f = async |id| { /* await … */ };,配套新的 AsyncFn 系列 trait,返回的 future 可以借用闭包捕获的变量。写 tokio 异步代码时不用再绕 || async move { } 的老套路。

1.100 · 标准库

DropGuard:退出时自动收尾

新助手类型 std::mem::DropGuard:给它一个值和一个闭包,值离开作用域时——不管是正常结束、? 提前返回还是 panic——闭包都会被执行。想「失败就回滚」时,用 DropGuard::dismiss() 撤销守卫即可,不必再为一次性清理专门实现 Drop。

1.100 · Cargo

依赖冷却期 + 无用依赖提醒

Cargo 新增 min-publish-age(依赖冷却期):在 .cargo/config.toml 里写 global-min-publish-age = "3 days",刚发布不到 3 天的新版本不会被自动选中,降低供应链投毒风险。同时 Cargo 会直接警告 Cargo.toml 里声明了却没用上的依赖,帮你给项目瘦身。

Edition 2024 · 更显式的安全

unsafe 处处明说 + 进阶项

2024 版要求 extern 块写成 unsafe extern、属性也要标 unsafe(...),危险操作不再藏着。进阶读者再记两个 1.100 新项:核心 Allocator trait 稳定,Vec / Box 可以换自定义内存分配器;还有 Box::map、Vec::from_fn、bool::toggle 等一批顺手的新 API。

let_chains.rs — 老写法 vs 2024 新写法
fn main() {
    let user = Some("Ferris");
    let score = Some(95);

    // Edition 2021:嵌套两层 if let
    if let Some(name) = user {
        if let Some(s) = score {
            if s >= 60 {
                println!("{} 通过,分数 {}", name, s);
            }
        }
    }

    // Edition 2024(1.88+):let 链一行写平
    if let Some(name) = user && let Some(s) = score && s >= 60 {
        println!("{name} 通过,分数 {s}");
    }
}
输出(两段相同)Ferris 通过,分数 95 Ferris 通过,分数 95
Cargo.toml — 新项目的样子
[package]
name = "hello_rust"
version = "0.1.0"
edition = "2024"   # ← 1.85 起 cargo new 的默认值

[dependencies]
  • 怎么确认自己的版本:看 Cargo.toml 的 edition 字段,再跑 rustc --version。本页代码默认你已经是 2024 + 1.100。
  • 老项目升级:官方提供自动迁移——把 edition 改成 "2024" 前先跑 cargo fix --edition,大部分机械改动它会替你完成。
  • 看老教程时:2021 及更早的教程绝大部分代码在 2024 下照样跑;对不上的基本就是本节这几处——let 链写不了多半是 edition 没升,而不是你写错了。

为什么值得学 Rust

不是追热点——这四个理由决定了 Rust 在系统编程、后端、命令行工具和 WebAssembly 里都站稳了脚跟。

内存安全,不靠 GC

编程里大量崩溃和安全漏洞来自内存错误。Rust 用所有权规则在编译期挡住悬垂引用、重复释放、数据竞争这一整类问题,运行时没有垃圾回收停顿,适合对延迟敏感的场景。(注:引用环等造成的内存泄漏仍可能发生,但那属于「浪费」而非「不安全」。)

性能与 C/C++ 同级

迭代器、泛型、闭包这些高级抽象会被编译成和手写循环一样快的代码——这就是官方说的「零成本抽象」:不用的不付费,用的不比手写慢。

编译器像一位严格的老师

Rust 的报错信息是出了名的详细:指出问题位置、解释原因、还经常直接给出改法。新手最怕的「不知道错在哪」,在 Rust 里很少发生——学会读报错,等于多了一位随身导师。

工具链完整统一

Cargo 管依赖和构建,rustfmt 统一格式,clippy 给出代码改进建议,rustdoc 自动生成文档。不用先花一周配环境,上手就能写正经项目。

8 周学习路线

按每天 1 小时左右的节奏设计。不必赶进度——Rust 的概念环环相扣,某一周卡住了,多花几天把代码敲透,比跳过去更划算。每个阶段末尾都有一个「过关标准」,达到了再往下走。

1 第 1–2 周 · 打地基

语法与 Cargo 上手

用 rustup 装好最新版 1.100,确认新项目的 Cargo.toml 是 edition = "2024",再熟悉 cargo 的常用命令。掌握变量与可变性、基本数据类型、函数、if / loop / while / for 控制流,以及注释和内联格式化输出 "{name}"。这一阶段的目标是:看到一段 Rust 代码不发怵。

edition = "2024"let / let muti32 · f64 · bool · charfn 函数内联格式化 {name}cargo new / run / build
过关标准:独立写出官方教程里的「猜数字游戏」——读懂每一行,包括 loop、match 和从终端读取输入的部分。
2 第 3–4 周 · 攻坚战

所有权、借用与生命周期

这是 Rust 的核心,也是学习曲线最陡的一段。理解值在赋值和传参时是「移动」还是「复制」,学会用引用 & 和可变引用 &mut 借用数据,认识切片(slice)。顺带把现代控制流写顺:用 let ... else 提前返回、用 Edition 2024 的 let 链把嵌套的 if let 写平。和借用检查器「吵架」是必经之路——每吵赢一次,理解就深一层。

所有权三规则move 与 Copy&T / &mut T切片 &strlet-elselet 链(2024)生命周期标注(初步)
过关标准:能向别人讲清楚为什么 let b = a; 之后 a 就不能再用了,以及什么时候该传值、什么时候该传引用。
3 第 5–6 周 · 组织代码

结构体、枚举与错误处理

用 struct 组织数据、用 enum + match 表达「多选一」的状态——这是 Rust 建模的精髓。再学集合(Vec、String、HashMap)、Option 与 Result、用 ? 运算符优雅地传播错误,并用模块和包把代码拆开。

struct + implenum + matchOption<T>Result<T, E> 与 ?Vec · HashMapmod 模块
过关标准:完成下面的「命令行待办清单」项目,全程不用 unwrap() 糊弄错误,该处理的错误都处理掉。
4 第 7–8 周 · 写出像样的程序

泛型、Trait 与迭代器

用泛型写可复用的代码,用 trait 定义共享行为(类似其他语言的接口),用闭包和迭代器把循环改写成链式调用。再认识 1.100 时代的几个新面孔:never type ! 怎么出现在函数签名里、异步闭包 async || { } 长什么样。最后完整做一个小项目收尾,并养成写测试、看 clippy 建议的习惯。

泛型 <T>trait 定义与实现闭包 |x| x + 1异步闭包 async ||(初步)never type !map / filter / collectcargo testclippy常用包:axum · sqlx · redis(见下节)
过关标准:完成「迷你 grep」或「JSON 待办工具」项目并发布到自己的 GitHub——从这一刻起,你可以自称 Rust 初学者毕业了。
5 毕业后进阶 · 生产实战

鉴权、多租户、部署与监控

把 axum + sqlx 的骨架推到能上线:密码用 Argon2 哈希、JWT 做无状态鉴权并配刷新令牌轮换与 RBAC;多租户默认用行级 tenant_id + Postgres RLS 兜底隔离;用多阶段 Dockerfile 打包、docker-compose 本地联调、GitHub Actions 做 CI;最后用 tracing 结构化日志、/health 与 /ready 探针、Prometheus 指标把服务变得可观测。细节见下方「生产实战」专区。

Argon2 + JWTRBAC · TOTP · API Keytenant_id + RLSDocker 多阶段构建GitHub Actions CIPrometheus + tracing目标:能独立把一个多租户 API 部署上线并监控
过关标准:给毕业项目加上登录鉴权和租户隔离,用 Docker Compose 一键起全套服务,并能在 Grafana 里看到请求的成功率与延迟。

核心概念,一个一个来

点开每个概念:左边是讲人话的解释和易错点,右边是能直接跑的代码。建议顺序阅读——所有权排第一位不是偶然,它是理解后面一切的钥匙。最后一个标签页是 Edition 2024 / 1.100 新语法,专门讲 let 链、异步闭包、never type 与 DropGuard。

所有权:每个值都有一个主人

Rust 管理内存靠三条规则:每个值有且只有一个所有者;所有者离开作用域,值就被自动释放;所有权可以转移(move),但同一时刻只有一个主人。

整数这类小而固定的数据存在栈上,赋值时直接复制(Copy);而 String 这类在堆上分配的数据,赋值会「移动」所有权——原来的变量随即失效。这样既避免了重复释放,又不需要 GC 在运行时巡逻。

  • 作用域结束时,Rust 自动调用 drop 释放资源,不用手动 free。
  • 想真正复制一份堆数据,用 .clone()——代价明确写在代码里。
  • 把值传给函数也会移动所有权,除非函数把它再返回来。
经典报错:移动后再使用原变量会得到 value used after move。这不是编译器找茬——它在阻止你使用一份已经被「送走」的数据。解法通常是借用(下一个概念)而不是 clone。
ownership.rs
fn main() {
    let a = String::from("hello");
    let b = a;               // 所有权从 a 移动到 b
    // println!("{}", a);    // ✗ 编译错误:a 已失效
    println!("{}", b);       // ✓ b 是现在的主人

    let x = 5;
    let y = x;               // i32 实现了 Copy,直接复制
    println!("{} {}", x, y); // ✓ 两个都能用
}
输出hello 5 5

借用:不拿走所有权,也能用数据

总不能每次用一下数据就把所有权送出去。用 & 创建引用就是「借用」:函数借来看一眼,用完物归原主。引用分两种:不可变引用 &T 只能读,可变引用 &mut T 可以改。

借用规则只有两条:同一时刻,要么有任意多个不可变引用,要么只有一个可变引用;引用必须始终有效(不能指向已释放的数据)。数据竞争在编译期就被堵死。

  • 函数参数写 &String 或更通用的 &str,调用方保留所有权。
  • 借可变引用前,变量本身要声明为 let mut。
  • 引用的有效期(生命周期)大多数时候编译器能自动推断,不用手写。
经典报错:cannot borrow as mutable because it is also borrowed as immutable——读写引用同时存在。解法:缩小借用的使用范围,让不可变借用先结束(用完即还),再借可变的。
borrow.rs
fn len_of(s: &String) -> usize {
    s.len()  // 只借来看长度,不拿走所有权
}

fn main() {
    let mut s = String::from("Rust");
    println!("长度: {}", len_of(&s));

    let r = &mut s;      // 可变借用
    r.push_str("acean");
    println!("{}", s);   // s 还是主人
}
输出长度: 4 Rustacean

结构体:把数据和行为装在一起

struct 把相关字段打包成一个自定义类型;impl 块给它添方法。第一个参数是 &self 的是普通方法(借用自己来读或改),没有 self 的是「关联函数」,常用来当构造器,比如 String::from(...)。

给结构体加上 #[derive(Debug)] 就能用 {:?} 打印出来调试——这是新手最该先学会的一个小魔法。

  • 更新语法 ..other 可以用已有实例的剩余字段填充新实例。
  • 元组结构体 struct Color(i32, i32, i32); 适合给一组数起个类型名。
  • 方法里改数据要写 &mut self,且实例本身要是 mut。
易错点:结构体字段默认私有。跨模块使用时,字段和方法要加 pub 才能被外部访问——报错说 field is private 时先想到它。
struct.rs
#[derive(Debug)]
struct Rect { width: u32, height: u32 }

impl Rect {
    fn area(&self) -> u32 { self.width * self.height }
    fn square(size: u32) -> Self {
        Self { width: size, height: size }
    }
}

fn main() {
    let r = Rect { width: 30, height: 50 };
    println!("{:?} 的面积是 {}", r, r.area());
    let s = Rect::square(10);
    println!("正方形面积: {}", s.area());
}
输出Rect { width: 30, height: 50 } 的面积是 1500 正方形面积: 100

枚举与模式匹配:状态只有这几种可能

Rust 的 enum 比多数语言的枚举强得多:每个变体可以携带不同类型的数据。配合 match 使用时,编译器会检查你是否处理了所有情况——漏掉一个分支,代码根本编译不过。

标准库的 Option<T> 就是枚举:Some(值) 或 None。Rust 没有 null,「可能没有值」必须在类型里明说,再被 match 强制处理——一整类运行时崩溃就此消失。

  • match 的每个分支是一个「模式 → 表达式」,必须穷尽所有可能。
  • 只关心一种情况时用 if let,更简洁。
  • _ 是兜底模式,匹配其余一切情况。
经典报错:non-exhaustive patterns——match 没覆盖全。别急着加 _ 糊弄过去,先想想:新情况真的不需要单独处理吗?编译器是在提醒你补逻辑。
enum_match.rs
enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
}

fn describe(m: &Message) -> String {
    match m {
        Message::Quit => String::from("退出"),
        Message::Move { x, y } => format!("移动到 ({}, {})", x, y),
        Message::Write(text) => format!("写下: {}", text),
    }
}

fn main() {
    let m = Message::Move { x: 3, y: 7 };
    println!("{}", describe(&m));
}
输出移动到 (3, 7)

错误处理:错误也是返回值

Rust 没有异常。可恢复的错误用 Result<T, E> 返回:成功是 Ok(值),失败是 Err(错误),调用方必须表态怎么处理。不可恢复的错误才用 panic! 直接终止程序。

? 运算符是日常写法:放在返回 Result 的表达式后面,成功就取出值继续,失败就立刻把错误 return 给上层。一行一个 ?,主流程干净得像没出错一样。

  • unwrap() 遇到 Err 会 panic——只适合写草稿和确信不会失败的场合。
  • expect("说明") 比 unwrap 多一句上下文,调试时友好得多。
  • 练习阶段先用 Box<dyn Error> 当统一错误类型,省去自定义错误类型的样板。
易错点:? 只能用在返回 Result(或 Option)的函数里。在 fn main() 里直接用会报错——把 main 的返回类型改成 Result<(), Box<dyn Error>> 即可。
error.rs
use std::num::ParseIntError;

fn double(s: &str) -> Result<i32, ParseIntError> {
    let n: i32 = s.trim().parse()?;  // 失败就自动 return Err
    Ok(n * 2)
}

fn main() {
    match double("21") {
        Ok(v) => println!("两倍是 {}", v),
        Err(e) => println!("解析失败: {}", e),
    }
    println!("{:?}", double("abc")); // Err 也能直接打印看
}
输出两倍是 42 Err(ParseIntError { kind: InvalidDigit })

Trait 与泛型:一份代码,多种类型

trait 定义一组行为(方法签名),类型通过 impl Trait for Type 来「认领」这些行为,类似其他语言的接口,但更灵活:你甚至能给别人的类型实现你定义的 trait。

函数参数写 impl Trait 或泛型 <T: Trait>,就是在说「只要会这项本事,什么类型都行」。编译时 Rust 会为每个具体类型生成专门的代码(单态化),所以泛型没有运行时开销。

  • trait 里的方法可以给默认实现,类型按需覆盖。
  • #[derive(...)] 就是在批量自动实现 Debug、Clone、PartialEq 等常用 trait。
  • 泛型约束写不明白时看报错——编译器通常会直接告诉你少了哪个 trait 约束。
易错点:给泛型值做 {} 打印或 == 比较会报错,因为编译器不知道任意 T 都支持这些操作。把约束补上:<T: std::fmt::Display + PartialEq>。
trait.rs
trait Summary {
    fn summarize(&self) -> String;
}

struct Article { title: String, author: String }

impl Summary for Article {
    fn summarize(&self) -> String {
        format!("《{}》— {}", self.title, self.author)
    }
}

fn notify(item: &impl Summary) {
    println!("新文章: {}", item.summarize());
}

fn main() {
    let a = Article {
        title: String::from("所有权入门"),
        author: String::from("Ferris"),
    };
    notify(&a);
}
输出新文章: 《所有权入门》— Ferris

集合与迭代器:把循环写成流水线

三大常用集合:Vec<T>(可增长数组)、String(UTF-8 文本)、HashMap<K, V>(键值对)。它们都住在堆上,所有权规则同样适用——把值放进 Vec,所有权就交给 Vec 了。

迭代器是 Rust 的日常表达方式:iter() 借用遍历、into_iter() 消耗遍历,再链上 map(变换)、filter(筛选),最后用 collect() 或 sum() 收尾。写起来像流水线,编译后和手写循环一样快。

  • 迭代器是惰性的:不调用 collect / sum 这类「消费者」,前面的 map/filter 不会真正执行。
  • 闭包 |x| x * 2 是传给 map/filter 的小函数,类型自动推断。
  • HashMap 查不到键时返回 Option——又见模式匹配,先 get 再处理 None。
易错点:遍历 Vec 的同时修改它(比如在 for 里 push)会被借用规则拦下。先用迭代器把新数据 collect 成一个新 Vec,再合并。
iter.rs
fn main() {
    let nums = vec![1, 2, 3, 4, 5, 6];

    let evens_doubled: Vec<i32> = nums.iter()
        .filter(|&&x| x % 2 == 0)   // 留下偶数
        .map(|x| x * 2)             // 每个翻倍
        .collect();
    println!("{:?}", evens_doubled);

    let total: i32 = nums.iter().sum();
    println!("总和: {}", total);
}
输出[4, 8, 12] 总和: 21

新语法:let 链、never type 与 DropGuard

这一页是「现在写 Rust」的样子,前提是 Edition 2024 + Rust 1.100。四样东西最值得先认识:

① let 链(1.88,2024 独占)——多个 let 和普通条件用 && 串在同一个 if / while 里,前面的绑定在后面的条件里直接可用,嵌套金字塔就此消失。注意链里不能用 ||。

② never type !(1.100 稳定)——表示「永远不产生值」的类型。panic!、return、死循环的表达式类型都是 !,它能自动转成任何类型,所以能塞进 match 的某个分支。现在还能写 Result<T, !> 明说「不会失败」,Infallible 已是它的别名。

③ 异步闭包(1.85)——async |x| { ... },闭包本身返回 future,配合 AsyncFn trait 写异步回调终于不用绕弯。

④ DropGuard(1.100)——std::mem::DropGuard::new(值, 闭包):值被 drop 时执行闭包,正常、? 返回、panic 都不漏;DropGuard::dismiss(guard) 取回值并取消清理,天生适合「失败回滚」。

  • let 链报错 let chains are only allowed in Rust 2024 or later = 你的 edition 还是 2021,先升级再写。
  • 函数签名写 -> ! 表示这个函数永不返回(如内部 panic 或调 std::process::exit)。
  • 老写法 let Ok(v) = res; 能成立,正是因为失败分支的类型是 !——不可能发生。
易错点:把 2024 项目的代码贴进 2021 项目,let 链和异步闭包都会报错。先看对方项目的 Cargo.toml 里 edition 写的是哪一年,再判断语法能不能用。
modern.rs — Edition 2024 / Rust 1.100
use std::mem::DropGuard;

// never type:Result<T, !> 表示不可能失败(1.100 起可写)
fn infallible_unwrap<T>(res: Result<T, !>) -> T {
    let Ok(v) = res;
    v
}

fn main() {
    let user = Some("Ferris");
    let score = Some(95);

    // let 链(1.88+,Edition 2024):一行串起两个 let 和一个条件
    if let Some(name) = user && let Some(s) = score && s >= 60 {
        println!("{name} 通过,分数 {s}");
    }

    println!("{}", infallible_unwrap(Ok(42)));

    // DropGuard(1.100):离开作用域时自动执行清理闭包
    let mut guard = DropGuard::new(vec![1, 2], |v| {
        println!("守卫清理: {v:?}");
    });
    guard.push(3);  // 通过 DerefMut 像 Vec 一样用
    println!("当前有 {} 个元素", guard.len());
} // ← guard 在这里被 drop,打印「守卫清理: [1, 2, 3]」
输出Ferris 通过,分数 95 42 当前有 3 个元素 守卫清理: [1, 2, 3]

常用包(Crates):写真实项目的那套轮子

Rust 标准库刻意保持精简,真实项目靠 crates.io 上的包(crate)拼装。下面按做后端 / 写 API 时的实际需求分七类:Web API、数据库与 ORM、S3 对象存储、配置文件、定时任务、缓存,外加一个日常工具箱。每个包都给「选哪个、依赖怎么写、最小可用代码长什么样」。版本只写主版本即可——Cargo 会自动解析兼容的最新版;细节 API 以 docs.rs 上对应包的文档为准。

需求首选包一句话定位
Web APItokio axum异步运行时 + 目前最主流的 Web 框架,写 REST API 的默认组合
数据库 / ORMsqlx sea-ormsqlx 直写 SQL(编译期校验);sea-orm 是异步 ORM,不想写 SQL 时用它
S3 对象存储aws-sdk-s3AWS 官方 SDK;连 AWS S3 以及阿里云 OSS、MinIO 等 S3 兼容存储
配置文件config dotenvy分层读 toml / yaml / .env / 环境变量,一次反序列化成结构体
定时任务tokio-cron-scheduler在 tokio 里按 cron 表达式跑异步任务,不用另起系统 crontab
缓存redis mokaredis 是跨进程 / 分布式缓存;moka 是单进程内的高性能内存缓存
鉴权argon2 jsonwebtoken totp-rs密码哈希、JWT 签发校验、两步验证;生产实战专区有完整接法
监控指标axum-prometheus tracing把请求量、错误率、延迟暴露成 Prometheus 指标,配 Grafana 看板与告警
日常工具箱serde reqwest anyhow序列化、发 HTTP 请求、错误处理、日志、时间、命令行参数——几乎每个项目都装
Cargo.toml — 一个后端项目的常用依赖全集(按需删减)
[dependencies]
tokio = { version = "1", features = ["full"] }       # 异步运行时,几乎所有网络包的地基
axum = "0.8"                                          # Web API 框架
serde = { version = "1", features = ["derive"] }  # 序列化 / 反序列化
serde_json = "1"
sqlx = { version = "0.8", features = ["runtime-tokio", "tls-rustls", "postgres"] }
sea-orm = { version = "1", features = ["sqlx-postgres", "runtime-tokio-rustls"] }
aws-config = "1"     # S3:官方 AWS SDK 的配置加载
aws-sdk-s3 = "1"
config = "0.15"      # 配置文件分层读取
dotenvy = "0.15"     # 读取 .env 文件
tokio-cron-scheduler = "0.13"  # 定时任务
redis = { version = "0.27", features = ["tokio-comp", "connection-manager"] }
moka = { version = "0.12", features = ["future"] }  # 进程内缓存
reqwest = { version = "0.12", features = ["json"] }  # HTTP 客户端
tracing = "0.1"      # 结构化日志
anyhow = "1"       # 应用层错误处理
thiserror = "2"    # 库层自定义错误类型
argon2 = "0.5"       # 密码哈希(生产实战:鉴权)
jsonwebtoken = "9"  # JWT 签发与校验
axum-prometheus = "0.8" # Prometheus 指标(生产实战:监控)
chrono = "0.4"       # 日期时间(或用 time crate)
uuid = "1"           # 生成 UUID
clap = { version = "4", features = ["derive"] }  # 命令行参数解析
1

Web API:tokio + axum

写接口、做后端服务

tokio 是异步运行时——没有它,axum、sqlx、redis 这些异步包都跑不起来,入口就是给 main 加一行 #[tokio::main]。axum 是 tokio 团队维护的 Web 框架,路由、JSON、提取请求参数都围绕普通函数和 trait 设计,目前新项目的默认选择;中间件生态用同系的 tower-http(CORS、日志、静态文件)。

  • 路由就是 Router::new().route("/路径", get(处理函数)),处理函数是普通 async fn。
  • 返回 Json(结构体) 自动序列化——结构体记得 #[derive(Serialize)](来自 serde)。
  • 共享状态(数据库连接池等)用 .with_state(...) 注入,处理函数里以 State 参数取出。
怎么选:新项目直接 axum;老教程里的 actix-web、rocket 也仍在维护,但生态势头和 tokio 的贴合度以 axum 最好。
api.rs — 最小可用的 JSON API
use axum::{routing::get, Json, Router};
use serde::Serialize;

#[derive(Serialize)]
struct Health { ok: bool, version: &'static str }

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let app = Router::new()
        .route("/health", get(|| async {
            Json(Health { ok: true, version: "1.100" })
        }));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await?;
    axum::serve(listener, app).await?;
    Ok(())
}
请求 GET /health 返回{"ok":true,"version":"1.100"}
2

数据库与 ORM:sqlx / SeaORM

连 PostgreSQL / MySQL / SQLite

两条路线:sqlx 直写 SQL,自带连接池,宏能在编译期连库校验 SQL 写得对不对,是目前用得最广的方案;SeaORM 建在 sqlx 之上,是真正的异步 ORM——定义 Entity 后用链式 API 查询,不手写 SQL,还带迁移工具 sea-orm-cli。同步风格的老牌 ORM 是 Diesel(编译期校验最强,但异步支持弱,新项目优先前两者)。

  • 连接串从配置 / 环境变量读:postgres://user:pass@localhost:5432/mydb,不要写死在代码里。
  • sqlx 用 PgPoolOptions 建连接池,整个应用共享一个池(放进 axum 的 State 里正好)。
  • 参数用 .bind() 或宏里的占位符传,永远不要用 format! 拼 SQL——那是注入漏洞。
  • SeaORM 先用 sea-orm-cli generate entity 从现有表生成 Entity 代码,再写查询。
怎么选:SQL 熟练、想要可控 → sqlx;表多、CRUD 多、想少写 SQL → SeaORM;只是练手或小工具 → sqlx + SQLite 最省事。
db_sqlx.rs — sqlx 连接池 + 参数化查询
use sqlx::postgres::PgPoolOptions;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let pool = PgPoolOptions::new()
        .max_connections(10)
        .connect("postgres://user:pass@localhost:5432/mydb").await?;

    // $1 是占位符,值用 bind 传 —— 防 SQL 注入
    let row: (i64, String) = sqlx::query_as("SELECT id, name FROM users WHERE id = $1")
        .bind(1_i64)
        .fetch_one(&pool).await?;
    println!("{}: {}", row.0, row.1);
    Ok(())
}
db_orm.rs — SeaORM 同一件事的 ORM 写法
use sea_orm::{Database, EntityTrait};
// user::Entity 由 sea-orm-cli 按表结构生成
let db = Database::connect(url).await?;
let admin = user::Entity::find_by_id(1).one(&db).await?;
println!("{:?}", admin); // Option<Model>:查不到是 None
3

S3 对象存储:aws-sdk-s3

上传 / 下载文件、生成临时下载链接

官方的 aws-sdk-s3(配套 aws-config 加载凭证)是现在的标准选择,老教程里的 rusoto 已停止维护,别再用。它不只能连 AWS S3:把 endpoint 换掉,就能连阿里云 OSS、腾讯云 COS 的 S3 兼容接口和自建 MinIO——这点对国内项目很实用。凭证走环境变量 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY,不要硬编码进代码。

  • 上传:put_object().bucket(..).key(..).body(ByteStream::from(..)),链式 builder 是 AWS SDK 的统一风格。
  • 大文件用分片上传(multipart),SDK 提供 Transfer Manager / 手动分片 API,几个 MB 以内直传即可。
  • 给前端临时下载链接用 presigned URL:签名一个带过期时间的 URL,不用公开桶权限。
  • 连兼容存储时:在 aws-config 里设置自定义 endpoint(如 OSS 的 https://oss-cn-hangzhou.aliyuncs.com)与 region 即可,其余代码不变。
注意:bucket 名、key、凭证都从配置读(见第 4 节);key 就是文件在桶里的「路径」,如 uploads/2026/report.pdf。
s3.rs — 上传 + 生成预签名下载链接
use aws_sdk_s3::{presigning::PresigningConfig, primitives::ByteStream, Client};
use std::time::Duration;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // 从环境变量 / ~/.aws 自动加载凭证与 region
    let config = aws_config::load_defaults(aws_config::BehaviorVersion::latest()).await;
    let client = Client::new(&config);

    client.put_object()
        .bucket("my-bucket")
        .key("hello.txt")
        .body(ByteStream::from_static(b"hello s3"))
        .send().await?;

    // 1 小时有效的临时下载链接(预签名 URL)
    let presigned = client.get_object()
        .bucket("my-bucket").key("hello.txt")
        .presigned(PresigningConfig::expires_in(Duration::from_secs(3600))?).await?;
    println!("下载链接: {}", presigned.uri());
    Ok(())
}
4

配置文件读取:config + dotenvy

toml / yaml / .env / 环境变量分层覆盖

规矩先立好:配置和代码分离——连接串、密钥、端口都不写死。config crate 能按顺序叠加多个来源(默认文件 → 按环境区分的文件 → 环境变量,后者覆盖前者),最后一次 try_deserialize 变成带类型的结构体,字段缺失或类型不对启动时就报错。dotenvy 负责本地开发时把 .env 文件加载成环境变量(dotenv 的维护版 fork);生产环境直接用真实环境变量,不放 .env 文件。

  • 结构体字段和配置键一一对应,配上 serde 的 Deserialize 即可,类型写错启动即失败——比运行时才发现好得多。
  • 环境变量覆盖时用前缀区分,如 APP_PORT=8080、APP_DATABASE_URL=...。
  • .env 必须写进 .gitignore:里面是密钥,进了仓库就等于公开。
# .env(本地开发用,不提交 git) APP_PORT=3000 DATABASE_URL=postgres://user:pass@localhost:5432/mydb REDIS_URL=redis://127.0.0.1:6379
怎么选:只有几个环境变量 → dotenvy + std::env::var 手动读就够;配置项一多、有多环境文件 → 上 config 分层。
settings.rs — 分层配置读成结构体
use config::{Config, Environment, File};
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Settings {
    port: u16,
    database_url: String,
    redis_url: String,
}

fn main() -> anyhow::Result<()> {
    dotenvy::dotenv().ok(); // 先加载 .env(没有也不报错)
    let settings = Config::builder()
        .add_source(File::with_name("config/default"))  // .toml / .yaml 都行
        .add_source(Environment::with_prefix("APP")) // 环境变量后加载,覆盖文件
        .build()?
        .try_deserialize::<Settings>()?;
    println!("监听端口 {port}", port = settings.port);
    Ok(())
}
5

定时任务:tokio-cron-scheduler

每天凌晨清理、每分钟同步、定时报表

任务跑在进程内部、又需要异步(查库、调 API)时,用 tokio-cron-scheduler:给它一条 cron 表达式和一个异步闭包即可,还能拿到任务 UUID 做暂停 / 删除。注意它的 cron 是七段式:秒 分 时 日 月 周 年,比 Linux crontab 多了秒和年,照五段式写会对不上。

  • "0 0 2 * * * *" = 每天凌晨 2:00:00;"0 */5 * * * * *" = 每 5 分钟。
  • 只想「每隔 N 秒跑一次」更简单:tokio 自带的 tokio::time::interval 就够,不用装包。
  • 多实例部署时每个实例都会触发——生产环境要配分布式锁或只在一台机器上启用调度,别重复发报表。
怎么选:单机小服务 → 进程内调度最省事;任务重、要失败重试和执行记录 → 交给系统 crontab / 外部调度平台调你的 CLI 或接口。
cron_job.rs — 每天凌晨 2 点跑一次
use tokio_cron_scheduler::{Job, JobScheduler};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut sched = JobScheduler::new().await?;
    // 七段式 cron:秒 分 时 日 月 周 年 —— 每天 02:00:00
    let job = Job::new_async("0 0 2 * * * *", |_uuid, _sched| {
        Box::pin(async move {
            println!("开始每日清理任务…");
            // 这里 await 查库 / 调 API 都可以
        })
    })?;
    sched.add(job).await?;
    sched.start().await?;
    tokio::signal::ctrl_c().await?; // 等 Ctrl+C 退出
    Ok(())
}
6

缓存:redis + moka

热点数据加速、限流计数、会话存储

两层思路:redis crate 连 Redis 服务——缓存活在进程之外,多台机器共享,还能顺手做限流计数、排行榜、分布式锁;moka 是进程内缓存,API 就是一个带过期和容量上限的 HashMap,零运维,适合缓存「算一次很贵、几分钟内不会变」的结果。常见搭配:先查 moka → 再查 redis → 最后查数据库,逐层回填。

  • 缓存一定要设过期时间(TTL):redis 用 set_ex(key, val, 秒),moka 在 builder 里设 time_to_live。
  • 缓存的值通常存 JSON 字符串:结构体先 serde_json::to_string,取出再解析回来。
  • redis 异步连接用 get_multiplexed_async_connection(),一条连接多路复用,整个应用共享。
怎么选:单机、能接受重启丢缓存 → moka;多实例共享、要持久或要计数器 → redis;两者叠加就是生产里最常见的两级缓存。
cache_redis.rs — Redis 读写带过期
use redis::AsyncCommands;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let client = redis::Client::open("redis://127.0.0.1:6379/")?;
    let mut conn = client.get_multiplexed_async_connection().await?;
    let _: () = conn.set_ex("user:1:name", "Ferris", 60).await?; // 存 60 秒
    let name: Option<String> = conn.get("user:1:name").await?;
    println!("{name:?}"); // Some("Ferris"),过期后是 None
    Ok(())
}
cache_moka.rs — 进程内缓存,三行上手
use moka::future::Cache;
use std::time::Duration;

let cache: Cache<String, i32> = Cache::builder()
    .max_capacity(10_000)
    .time_to_live(Duration::from_secs(60))
    .build();
cache.insert("answer".to_string(), 42).await;
println!("{:?}", cache.get(&"answer".to_string()).await); // Some(42)
7

日常工具箱:几乎每个项目都装

序列化、HTTP 客户端、日志、错误、时间、CLI

这组包不分领域、出现频率最高:serde + serde_json 处理一切 JSON / 结构体互转;reqwest 发 HTTP 请求调别人的 API;tracing 打结构化日志;anyhow(应用层)+ thiserror(库层)处理错误;chrono 管日期时间;uuid 生成唯一 ID;clap 解析命令行参数。先认识 reqwest 和 serde 这对最常见的组合:

  • reqwest 的 .json::<T>() 直接把响应体反序列化成结构体——T 只要 derive 了 Deserialize。
  • 日志别再 println!:tracing::info! 带级别和字段,配 tracing-subscriber 输出,上线可按环境变量调级别。
  • 错误分工:main 和业务代码里用 anyhow 的 Result 快速传播;写给别人用的库,用 thiserror 定义自己的错误枚举。
加包小技巧:不用手敲 Cargo.toml——终端里 cargo add axum sqlx 会自动写入最新版号并解析 features。
http.rs — reqwest 调 API + serde 接数据
use serde::Deserialize;

#[derive(Debug, Deserialize)]
struct Release { tag_name: String, name: String }

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let rel: Release = reqwest::Client::new()
        .get("https://api.github.com/repos/rust-lang/rust/releases/latest")
        .header("User-Agent", "rust-learning-demo")
        .send().await?
        .error_for_status()?
        .json().await?;
    println!("最新版: {} ({})", rel.tag_name, rel.name);
    Ok(())
}
说明响应 JSON 里多余的字段会被自动忽略,只取结构体里声明的两个字段。

把这一节串成一个项目:用 axum 起 API 服务 → config 读配置 → sqlx / SeaORM 连数据库 → 热点数据过 redis 缓存 → 文件上传走 S3 → tokio-cron-scheduler 每天凌晨跑一次数据清理。这就是一个完整后端的骨架,第 7–8 周的毕业项目可以直接按这个清单练一遍。要把它推到能上线,再接下一节「生产实战」:加鉴权与多租户隔离,用 Docker 部署,用 Prometheus + tracing 做监控。查包先上 crates.io 看下载量与维护状态,查用法看 docs.rs 的示例。

生产实战:鉴权、多租户、部署与监控

上一节的 axum + sqlx 骨架能跑通接口,但离「敢上线给别人用」还差四件事:谁能进来(鉴权)、数据怎么隔离(多租户)、怎么交付运行(部署)、出事怎么知道(监控)。这一节按真实 SaaS 后端的顺序把四块补齐,代码仍以 Rust 1.100 / Edition 2024、axum 0.8、sqlx + PostgreSQL 为基准,可直接接在常用包的代码后面。

鉴权

登录与权限:Argon2 + JWT + RBAC

密码哈希 · 令牌 · 刷新轮换 · 两步验证 · API Key

鉴权分两步:认证(你是谁)和授权(你能做什么)。密码绝不明文或普通哈希存库——用 argon2 做慢哈希加盐;登录成功后签发 jsonwebtoken 的 JWT 访问令牌(短期、无状态),再配一个可吊销的刷新令牌(长期、存库);权限用 RBAC 角色控制,需要更高安全等级时再加 TOTP 两步验证和给机器用的 API Key。

  • 密码:Argon2::default() 哈希,每次用 SaltString::generate(OsRng) 生成随机盐;校验用 verify_password。存的是哈希串本身,盐已经在里面。
  • 访问令牌 JWT:Claims 至少放 sub(用户 ID)、tenant_id、role、exp;有效期短(15 分钟量级),密钥从环境变量读,校验时钉死算法和过期时间。
  • axum 提取器:实现 FromRequestParts 的 AuthUser,handler 参数里写上它就等于「必须登录」,解析失败直接返回 401,后续多租户也从这里取 tenant。
  • 刷新令牌轮换:刷新令牌只存哈希到库里,每次刷新都发新的、作废旧的;如果旧令牌被再次使用,说明可能被盗,立刻吊销该用户的整条令牌链并要求重新登录。
  • RBAC:角色先粗后细——Owner / Admin / Member / Viewer 枚举 + 一个 require_role 检查;再补资源级判断(「只能改自己创建的」),不要只靠前端藏按钮。
  • TOTP 两步验证:totp-rs 生成密钥和二维码 URI,用户用验证器 App 绑定;密钥加密后存库,校验时允许 ±1 个时间步的时钟偏差,并给一次性恢复码。
  • API Key:给脚本和第三方集成用——格式 sk_live_xxxx,库里只存哈希,明文只在创建时展示一次,支持单独吊销和限定权限范围。
凭证适合谁有效期 / 吊销
JWT 访问令牌网页 / App 的日常请求分钟级;靠短过期自然失效
刷新令牌换取新访问令牌天/周级;存库可随时吊销,轮换防盗用
API Key脚本、服务端集成长期;按 key 单独吊销
TOTP登录的第二因素30 秒滚动码;解绑需重新验证
常见坑:把 JWT 当会话存敏感信息(它只是签名不是加密,任何人都能解开看)、密钥写进代码仓库、登录接口不做限流——这三件是新手鉴权最常翻车的地方。
auth.rs — Argon2 哈希 + JWT 签发
use argon2::{Argon2, PasswordHash, PasswordHasher, PasswordVerifier};
use argon2::password_hash::{rand_core::OsRng, SaltString};
use jsonwebtoken::{encode, EncodingKey, Header};

fn hash_password(plain: &str) -> anyhow::Result<String> {
    let salt = SaltString::generate(&mut OsRng);
    let hash = Argon2::default()
        .hash_password(plain.as_bytes(), &salt)
        .map_err(|e| anyhow::anyhow!(e))?;
    Ok(hash.to_string())
}

fn verify_password(plain: &str, stored: &str) -> bool {
    let Ok(h) = PasswordHash::new(stored) else { return false };
    Argon2::default().verify_password(plain.as_bytes(), &h).is_ok()
}

#[derive(Serialize)]
struct Claims { sub: String, tenant_id: String, role: String, exp: usize }

fn issue_jwt(c: &Claims, secret: &str) -> anyhow::Result<String> {
    Ok(encode(&Header::default(), c,
        &EncodingKey::from_secret(secret.as_bytes()))?)
}
extractor.rs — 在 axum 里要求登录
// handler 参数里出现 AuthUser = 这个接口必须登录,失败直接 401
struct AuthUser { user_id: String, tenant_id: String, role: String }

impl FromRequestParts<AppState> for AuthUser {
    type Rejection = StatusCode;
    async fn from_request_parts(parts: &mut Parts, state: &AppState)
        -> Result<Self, StatusCode> {
        let token = parts.headers.get("Authorization")
            .and_then(|v| v.to_str().ok())
            .and_then(|v| v.strip_prefix("Bearer "))
            .ok_or(StatusCode::UNAUTHORIZED)?;
        let data = decode::<Claims>(token,
            &DecodingKey::from_secret(state.jwt_secret.as_bytes()),
            &Validation::default())
            .map_err(|_| StatusCode::UNAUTHORIZED)?;
        Ok(AuthUser { user_id: data.claims.sub,
            tenant_id: data.claims.tenant_id, role: data.claims.role })
    }
}
用法async fn me(user: AuthUser) -> Json<…> { /* user 已验明身份 */ }
多租户

租户隔离:默认行级 tenant_id + RLS 兜底

一个系统服务多家客户,数据绝不能串

多租户的核心只有一句话:任何一次查询都只能碰到当前租户的数据。隔离有三种做法,新项目默认选第一种——所有业务表带 tenant_id、查询强制带租户条件,再用 PostgreSQL 的行级安全(RLS)做第二道防线:哪怕某条 SQL 忘了写条件,数据库也会替你拦住。

方案隔离强度成本与复杂度适合
行级共享表(tenant_id)中:靠应用 + RLS 约束最低:一套表、一套代码绝大多数 SaaS 的默认选择
Schema 隔离高:每租户一个 schema中:迁移要逐 schema 执行租户数不多、合规要求较强
独立数据库最高:物理隔离最高:连接、备份、升级都要乘以租户数大客户、强合规、需独立部署
  • 租户从哪来:从已验签的 JWT 里取 tenant_id(上一节的 AuthUser),永远不要相信前端传来的租户参数——那等于让用户自己选能看谁的数据。
  • 建模:tenants 表存租户本身;每张业务表加 tenant_id 外键 + 组合索引 (tenant_id, id),唯一约束也要带上 tenant_id。
  • RLS 兜底:给表启用 ENABLE ROW LEVEL SECURITY 并建策略,请求开始时在事务里执行 SET LOCAL app.tenant_id = …,策略只放行匹配的行。
  • 别漏的角落:缓存 key 加租户前缀 tenant:{id}:…、S3 key 加 tenants/{id}/… 前缀、定时任务和后台脚本必须显式指定租户、导出与搜索同样要过滤。
  • 配额与限流:按租户记用量(成员数、存储、API 调用),在中间件层按 tenant_id 做限流和套餐配额检查,防止一家把资源吃光。
最危险的 bug:不是黑客攻击,而是自己某条 SQL 忘了写 WHERE tenant_id = $1。所以才要 RLS 兜底 + 给每个接口写一条「用 A 租户令牌查 B 租户数据应返回 404」的测试。
tenant.sql — 建表与 RLS 策略
CREATE TABLE tenants (id uuid PRIMARY KEY, name text NOT NULL);

CREATE TABLE projects (
    id uuid PRIMARY KEY,
    tenant_id uuid NOT NULL REFERENCES tenants(id),
    title text NOT NULL
);
CREATE INDEX ON projects (tenant_id, id);

-- 行级安全:没设置 app.tenant_id 时,一行都查不到
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON projects
    USING (tenant_id = current_setting('app.tenant_id')::uuid);
tenant_query.rs — 每请求先声明租户再查
async fn list_projects(user: AuthUser, State(state): State<AppState>)
    -> anyhow::Result<Json<Vec<Project>>> {
    let mut tx = state.pool.begin().await?;
    // set_config 第三个参数 true = 只在本事务内有效
    sqlx::query("SELECT set_config('app.tenant_id', $1, true)")
        .bind(user.tenant_id.to_string())
        .execute(&mut *tx).await?;
    let rows = sqlx::query_as::<_, Project>("SELECT * FROM projects")
        .fetch_all(&mut *tx).await?; // RLS 已过滤
    tx.commit().await?;
    Ok(Json(rows))
}
部署

从 cargo run 到上线:Docker + CI + 优雅停机

多阶段构建 · Compose · GitHub Actions · K8s 基础

Rust 编译出单个原生二进制,部署天生简单:多阶段 Dockerfile 在构建阶段编译、运行阶段只留二进制,镜像可以做到几十 MB。本地和单机用 docker-compose 把 app + Postgres + Redis 一起拉起;代码推到 GitHub 后由 Actions 跑测试并构建镜像;规模再大时才上 Kubernetes。无论哪种方式,三件事不变:配置走环境变量、数据库迁移单独执行、停机要优雅。

  • 优雅停机:axum 用 with_graceful_shutdown 监听 SIGTERM / Ctrl+C,收到信号后停止接新请求、等在途请求处理完再退出——发版时用户不会撞上连接被掐断。
  • 数据库迁移:用 sqlx migrate 管理版本化迁移文件;部署时作为独立一步先跑迁移、再换新版本,不要让每个副本启动时抢着迁移。
  • 密钥管理:镜像和仓库里不放任何密钥;本地用 .env(不提交),线上用平台的 Secret / 环境变量注入,JWT 密钥、数据库密码都走这条路。
  • CI 流水线:GitHub Actions 固定四步——cargo fmt --check、cargo clippy、cargo test、构建并推送 Docker 镜像(tag 用 commit SHA,不要只用 latest)。
  • K8s 基础:Deployment 管副本、Service 暴露入口、探针指到下一节的 /health 与 /ready、配置放 ConfigMap / Secret;出问题用 kubectl rollout undo 一键回滚到上一版。
  • 发布习惯:先灰度一个副本观察指标再全量;数据库迁移保持向后兼容(先加列、后删列),这样回滚旧版本也不会炸。
怎么选:个人项目 / 单机 → docker-compose 足够;团队协作 → 加 GitHub Actions 自动构建镜像;多机、多服务、需要自动扩缩 → 再上 K8s / Helm,不要提前复杂化。
Dockerfile — 多阶段构建
# 阶段一:用官方镜像编译(版本对齐本页的 1.100)
FROM rust:1.100-bookworm AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

# 阶段二:运行镜像只带二进制,体积小、攻击面小
FROM debian:bookworm-slim
RUN useradd -m appuser
WORKDIR /app
COPY --from=builder /app/target/release/my-api .
USER appuser          # 不用 root 跑服务
EXPOSE 3000
CMD ["./my-api"]
docker-compose.yml — 本地一键全套
services:
  app:
    build: .
    ports: ["3000:3000"]
    environment:
      DATABASE_URL: postgres://app:secret@db:5432/app
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}   # 从宿主机环境注入,不写死
    depends_on:
      db: { condition: service_healthy }
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 3s
      retries: 10
    volumes: ["pgdata:/var/lib/postgresql/data"]
  redis:
    image: redis:7
volumes: { pgdata: {} }
main.rs — 优雅停机
axum::serve(listener, app)
    .with_graceful_shutdown(async {
        tokio::signal::ctrl_c().await.ok();
        // K8s 发版发 SIGTERM:生产代码再并上 unix 信号一同等待
    })
    .await?;
监控

可观测性:日志、探针、Prometheus 指标与追踪

tracing · /health 与 /ready · Grafana 告警 · OpenTelemetry

上线后你要能回答三个问题:服务活着吗、请求正常吗、慢在哪一步。对应三件套:tracing 的结构化日志(带 request_id、tenant_id 字段,能按字段搜)、健康探针(给负载均衡和 K8s 判断能不能发流量)、axum-prometheus 暴露的指标(进 Prometheus + Grafana 看板和告警)。跨服务排查再加 OpenTelemetry 把一次请求的调用链串起来。

  • 两个探针别混:/health 是存活探针,只回答「进程还在」——不要查数据库,依赖抖动不该导致进程被反复重启;/ready 是就绪探针,检查连接池能拿到连接、Redis 能 ping 通,失败返回 503,流量自动摘掉、恢复后自动挂回。
  • 看指标先看 RED:请求量(Rate)、错误率(Errors,5xx 占比)、延迟(Duration,p95 / p99 而不是平均值)。axum-prometheus 默认就按路由统计这三样。
  • 日志结构化:tracing-subscriber 输出 JSON,每条日志带 request_id 和 tenant_id;级别用 RUST_LOG 环境变量控制,线上不用改代码就能调到 debug 排查问题。
  • 分布式追踪:用 opentelemetry + OTLP 导出到 Jaeger / Tempo,一次请求在网关、服务、数据库之间的耗时一目了然;日志里带上 trace_id,就能从一条慢请求跳到完整链路。
  • 告警只报要行动的:例如「5 分钟内 5xx 比例 > 1%」「p99 延迟 > 1s 持续 10 分钟」「就绪探针连续失败」;只记录不行动的指标放看板,别进告警通道。
信号工具回答的问题
日志 Logstracing + JSON 输出具体发生过什么、哪一步报错
指标 MetricsPrometheus + Grafana整体趋势:量、错误率、延迟
追踪 TracesOpenTelemetry → Jaeger一次请求慢在哪个环节
探针 Probes/health · /ready能不能接流量、要不要重启
observability.rs — 探针 + 指标端点
use axum_prometheus::PrometheusMetricLayer;

// 存活探针:只证明进程在,不查任何依赖
async fn health() -> &'static str { "ok" }

// 就绪探针:数据库连不上就返回 503,摘掉流量
async fn ready(State(state): State<AppState>)
    -> Result<&'static str, StatusCode> {
    sqlx::query("SELECT 1").execute(&state.pool).await
        .map_err(|_| StatusCode::SERVICE_UNAVAILABLE)?;
    Ok("ready")
}

fn build_router(state: AppState) -> Router {
    let (prom_layer, prom_handle) = PrometheusMetricLayer::pair();
    Router::new()
        .route("/health", get(health))
        .route("/ready", get(ready))
        .route("/metrics", get(|| async move { prom_handle.render() }))
        .layer(prom_layer)
        .with_state(state)
}
GET /metrics 片段(Prometheus 来抓取)axum_http_requests_total{endpoint="/ready",status="200"} 128 axum_http_requests_duration_seconds_bucket{endpoint="/projects",le="0.1"} 342
logging.rs — 结构化日志初始化
tracing_subscriber::fmt()
    .json() // 一行一条 JSON,方便采集与按字段检索
    .with_env_filter(EnvFilter::from_default_env()) // 读 RUST_LOG
    .init();
tracing::info!(tenant_id = %user.tenant_id, "project created");

上线前检查清单:密码 Argon2 哈希且登录接口有限流 → JWT 短过期、刷新令牌轮换、密钥只在环境变量里 → 每张业务表带 tenant_id 且开了 RLS、跨租户访问测试通过 → Dockerfile 多阶段构建、非 root 运行、迁移单独执行、收到 SIGTERM 能优雅停机 → /health 与 /ready 已接探针、/metrics 已被 Prometheus 抓取、Grafana 上有错误率与 p99 延迟告警。四块都打勾,才算把常用包的骨架变成了生产服务。

语法速查表

写代码时最常回头看的就是这张表,已按 Edition 2024 / Rust 1.100 补上新语法行(标 ★)。建议收藏本页,卡住时先来这儿找。

写法含义
let x = 5;声明不可变变量(默认),类型可自动推断
let mut x = 5;声明可变变量,之后才能给 x 重新赋值
const MAX: u32 = 100;常量:必须标注类型,编译期求值,命名用全大写
let x: i64 = "42".parse().unwrap();类型标注:告诉编译器你想要的确切类型
&s / &mut s不可变借用 / 可变借用:不转移所有权地使用 s
s.clone()深拷贝一份数据,两个所有者互不影响
String::from("hi") / "hi".to_string()从字符串字面量创建堆上的 String
&s[0..2]切片:借用一段连续数据(如字符串的一部分)
if 条件 { } else { }if 是表达式,可以直接赋值给变量
loop { break 值; }无限循环,break 可以带一个返回值出来
for x in 1..=5 { }遍历范围:1..5 不含 5,1..=5 包含 5
fn f(x: i32) -> i32 { x + 1 }函数:最后一行不加分号就是返回值
println!("{} {:?}", a, b)格式化输出:{} 用 Display,{:?} 用 Debug
vec![1, 2, 3]快速创建 Vec,相当于手写 push 三次
expr?成功取里面的值,失败立刻 return 这个错误
#[derive(Debug, Clone)]自动为类型实现常用 trait
#[test]标记测试函数,用 cargo test 运行
edition = "2024" ★Cargo.toml 里声明语言版本;1.85 起 cargo new 默认值,解锁 let 链等新语法
println!("{name} 的分数是 {s}") ★内联格式化:变量直接写进字符串,现在的标准写法
if let Some(x) = a && let Some(y) = b { } ★let 链(1.88 · 2024):多个 let 与条件用 && 串联,免嵌套;链中不能用 ||
let Some(x) = opt else { return; };let-else:匹配失败就走 else 分支提前退出,主流程不缩进
async |x| { ... } ★异步闭包(1.85):闭包直接返回 future,配套 AsyncFn trait
fn f() -> ! / Result<T, !> ★never type(1.100 稳定):表示永不返回 / 不可能失败;Infallible 是它的别名
static C: LazyLock<Vec<i32>> = LazyLock::new(|| vec![1, 2]);LazyLock(1.80):全局变量第一次用到时才初始化,替代 lazy_static
DropGuard::new(v, |v| { }) ★DropGuard(1.100):值离开作用域时执行闭包;dismiss() 取回值并取消
global-min-publish-age = "3 days" ★Cargo 依赖冷却期(1.100):写在 .cargo/config.toml,跳过刚发布的新版本

三个练手项目

看懂和写出之间隔着一百次编译错误。按顺序做,每个都对应路线图的一个阶段。

项目一 · 第 1–2 周后

猜数字游戏加强版

在官方教程的猜数字基础上加料:限制猜测次数、记录每轮成绩、输入非法时不崩溃而是提示重试。用 rand crate 生成随机数——顺便学会给 Cargo.toml 加第一个依赖。

  1. 跑通官方原版,读懂每一行
  2. 给游戏加 7 次机会上限与输赢结算
  3. 把成绩追加写入 scores.txt
std::ioloop + match外部 crate文件写入
项目二 · 第 5–6 周后

命令行待办清单

一个能真正日常用的小工具:todo add 买牛奶、todo list、todo done 1。待办项存成文件,重启不丢失。重点练习结构体建模和错误处理——全程禁止用 unwrap 糊弄;解析参数时顺便用上 Edition 2024 的 let 链和 let-else。

  1. 定义 Task 结构体与状态枚举
  2. 解析 std::env::args 的子命令(用 let 链写平校验)
  3. 用 serde_json 把列表存到本地文件
struct + enumResult 与 ?serde 依赖CLI 参数
项目三 · 第 7–8 周后

迷你 grep(minigrep)

官方教程的经典收尾项目:在文件里搜索包含关键词的行。进阶版再支持忽略大小写开关和递归搜索文件夹。这是把所有权、生命周期、trait、迭代器、测试串成一串的「毕业设计」。

  1. 先写死参数跑通核心搜索函数
  2. 抽出 Config 结构体管理配置
  3. 改用迭代器重写搜索,并补单元测试
生命周期迭代器cargo test模块拆分

和借用检查器相处的心法:报错不是敌人,是免费的代码审查。先完整读一遍报错(包括它给的 help 建议),再动手改;十次里有八次,照着编译器的提示改就能过。实在想不通,把所有权「谁拥有、借给了谁、借多久」在纸上画出来,问题通常自己就浮出来了。

自测一下

九道题,覆盖所有权、借用、可变性、Option、迭代器、最新版的 let 链,再加三道生产实战题:密码存储、租户隔离、健康探针。点选答案立刻出结果——错了也没关系,解析里有出处概念。

1. 下面代码能编译通过吗?

let s1 = String::from("hi");
let s2 = s1;
println!("{}", s1);

String 存在堆上,赋值发生所有权移动(move),s1 随即失效,再使用会报 value used after move。想两个都用:要么 s1.clone(),要么用引用借用。

2. 想让一个函数「看一眼字符串、算个长度」,又不夺走调用方的所有权,参数应该写成?

引用即借用:函数只借不拿。其中 &str 更通用——String 和字符串字面量都能自动适配到 &str,所以实际项目里优先用它。

3. 关于 Rust 的变量,下面哪句是对的?

默认不可变是 Rust 的刻意设计:让「哪里会变」在代码里一眼可见。常量用 const 声明,必须标注类型。

4. Option<T> 存在的意义是?

Option 只有 Some(值) 和 None 两种状态。用 match 或 if let 取值时,编译器会逼你把 None 的情况也写出来——空指针异常在编译期就被消灭。

5. 这段代码的输出是?

let v = vec![1, 2, 3, 4];
let s: i32 = v.iter().filter(|&&x| x > 2).sum();
println!("{}", s);

filter 留下大于 2 的元素 3 和 4,sum 求和得 7。注意迭代器是惰性的:是最后的 sum() 真正驱动了整条流水线执行。

6.(最新版)在 Edition 2024 项目里,这行代码为什么能编译?

if let Some(name) = user && let Some(s) = score && s >= 60 {
    println!("{name}: {s}");
}

let 链是 Edition 2024 的招牌新语法(Rust 1.88 稳定):前面的绑定在后面的条件里直接可用,一行替代三层嵌套 if let。同样的代码在 edition 2021 的项目里会报 let chains are only allowed in Rust 2024 or later。顺带一提,never type ! 则在 1.100 才正式稳定。

7.(生产实战)用户密码应该怎么存进数据库?

密码必须用 Argon2(或 bcrypt / scrypt 这类慢哈希)加每用户随机盐存储:拖库后攻击者也难以批量撞出明文。MD5 / SHA 这类快哈希几秒就能暴力破解,等于没存好。见「生产实战 · 鉴权」。

8.(生产实战)多租户系统里,当前租户的 tenant_id 应该从哪里取?

租户身份必须来自服务端验签后的令牌,前端传来的参数可以任意伪造。再配合每张业务表的 tenant_id 条件和 Postgres 行级安全(RLS),某条 SQL 忘了过滤也不会串数据。见「生产实战 · 多租户」。

9.(生产实战)/health(存活)和 /ready(就绪)探针的区别是?

存活探针失败会导致进程被重启,所以它绝不能依赖外部服务——数据库抖一下不该把好端端的进程重启掉。就绪探针才查依赖,失败只是暂时不接流量,恢复后自动挂回。见「生产实战 · 监控」。

得分 0 / 9 答完一题,这里会更新你的进度。

接着往下学的资源

都是社区公认的主线材料,按这个顺序用:中文教程打底 → 官方 Book 系统过一遍 → Rustlings 刷题巩固 → 遇到问题查圣经和标准库。

圣

《Rust 语言圣经》

目前最用心的中文 Rust 教程,170 余章,从入门到异步、性能优化都有,讲解生动、示例丰富。适合当主教材通读。

course.rs
B

The Rust Programming Language(官方 Book)

官方出品的系统教程,猜数字、minigrep、小型 Web 服务器三个项目串起全部核心概念。英文原版更新最快。

doc.rust-lang.org/book
译

官方 Book 简体中文版

《Rust 程序设计语言》社区中文翻译,与英文原版章节一一对应。英文吃力时对照着读,术语也能对上。

rustwiki.org/zh-CN/book
练

Rustlings 在线版

官方小练习集:在浏览器里改代码、修编译错误,一题一个知识点。专治「看懂了但写不出」。

rustlings.rust-lang.org
码

Rustlings 本地版(GitHub)

把练习装到自己电脑上做,体验完整的 cargo 工作流和真实编译器报错,做完一整套基本就算入了门。

github.com/rust-lang/rustlings
战

现代 Rust 实战教程(Web 后端)

以 tokio + axum + sqlx 为主线讲生产级 Web 后端与 SaaS:鉴权、多租户、部署、监控等主题很全。本页「生产实战」专区即参考它补齐,深入某个主题时可以对照它逐章细读(注意它基于 Rust 1.97.1,版本以本页的 1.100 为准)。

rust-web-tutorial.llapp.com
新

Rust 1.100.0 官方发布公告

当前最新版的第一手说明:never type 稳定、Allocator API、DropGuard、Cargo 依赖冷却期与无用依赖提醒,都出自这篇。想追每个新版本的变化,盯住官方博客即可。

blog.rust-lang.org/2026/11/12/Rust-1.100.0

给自己定个节奏:每天 1 小时、连学 8 周,好过周末突击一整天。Rust 的概念需要「睡一觉再回来看」——很多今天卡死的借用问题,第二天重读报错就通了。学完这个页面只是起点,真正的进步发生在你敲 Rustlings 和做项目的过程里。