生态 crate 与配置

常用 crate 地图与配置管理、运行时行为。

必知 crate 地图

下面每条给出 cargo add 命令 + 一句话定位 + 最小示例。版本号是本章写作时的主流线，实际请以 cargo add 解析结果为准。

serde + serde_json：序列化的事实标准

cargo add serde --features derive
cargo add serde_json

use serde::{Deserialize, Serialize};

/// API 返回的用户对象。
///
/// `rename_all` 让 Rust 的 snake_case 与 JSON 的 camelCase 自动对应，
/// 避免每个字段都手写 rename。
#[derive(Debug, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct User {
    /// 用户 ID。
    pub user_id: u64,
    /// 昵称。
    pub display_name: String,
    /// 可选备注：为 None 时**不输出这个键**，而不是输出 `null`。
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub bio: Option<String>,
    /// 解析时把未知字段收集到这里，实现「向前兼容」。
    #[serde(flatten)]
    pub extra: std::collections::HashMap<String, serde_json::Value>,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let u = User {
        user_id: 7,
        display_name: "Ada".to_owned(),
        bio: None,
        extra: Default::default(),
    };
    let s = serde_json::to_string_pretty(&u)?;
    println!("{s}");            // bio 字段整体消失

    // 动态 JSON 用 Value；不要在能定义 struct 的地方长期用 Value
    let v: serde_json::Value = serde_json::from_str(r#"{"userId":8,"unknown":true}"#)?;
    println!("{}", v["userId"]);                 // 8
    println!("{}", v["unknown"].as_bool().unwrap_or(false));   // true

    Ok(())
}

要点与常见属性：

需求	写法
跳过序列化	#[serde(skip_serializing_if = "Option::is_none")]、skip_serializing
缺失时用默认值反序列化	#[serde(default)]（可配 default = "fn_path"）
改键名	#[serde(rename = "id")]、rename_all = "kebab-case"
内联嵌套结构	#[serde(flatten)]（注意：与 deny_unknown_fields 不兼容）
枚举表示法	#[serde(tag = "type")]（内部标签）、untagged
拒绝未知字段	#[serde(deny_unknown_fields)]（库的公开 API 慎用，破坏向前兼容）
字段级自定义	#[serde(with = "module")]、serialize_with/deserialize_with

⚠️ 陷阱：flatten 会让 serde 走「先反序列化成 map 再填充」的路径，性能明显低于普通结构体，且不能与 deny_unknown_fields 共存。高频热路径上不要滥用。另外 serde_json::Value 是动态类型，字段名写错是运行期才发现——能用 struct 就用 struct。

clap：derive 风格 CLI

cargo add clap --features derive

use clap::{Parser, Subcommand, ValueEnum};

/// 一个演示用的文件处理工具。
#[derive(Parser, Debug)]
#[command(name = "fxtool", version, about, long_about = None)]
struct Cli {
    /// 全局开关：输出更详细的信息。
    #[arg(short, long, global = true)]
    verbose: bool,

    /// 子命令。
    #[command(subcommand)]
    command: Command,
}

/// 支持的子命令。
#[derive(Subcommand, Debug)]
enum Command {
    /// 统计行数。
    Count {
        /// 输入文件。
        file: std::path::PathBuf,
        /// 输出格式。
        #[arg(long, value_enum, default_value_t = Format::Text)]
        format: Format,
    },
    /// 抓取远端内容。
    Fetch {
        /// 目标 URL。
        url: String,
        /// 重试次数，必须落在 0..=10。
        #[arg(long, default_value_t = 3, value_parser = clap::value_parser!(u8).range(0..=10))]
        retries: u8,
    },
}

/// 输出格式。
#[derive(ValueEnum, Clone, Debug)]
enum Format {
    /// 纯文本。
    Text,
    /// JSON。
    Json,
}

fn main() {
    let cli = Cli::parse();       // 解析失败会自动打印友好错误并以退出码 2 结束
    if cli.verbose {
        eprintln!("verbose 已开启");
    }
    match cli.command {
        Command::Count { file, format } => {
            println!("统计 {:?}，格式 {:?}", file, format);
        }
        Command::Fetch { url, retries } => {
            println!("抓取 {url}，重试 {retries} 次");
        }
    }
}

