ecosystem 是一个 Rust 生态系统学习与实践项目，通过丰富的示例代码展示 Rust 主流库和框架的使用方法。项目涵盖了异步编程（tokio）、Web 开发（axum）、序列化（serde）、错误处理（thiserror/anyhow）、日志追踪（tracing/OpenTelemetry）、并发测试（loom）等核心主题，是 Rust 生态系统的综合学习资源。
-
语言: Rust (Edition 2024)
-
核心依赖:
anyhow/thiserror- 错误处理serde/serde_json/serde_with- 序列化框架chrono- 时间处理tracing/tracing-subscriber/tracing-appender- 日志追踪opentelemetry/tracing-opentelemetry- 分布式追踪
-
示例依赖:
- 异步编程:
tokio,futures,tokio-util - Web 框架:
axum,http - 数据库:
sqlx(PostgreSQL) - 序列化扩展:
serde_with,strum,derive_more,derive_builder - 加密:
chacha20poly1305,base64,blake3 - 并发:
dashmap,loom - 工具:
bytes,nanoid,dotenvy,console-subscriber
- 异步编程:
src/
└── lib.rs # 库入口（空）
examples/ # 示例代码
├── tokio1.rs # tokio 运行时基础
├── tokio2.rs # 异步/同步通道通信
├── bytes.rs # bytes 缓冲区操作
├── serde.rs # serde 手动实现 Serialize/Deserialize
├── serde1.rs # serde 高级用法（加密、Base64、serde_with）
├── axum_serde.rs # axum + serde Web 服务
├── axum_tracing.rs # axum + tracing + OpenTelemetry 分布式追踪
├── enum.rs # strum 枚举工具库
├── more.rs # derive_more 派生宏
├── builder.rs # derive_builder 构建者模式
├── err.rs # thiserror/anyhow 错误处理
├── shortener.rs # URL 短链接服务（完整 Web 应用）
├── minginx.rs # 简易反向代理
└── chat.rs # 多人聊天服务器
tests/
└── loom.rs # loom 并发测试
logs/ # 日志输出目录
test.rest # HTTP 测试文件
演示 current_thread 运行时的创建和任务调度：
cargo run --example tokio1核心要点：
- 使用
Builder::new_current_thread()创建单线程运行时 rt.spawn()提交异步任务- 异步 I/O（文件读取）与 CPU 密集型任务的并行执行
演示 tokio 异步任务与同步线程之间的消息传递：
cargo run --example tokio2核心要点：
mpsc::channel创建异步通道- 异步端使用
tx.send().await发送消息 - 同步端使用
rx.blocking_recv()接收消息 - 适用于异步生产者 + 同步消费者的场景
手动实现 Serialize 和 Deserialize trait，深入理解 serde 工作原理：
cargo run --example serde核心要点：
Serialize: 使用serialize_struct逐字段序列化Deserialize: 实现Visitortrait，支持visit_seq和visit_mapvisit_seq中字段顺序必须与声明一致
展示 serde 的高级功能，包括自定义序列化、加密、Base64 编码等：
cargo run --example serde1核心要点：
#[serde(rename_all = "camelCase")]- 字段重命名#[serde(rename = "privateAge")]- 单个字段重命名#[serde(skip_serializing_if = "Vec::is_empty")]- 条件跳过#[serde(tag = "type", content = "details")]- 枚举内部标记- 自定义
serialize_with/deserialize_with- Base64 编解码 serde_with的DisplayFromStr- 自动通过Display/FromStr转换- ChaCha20Poly1305 加密序列化
使用 axum 构建支持 JSON 序列化的 REST API：
cargo run --example axum_serde核心要点：
Router路由定义State共享状态管理Json请求/响应处理#[instrument]自动追踪patch部分更新模式
集成 OpenTelemetry 实现分布式追踪和多层日志：
# 先启动 Jaeger（分布式追踪后端）
docker run -d -p16686:16686 -p4317:4317 -e COLLECTOR_OTLP_ENABLED=true jaegertracing/all-in-one:latest
cargo run --example axum_tracing核心要点：
- 控制台日志（
tracing-subscriber） - 文件滚动日志（
tracing-appender） - OpenTelemetry 导出（
tracing-opentelemetry） #[instrument]自动创建 span- Jaeger UI 查看追踪（http://localhost:16686）
完整的 URL 短链接 Web 应用，使用 PostgreSQL 存储：
# 设置数据库连接
export DATABASE_URL="postgres://user:pass@localhost:5432/shortener"
cargo run --example shortenerAPI 使用：
# 创建短链接
curl -X POST http://localhost:8080/ \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com"}'
# 访问短链接（自动重定向）
curl -v http://localhost:8080/<id>核心要点：
sqlx异步 PostgreSQL 操作nanoid生成短 IDdotenvy环境变量管理FromRow数据库行映射ON CONFLICT处理 URL 去重- axum 提取器顺序（
FromRequestParts在前，FromRequest在后）
实现基本的 TCP 反向代理：
cargo run --example minginx核心要点：
- TCP 连接的双向数据转发
tokio::io::copy零拷贝数据传输tokio::try_join!并发执行双向转发Arc共享配置
基于 TCP 的多人聊天室：
# 启动服务器
cargo run --example chat
# 使用 telnet 连接
telnet localhost 8080核心要点：
DashMap并发安全的连接管理Framed+LinesCodec行协议编解码mpsc通道实现消息广播- 连接生命周期管理（加入/离开通知）
使用 strum 库增强枚举功能：
cargo run --example enum核心要点：
EnumString- 字符串转枚举EnumIter- 遍历所有变体EnumCount- 变体计数EnumIs- 类型判断（is_b()）IntoStaticStr- 转为静态字符串VariantNames- 获取变体名称列表Display- 自定义显示格式#[strum(serialize = ..., to_string = ...)]- 自定义序列化和显示
使用 derive_more 自动生成常用 trait 实现：
cargo run --example more核心要点：
From- 自动类型转换Add- 加法运算Into- 反向转换Display- 格式化显示#[display("int: {_0}")]- 自定义 Display 格式
使用 derive_builder 实现构建者模式：
cargo run --example builder核心要点：
#[builder(setter(into))]- 自动类型转换#[builder(setter(skip))]- 跳过字段#[builder(default)]- 默认值#[builder(setter(custom))]- 自定义 setter#[builder(setter(each(name = "skill", into)))]- 集合逐项添加- 自定义
build()方法（计算派生字段）
演示 Rust 错误处理的最佳实践：
cargo run --example err核心要点：
thiserror定义错误枚举#[from]自动实现Fromtrait#[error("...")]自定义错误消息Box<BigError>大错误放堆上，减小错误大小anyhow::Context添加上下文信息- 各错误类型的大小比较
演示 bytes crate 的缓冲区操作：
cargo run --example bytes核心要点：
BytesMut可变缓冲区BufMuttrait 写入数据split()/freeze()/split_to()切片操作
使用 loom 进行并发正确性测试：
cargo test --test loom核心要点：
loom::model模拟并发执行- 检测原子操作的正确性
fetch_addvsload + store的竞态条件
cargo build # 调试构建
cargo build --release # 发布构建# 运行指定示例
cargo run --example <name>
# 例如
cargo run --example tokio1
cargo run --example serde1
cargo run --example axum_serdecargo test # 运行测试
cargo nextest run # 使用 nextest 运行测试- 使用
cargo fmt格式化代码 - 使用
cargo clippy进行代码检查，所有警告视为错误 (-D warnings)
项目配置了以下 pre-commit 检查：
- 通用检查: 文件编码、大小写冲突、合并冲突、YAML 格式、行尾空格
- Python 格式:
black代码格式化 - Rust 检查:
cargo fmt -- --check- 代码格式检查cargo deny check -d- 依赖安全检查typos- 拼写检查cargo check --all- 编译检查cargo clippy --all-targets --all-features --tests --benches -- -D warnings- 代码质量检查cargo nextest run --all-features --no-tests pass- 单元测试
项目使用 Conventional Commits 规范：
feat:- 新功能fix:- Bug 修复doc:- 文档更新perf:- 性能优化refactor:- 代码重构style:- 代码风格test:- 测试相关chore:- 其他杂项
使用 git-cliff 自动生成 CHANGELOG。
使用 cargo-deny 进行依赖检查，配置文件 deny.toml：
- 安全漏洞:
deny - 维护状态:
warn - 许可证白名单: MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception, MPL-2.0, BSD-2-Clause, BSD-3-Clause, ISC, CC0-1.0, Unicode-3.0