关键 API：Parser::parse()（失败即退出）与 try_parse()（自己处理错误）、#[arg(short, long)]、default_value_t（用 Display）、value_parser!(T).range(..)、value_enum、global = true（全局参数可放在任意层级）、#[command(version)] 自动读 CARGO_PKG_VERSION。

🚀 进阶：需要 shell 补全时用 clap_complete；#[arg(env = "MY_VAR")] 可以让参数回退到环境变量，天然支持容器化部署。

anyhow / thiserror：错误处理（详见错误处理）

cargo add anyhow
cargo add thiserror

一句话分工：库用 thiserror 定义具体错误类型（调用方需要 match）；二进制/应用用 anyhow::Result 汇总上下文（调用方只要日志）。bail!/context/with_context 是 anyhow 的主力宏与方法，细节见〈错误处理〉。

tracing + tracing-subscriber：结构化日志

cargo add tracing
cargo add tracing-subscriber --features env-filter

use tracing::{debug, info, info_span, instrument, warn};

/// 用 #[instrument] 自动为函数创建 span，
/// 参数与返回值会被结构化记录，不需要手写字符串拼接。
#[instrument(skip(data))]
fn process(data: &[u8], batch_id: u64) -> usize {
    let len = data.len();
    debug!(len, "收到数据");            // 结构化字段：len=...
    if len == 0 {
        warn!(batch_id, "空批次");
    }
    len
}

fn main() {
    // 用 RUST_LOG 环境变量控制级别与过滤规则
    tracing_subscriber::fmt()
        .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
        .with_target(false)
        .init();

    let span = info_span!("job", id = 1);
    let _guard = span.enter();          // 同步代码里用 guard 进入 span
    info!(batch = 2, "开始处理");
    let n = process(&[1, 2, 3], 7);
    info!(n, "处理完成");
}

💡 对照：tracing 是 log 的「带上下文的继任者」。log 只有「级别 + 一条消息」，tracing 增加了 span（作用域） 与结构化字段，因此天然适配分布式追踪（OpenTelemetry）。两者关系：tracing 提供了 log 的兼容层（tracing-log feature），并且可以作为 log 的后端（把 log 宏的输出接进 tracing 管线），所以依赖里同时出现 log 和 tracing 是正常的。异步代码里 span 会随 Future 跨 .await 传播，同步代码里记得「进入 span 后立刻 drop guard」，否则会跨线程污染。

其他高频 crate 一览

crate	一句话定位	关键 API
regex	正则表达式（不支持反向引用，但保证线性时间）	Regex::new、.is_match、.captures、.replace_all；Regex::new 有编译开销，用 LazyLock 缓存
chrono	日期时间「全家桶」，API 丰富、生态最广	Utc::now()、NaiveDate、DateTime<Utc>、Duration；4.x 起默认时间区数据走 chrono-tz/iana-time-zone
time	更精简、更严格的日期时间库，no_std 友好	OffsetDateTime::now_utc()、Date、Time、Duration、format_description!
uuid	UUID 生成与解析	Uuid::new_v4()（需 v4 feature）、Uuid::parse_str、uuid::Uuid::nil()
rand	随机数（注意 0.9 与 0.10 是不同 major，API 有差异）	0.9：rand::rng()、.random()、.random_range(1..=6)、random_bool(0.5)、StdRng::seed_from_u64（可复现测试）
itertools	迭代器扩展大礼包	.chunk_by()、.tuple_windows()、.counts()、.sorted_by_key()、.join()
once_cell / std::sync::LazyLock	全局懒初始化	LazyLock::new、OnceLock::get_or_init；1.80 起优先用标准库，once_cell 只在需要 no_std 或 MSRV < 1.80 时用
rayon	数据并行：iter() 换 par_iter() 即并行	.par_iter().map(..).sum()、par_sort
tokio	异步运行时（见异步编程）	#[tokio::main]、tokio::spawn、tokio::fs
reqwest	HTTP 客户端，async + 阻塞双 API	Client::new().get(url).send().await?、.json::<T>()
axum	官方系 Web 框架，基于 tower/hyper	Router::new().route("/", get(handler))、State、extract::Json
sqlx	异步 SQL，编译期校验查询（需连库或离线缓存）	sqlx::query_as!、Pool、migrate!
indexmap	保持插入顺序的 HashMap	IndexMap、shift_remove（swap_remove 才破坏顺序）
bytes	引用计数的字节缓冲区，零拷贝切片	Bytes、BytesMut、.freeze()、.slice()
parking_lot	更快更小的锁，无 poisoning	Mutex、RwLock、Mutex::lock() 直接返回 guard（不返回 Result）
criterion	统计严谨的基准测试（见测试与性能）	criterion_group!、criterion_main!、black_box

对应安装命令：

cargo add regex
cargo add chrono --features serde          # 需要与 serde 联动时
cargo add uuid --features v4
cargo add rand@0.9                         # 显式钉住 0.9；不写版本会拿到 0.10（API 不同）
cargo add itertools
cargo add rayon
cargo add indexmap
cargo add bytes
cargo add parking_lot
cargo add --dev criterion
cargo add reqwest --features json,rustls-tls
cargo add axum tokio --features tokio/full
cargo add sqlx --features runtime-tokio-rustls,sqlite
cargo add tracing tracing-subscriber --features tracing-subscriber/env-filter

LazyLock 替代 once_cell 的写法：

use std::sync::LazyLock;

/// 正则编译昂贵，全局只编一次。
///
/// LazyLock 自 Rust 1.80 稳定；MSRV 更低时才需要 once_cell。
static ID_RE: LazyLock<regex::Regex> =
    LazyLock::new(|| regex::Regex::new(r"^[a-z]{2}-\d{4}$").expect("正则硬编码，必然合法"));

fn main() {
    assert!(ID_RE.is_match("ab-1234"));
    println!("匹配成功");
}

rand 0.9 的核心 API（相对 0.8 有一批改名，注意 gen 已是保留字）：

# 本节示例针对 0.9 系列。rand 0.10 又把采样方法挪到了 RngExt trait，
# 所以这里显式写成 "0.9"，不要用会解析到 0.10 的宽松需求。
[dependencies]
rand = "0.9"

use rand::{Rng, SeedableRng, rngs::StdRng};

fn main() {
    // 1) 线程本地 RNG：0.8 的 thread_rng() 在 0.9 中改名为 rng()
    let mut r = rand::rng();
    let dice: u32 = r.random_range(1..=6);      // 0.8 的 gen_range
    let flag: bool = r.random_bool(0.5);        // 0.8 的 gen_bool
    println!("dice={dice} flag={flag}");

    // 2) 可复现：用固定种子，测试里必备（断言随机逻辑时不要用真随机）
    let mut seeded = StdRng::seed_from_u64(42);
    let _same: f64 = seeded.random();           // 0.8 的 gen
}

⚠️ 陷阱：0.9 与 0.10 属于不同 major，Cargo 会把它们当成两个 crate 一起编进二进制（见「重复依赖与 links 冲突排查」 的重复依赖）；rand::thread_rng()、gen()、gen_range() 在 0.9 里仍存在但已标 #[deprecated]，编译会出警告。若你看到 no method named random_range found for ... Rng 这类错误，多半是拿到了 0.10（方法迁到 RngExt）——检查 cargo tree -i rand 里到底是哪个版本。

⚠️ 陷阱：Regex::new 内部会做编译，不要放在循环里。要么用 LazyLock 做全局单例，要么用 regex::RegexBuilder 预先构造。 ⚠️ 陷阱：chrono 与 time 都会在类型里带上时区语义，二者不要混用（互相转换要走 RFC 3339 字符串或 time::OffsetDateTime 的中间表示），否则会出现「同一时刻两个类型不相等」的诡异 bug。选型建议：需要丰富日历运算、时区库、被大量生态依赖 → chrono；追求精简、no_std、严格 API、避免历史包袱 → time。

完整 Cargo.toml 示例

[package]
name = "fxtool"
version = "0.3.0"
edition = "2024"
rust-version = "1.85"
description = "一个演示工程化配置的文件处理工具"
license = "MIT OR Apache-2.0"
repository = "https://github.com/example/fxtool"
keywords = ["cli", "file", "demo"]
categories = ["command-line-utilities"]

[dependencies]
anyhow = "1"
clap = { version = "4", features = ["derive", "env"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "2"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# 可选依赖：按 feature 引入，避免默认构建背负重依赖
regex = { version = "1", optional = true }
rayon = { version = "1", optional = true }

[features]
default = []
# 用 dep: 精确启用可选依赖，不产生隐式同名 feature
pattern = ["dep:regex"]
parallel = ["dep:rayon"]
full = ["pattern", "parallel"]

[dev-dependencies]
assert_cmd = "2"          # 端到端测试 CLI 的进程行为
predicates = "3"
tempfile = "3"
criterion = "0.7"

[build-dependencies]
# 需要生成代码或探测系统库时才用；否则删掉本节
# cc = "1"

[[bench]]
name = "throughput"
harness = false           # criterion 自己接管 main，必须关掉内置 harness

[lints.rust]
unsafe_op_in_unsafe_fn = "deny"
missing_docs = "warn"

[lints.clippy]
all = "warn"
pedantic = "warn"

[profile.release]
lto = "thin"              # 跨 crate 内联，编译时间涨幅可接受
codegen-units = 1         # 更少编译单元 → 更多优化机会
panic = "abort"           # 去掉 unwind 表；注意：会禁用 catch_unwind
strip = true              # 剥离符号表，二进制显著变小
opt-level = 3
debug = false

⚠️ 陷阱：panic = "abort" 与 catch_unwind、以及任何依赖「panic 后继续运行」的代码（部分 FFI 边界、tokio 的某些任务隔离）不兼容。库项目不要在自己的 [profile] 里设 panic = "abort"（profile 设置只对顶层项目生效，但会误导使用者）；这是应用侧的决策。

---

---

配置与运行时

环境变量与 dotenvy

use std::env;

/// 读取必填环境变量；缺失时给出「哪个变量缺了」的明确错误。
fn required(key: &str) -> Result<String, String> {
    env::var(key).map_err(|_| format!("缺少必需的环境变量 {key}"))
}

fn main() {
    // dotenvy::dotenv().ok();   // 开发环境：从 .env 加载；生产环境不要用
    match required("DATABASE_URL") {
        Ok(v) => println!("已配置，长度 {}", v.len()),
        Err(e) => eprintln!("{e}"),
    }

    // 带默认值的可选配置：var 失败就用默认，且只解析一次
    let port: u16 = env::var("PORT").ok().and_then(|s| s.parse().ok()).unwrap_or(8080);
    println!("监听端口 {port}");
}

cargo add dotenvy。注意 env::set_var 在 2024 edition 中已是 unsafe 函数（多线程下修改环境是数据竞争），因此应当只在 main 最开始、任何线程创建之前设置环境，或干脆避免使用。

config crate 与 12-factor

cargo add config --features toml,json,env

use serde::Deserialize;

/// 应用配置，字段名与配置文件里的键对应。
#[derive(Debug, Deserialize)]
struct AppConfig {
    /// 服务监听地址。
    host: String,
    /// 监听端口。
    port: u16,
    /// 数据库连接串。
    database_url: String,
}

fn main() -> Result<(), config::ConfigError> {
    // 分层覆盖：先 config/default.toml，再 config/production.toml，最后环境变量 APP__PORT
    let cfg = config::Config::builder()
        .add_source(config::File::with_name("config/default"))
        .add_source(config::File::with_name("config/production").required(false))
        .add_source(config::Environment::with_prefix("APP").separator("__"))
        .build()?;

    let app: AppConfig = cfg.try_deserialize()?;
    println!("{}:{}", app.host, app.port);
    Ok(())
}

12-factor 的简单讨论：12-factor App 方法论主张「配置放环境变量，不放进代码/打进构建产物」。Rust 项目里可以这样落地：

• 构建产物不分环境：同一份 release 二进制在 dev/staging/prod 都能跑，差异全部来自环境变量。这避免了「为每个环境各打一次包」的流水线分叉。
• 默认值写在代码里，必填项在启动时校验（fail fast，别等第一次请求才发现）。
• 密钥不进 git、不进镜像层：由部署平台注入。
• 反方向的声音：环境变量是扁平的，复杂嵌套配置（列表、结构化对象）表达起来别扭，.toml 更合适。务实做法是 12-factor 的「外部化」原则 + 分层的配置文件：非敏感的结构化配置用 TOML，敏感与环境相关的用环境变量覆盖——这就是上面 config crate 的分层顺序。

日志级别控制：RUST_LOG

# 全局 info 起步，某个模块开 debug
$env:RUST_LOG = "info,myapp::engine=debug"

# 只关心某个 span/目标，多目标逗号分隔
$env:RUST_LOG = "warn,fxtool=info,hyper=error"

./fxtool count .\data.txt

EnvFilter 语法支持 target=level、level，以及 #[instrument] 产生的 span 名。生产环境建议默认 info，把 debug/trace 留给排障；绝不要在热路径用 println! 当日志（无法分级、无法结构化、无法关闭）。

错误报告与退出码

use std::process::ExitCode;

/// 顶层错误：区分「用法错误」和「运行失败」，因为它们对应不同退出码。
enum TopError {
    /// 参数/配置错误 → 退出码 2（与 clap 的约定一致）
    Usage(String),
    /// 运行期失败 → 退出码 1
    Runtime(anyhow::Error),
}

fn main() -> ExitCode {
    match run() {
        Ok(()) => ExitCode::SUCCESS,
        Err(TopError::Usage(m)) => {
            eprintln!("用法错误: {m}");
            ExitCode::from(2)
        }
        Err(TopError::Runtime(e)) => {
            // {:#} 打印 anyhow 的完整错误链（原因 → 原因 → …）
            eprintln!("错误: {e:#}");
            ExitCode::FAILURE
        }
    }
}

fn run() -> Result<(), TopError> {
    let arg = std::env::args().nth(1).ok_or_else(|| TopError::Usage("缺少参数".into()))?;
    if arg == "boom" {
        return Err(TopError::Runtime(anyhow::anyhow!("模拟运行失败")));
    }
    println!("处理 {arg}");
    Ok(())
}

退出码约定与实践：

场景	退出码	说明
成功	0	ExitCode::SUCCESS
一般失败	1	ExitCode::FAILURE；main 返回 Err 时 rustc 生成的胶水代码也用 1
用法/参数错误	2	clap 的默认约定；调用方脚本可据此区分「重试无意义」
自定义	3..=125	供上层编排系统判断（如 Docker/K8s、CI）

🧠 原理：fn main() -> Result<(), E> 是合法的，E: Debug 即可。当返回 Err 时，运行时会打印 Error: {:?} 并以退出码 1 结束，同时会调用 Termination::report()。注意它打印的是 Debug 格式（anyhow 的 Debug 恰好带完整链路，所以好看；自己手写的错误类型 Debug 往往很难看）。想要完全掌控输出与退出码，就显式返回 ExitCode——这也是推荐做法。

CLI 参数校验与用户友好错误

原则：在进入业务逻辑前把非法输入全部拦掉，错误信息要给出「期望什么」，而不只是「哪里错」。

use clap::{CommandFactory, Parser};

#[derive(Parser, Debug)]
#[command(name = "porter", about = "端口转发小工具")]
struct Cli {
    /// 监听端口，1..=65535
    #[arg(long, value_parser = clap::value_parser!(u16).range(1..))]
    listen: u16,

    /// 目标地址，形如 host:port
    #[arg(long)]
    target: String,
}

/// 二次校验：clap 管不了「跨字段约束」，需要自己写。
fn validate(cli: &Cli) -> Result<(), String> {
    let (host, port) = cli
        .target
        .rsplit_once(':')
        .ok_or_else(|| format!("--target 需要 host:port 形式，收到 `{}`", cli.target))?;
    if host.is_empty() {
        return Err("--target 的主机部分不能为空，例如 127.0.0.1:8080".to_owned());
    }
    port.parse::<u16>()
        .map_err(|_| format!("--target 的端口 `{port}` 不是合法端口号（0-65535）"))?;
    if port == cli.listen.to_string() {
        return Err("--listen 与 --target 端口相同，会形成回环转发".to_owned());
    }
    Ok(())
}

fn main() {
    let cli = Cli::parse();
    if let Err(msg) = validate(&cli) {
        // 打印用法摘要 + 明确原因，比只丢一句 "invalid input" 有用得多
        let mut cmd = Cli::command();
        let _ = cmd.print_help();
        eprintln!("\n错误: {msg}");
        std::process::exit(2);
    }
    println!("{listen} -> {target}", listen = cli.listen, target = cli.target);
}

🚀 进阶：复杂 CLI 的「跨字段校验」还可以交给 clap 的 ArgGroup（至少/至多一个）与 requires/conflicts_with 声明式表达，能省掉一半手写校验。

---

---