Rust模块系统与crate发布实践:从私有项目到开源分享

The Rust Programming Language - 第14章 更多关于Cargo和Crates.io的内容 - 14.2 将crate发布到Crate.io 14 更多关于Cargo和Crates.io的内容 进一步认识Cargo和Crate.io 目前为止,我们只使用过Cargo构建、运行和测试代码这些最基本的功能,本章我们来探索更多功能 使用发布配置来自定义构建 将库发布到crate.io 使工作空间来组织根本更大的项目 从crate.io安装二进制文件 使用自定义的命令来扩展Cargo 14.2 将crate发布到Crate.io 我们曾在项目中使用crate.io上的包作为依赖,其实crate.io是一个平台,用来分发包的源代码和托管开源代码,这意味着, 阅读详情

Rust模块系统与crate发布实践:从私有项目到开源分享

cover

一、模块系统的困惑:mod、use、pub到底怎么组织

Rust的模块系统是我学Rust时最困惑的部分之一——不是概念难,而是"怎么做"不清晰。mod.rs和文件名的关系、use的路径规则、pub的可见性层级、mod声明和文件系统的对应——每个单独看都懂,组合起来就乱。

更困惑的是,什么时候该拆模块,什么时候该拆crate?模块和crate的边界在哪里?这些问题在教程里往往一笔带过,但实际写项目时天天遇到。

本文梳理Rust模块系统的核心规则,并记录我发布第一个crate的完整过程。

二、模块系统核心规则

2.1 模块声明与文件系统

graph TB
    A[src/lib.rs] --> B[mod scanner]
    A --> C[mod output]
    A --> D[mod config]
    B --> E[src/scanner.rs]
    C --> F[src/output.rs]
    D --> G[src/config.rs]
    E --> H[src/scanner/mod.rs 或 src/scanner.rs]
    B --> I[mod deep]
    I --> J[src/scanner/deep.rs]

2.2 模块声明的两种方式

// src/lib.rs

// 方式1:内联模块(小模块适合)
mod utils {
    pub fn format_size(bytes: u64) -> String {
        if bytes < 1024 {
            format!("{} B", bytes)
        } else {
            format!("{:.1} KB", bytes as f64 / 1024.0)
        }
    }
}

// 方式2:外部文件模块
mod scanner;   // 对应 src/scanner.rs 或 src/scanner/mod.rs
mod output;    // 对应 src/output.rs
mod config;    // 对应 src/config.rs

2.3 可见性规则

// 默认私有,需要pub才能被外部访问
mod internal {
    fn private_fn() {}        // 仅本模块可见
    pub fn public_fn() {}     // 本模块及父模块可见
    pub(crate) fn crate_fn() {}  // 整个crate可见
    pub(super) fn parent_fn() {} // 仅父模块可见
}

// 结构体字段也是私有的
pub struct Config {
    pub path: String,          // 公开字段
    max_depth: usize,          // 私有字段,外部不能直接访问
}

impl Config {
    pub fn new(path: String, max_depth: usize) -> Self {
        Self { path, max_depth }
    }

    pub fn max_depth(&self) -> usize {
        self.max_depth  // 通过方法暴露私有字段
    }
}

2.4 use与路径

// 绝对路径从crate根开始
use crate::scanner::FileScanner;

// 相对路径从当前模块开始
use super::config::AppConfig;  // 父模块
use self::utils::format_size;  // 当前模块

// 惯用法:函数用完整路径,类型用短路径
use std::collections::HashMap;
use std::fs::read_dir;  // 函数可以完整路径

// 重命名避免冲突
use std::io::Result as IoResult;
use anyhow::Result;

三、从模块到crate:拆分决策

3.1 何时拆成独立crate

graph TD
    A{是否被多个项目复用?} -->|是| B[拆成独立crate]
    A -->|否| C{是否需要独立版本?}
    C -->|是| B
    C -->|否| D{模块是否>500行?}
    D -->|是| E[拆成子模块]
    D -->|否| F[保持当前结构]

3.2 crate发布准备

Cargo.toml配置

[package]
name = "dust-scanner"           # crate名称,全局唯一
version = "0.1.0"               # 语义化版本
edition = "2021"
authors = ["Chen Yiming <yiming@example.com>"]
license = "MIT"                 # 必须指定license
description = "A disk usage scanner library"
repository = "https://github.com/example/dust-scanner"
keywords = ["disk", "scanner", "filesystem"]
categories = ["filesystem"]

[dependencies]
anyhow = "1.0"
serde = { version = "1.0", features = ["derive"] }

[dev-dependencies]
tempfile = "3.8"  # 测试用临时目录

文档注释

/// 扫描指定目录,返回每个子目录的大小
///
/// # Arguments
///
/// * `path` - 要扫描的根目录路径
/// * `max_depth` - 最大递归深度
///
/// # Examples
///
/// ```
/// use dust_scanner::scan_directory;
///
/// let entries = scan_directory(".", 5).unwrap();
/// for entry in &entries {
///     println!("{}: {} bytes", entry.path.display(), entry.size);
/// }
/// ```
///
/// # Errors
///
/// 当路径不存在或不是目录时返回错误
pub fn scan_directory(
    path: &str,
    max_depth: usize,
) -> Result<Vec<DirEntry>> {
    // ...
}

3.3 测试组织

// 单元测试:和代码放在一起
pub fn format_size(bytes: u64) -> String {
    match bytes {
        0..1024 => format!("{} B", bytes),
        1024..1048576 => format!("{:.1} KB", bytes as f64 / 1024.0),
        _ => format!("{:.1} MB", bytes as f64 / 1048576.0),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_format_size_bytes() {
        assert_eq!(format_size(512), "512 B");
    }

    #[test]
    fn test_format_size_kb() {
        assert_eq!(format_size(2048), "2.0 KB");
    }

    #[test]
    fn test_format_size_mb() {
        assert_eq!(format_size(3 * 1048576), "3.0 MB");
    }
}
// 集成测试:tests/目录下
// tests/integration_test.rs
use dust_scanner::scan_directory;
use tempfile::TempDir;

#[test]
fn test_scan_empty_directory() {
    let tmp = TempDir::new().unwrap();
    let entries = scan_directory(
        tmp.path().to_str().unwrap(), 5
    ).unwrap();
    assert!(entries.is_empty());
}

#[test]
fn test_scan_with_files() {
    let tmp = TempDir::new().unwrap();
    std::fs::write(tmp.path().join("test.txt"), "hello").unwrap();

    let entries = scan_directory(
        tmp.path().to_str().unwrap(), 5
    ).unwrap();
    assert!(!entries.is_empty());
}

四、发布流程

4.1 发布前检查清单

# 1. 运行所有测试
cargo test --all

# 2. 检查文档
cargo doc --open

# 3. 运行Clippy
cargo clippy -- -D warnings

# 4. 检查格式
cargo fmt --check

# 5. 干跑发布(不实际发布)
cargo publish --dry-run

# 6. 检查包大小
cargo package --list

4.2 发布命令

# 首次登录crates.io
cargo login <api-token>

# 发布
cargo publish

# 版本更新后重新发布
# 修改Cargo.toml中的version
cargo publish

4.3 版本号规则

0.1.0 → 0.1.1  修复bug,不改变API
0.1.0 → 0.2.0  新增功能,可能改变API(0.x阶段不保证兼容)
1.0.0 → 1.1.0  新增功能,向后兼容
1.1.0 → 2.0.0  破坏性变更

五、架构权衡与边界分析

5.1 模块 vs crate

模块是编译单元内的代码组织,crate是独立的编译和发布单元。模块间零开销访问,crate间有API边界。建议:项目内用模块组织,跨项目复用才拆crate。过早拆crate会增加编译时间和维护成本。

5.2 文档注释的投入

文档注释写起来费时间,但对crate的可用性至关重要。建议:公开API必须有文档注释和示例代码,私有函数不需要。cargo doc生成的文档质量取决于注释的投入。

5.3 0.x版本的承诺

0.x版本意味着"API不稳定,随时可能变"。不要害怕在0.x阶段做破坏性变更,但要在CHANGELOG中记录。1.0之后再做破坏性变更就要慎重。

六、总结

Rust模块系统的核心规则:mod声明对应文件系统,pub控制可见性,use引入路径。模块是代码组织的基本单位,crate是发布和复用的基本单位。拆分决策的关键是"是否需要跨项目复用"。

发布crate的流程:写好文档注释→运行测试→Clippy检查→dry-run验证→正式发布。版本号遵循语义化版本规范,0.x阶段允许破坏性变更。

落地建议:项目初期用模块组织代码,稳定后再考虑拆crate;公开API必须写文档注释和示例;发布前用cargo publish --dry-run验证;0.x阶段大胆迭代,1.0之后再保证兼容性。

睿尔曼超轻量仿人机械臂--医疗工作站运行Demo(Python) 开发环境系统:win10Python版本:python 3.11.2由于机械臂相关软件版本不定期更新,如果你使用的软件接口或协议与本文有出入,请联系官方技术人员及时更新。 阅读详情

相关推荐

基于Python的微信聊天记录分析——数据获取

本篇为“基于Python的微信聊天记录分析”第一篇,主要涉及数据获取,包括Python环境配置、WeChatMsg项目配置和运行、获取聊天记录等内容,流程简单、比较基础,后续这个系列会涉及基于Python的数据处理、统计分析、NLP技术等内容。希望和大家多多交流,共同进步!

Henryli1202的博客 1万+

深入理解 Rust crate 发布流程与实践

Rust 拥有一个强大而活跃的生态系统,而crates.io正是它的核心基石。作为官方包注册中心,crates.io集中了社区贡献的开源库(crate),让开发者可以轻松复用他人代码,也能将自己的成果分享给全世界。本文将深入讲解如何将一个 Rust crate 从本地项目成功发布到crates.io,不仅介绍具体操作流程,还将探讨 crate 发布背后的机制与最佳实践。

2501_94047039的博客 1430

Unity半透明物体景深失效?教你用双材质球方案完美解决(附完整Shader代码)

本文深入剖析了Unity中半透明物体导致景深效果失效的根本原因,即半透明物体默认不写入摄像机深度图。针对此问题,文章详细介绍了稳定高效的“双材质球”解决方案,通过为物体附加一个仅写入深度信息的不可见材质,完美修复景深效果,并提供了完整的Shader代码与实现脚本。

weixin_29010003的博客 384

Rust从入门到精通 如何将 crate 发布到 Crates.io,发布现有 crate 的新版本

本文介绍了如何将Rust crate发布到crates.io以及如何编写有效的文档注释。主要内容包括: 文档注释的使用方法,包括///三斜杠注释和常用文档部分(如Examples、Panics等) 文档注释可以作为测试代码运行,确保示例与代码同步 使用//!为整个crate或模块添加概述文档 通过pub use重导出功能来优化公有API结构,提高用户使用体验 这些功能能帮助开发者创建更易于使用和维护的Rust库,同时确保文档与代码保持同步。

2301_79516858的博客 1055

基于Simulink的转向控制系统仿真建模示例

本文完成了基于 Simulink 的 EPS 转向控制系统仿真,实现了:✅掌握 EPS 助力控制基本原理✅构建车速敏感的可变助力策略✅在 Simulink 中验证低速轻便、高速沉稳的手感✅达成“安全、舒适、高效”的现代转向系统。

xiaoheshang_123的博客 88

单光子雪崩二极管(SPAD):原理、极高增益机制与微光探测解析

本文系统阐述了单光子雪崩二极管(SPAD)的工作原理及其在弱光探测中的应用。SPAD通过工作在盖革模式下的碰撞离化效应实现单光子探测,其核心机理包括:1)采用p+-n-n+结构实现高电场分布;2)通过雪崩倍增过程获得10^6量级增益;3)采用主动/被动淬灭机制实现快速恢复。文章详细分析了SPAD的关键性能参数(如光子探测效率、暗计数率等)及其在量子通信、激光雷达等领域的应用优势,揭示了该器件在极微弱光信号探测中的独特价值。

Fun_LiDAR的博客 1049

rust-gpu 发布指南:在 crates.io 上发布 rust-gpu 全部六个 crate 的完整流程

rust-gpu 是一个将 Rust 变为 GPU 着色器一等公民的开源项目,由多个 crate 组成一个统一工作区。本文面向拥有 embark 的 crates.io 账号权限的 rust-gpu 维护者,完整梳理发布一个新版本时必须执行的七个步骤:从统一升级版本、同步文档、合并 PR、打 tag,到按固定依赖顺序执行 `cargo publish`。读完本文,你将掌握 rust-gpu 多 c

gitblog_00715的博客 625

OpenOCD入门到精通:第28章 综合实战:RISC-V 调试

RISC-V调试实战摘要 本文介绍了RISC-V调试规范及其在OpenOCD中的实现。主要内容包括: RISC-V Debug规范的两个版本(0.11和0.13)及其差异,OpenOCD通过自动检测DTMCS寄存器版本号选择对应驱动实现。 RISC-V调试架构的分层设计,包含DTM、Debug Module、Program Buffer等核心组件,以及三种内存访问方式(progbuf、sysbus、abstract)。 以GD32VF103为例的实战调试配置,包括硬件连接、OpenOCD配置文件编写和GDB

从事嵌入式linux android驱动开发,拥有全栈能力 285

Rust包发布流程详解:从crate创建到crates.io发布的5步安全上线法

掌握Rust包发布全流程,解决crates.io上线难题。涵盖crate创建、版本管理、依赖配置、文档编写到安全发布5大步骤,适用于开源项目与团队协作。结合Cargo工具实现高效Rust包管理,确保合规与安全,值得收藏。

LiteCode的博客 725

Unity Hololens2开发|(一)环境配置

开发过程中预览和调试应用:可以在电脑上的 Unity 编辑器中以播放模式本地运行应用,并将体验流式传输到 HoloLens2。将来自 HoloLens2 的输入(视线、手势、语音和空间映射)发送到电脑,在其中内容以虚拟沉浸式视图渲染。在HoloLens2设备中,打开Settings面板,依次选择Update & Security > For Developers,打开“Developer Mode”。在开发计算机中打开控制面板,依次选择“更新和安全> 开发者选项”,打开“开发人员模式”;

游戏开发小Y的博客 14万+

Python地理数据处理 十七:植被物候提取和分析(Savitzky-Golay)

植被是陆地生态系统中最重要的组分之一,也是对气候变化最敏感的组分,其在全球变化过程中起着重要作用,能够指示自然环境中的大气、水、土壤等成分的变化,其年际和季节性变化可以作为地球气候变化的重要指标。此外,由于生态工程保护建设和植被自然生长等因素,中国陆地生态系统发挥了重要的碳汇作用。因此,定量评估植被时空动态变化是制定生态系统可持续发展目标和衡量生态系统固碳潜力的重要前提,卫星遥感数据衍生的生态参量产品为研究长时间序列全球及区域植被时空变化提供了重要数据源。SG滤波能够对物候信息进行平滑,并提取其中的物候信息

amyniez的博客,欢迎交流讨论 4248

推荐开源项目:Google的Rust Crate审计工具

推荐开源项目:Google的Rust Crate审计工具 在Rust生态快速发展的今天,确保第三方依赖的安全性成为了开发者的头等大事。为此,Google推出了一款强大的开源工具——Google's Rust Crate Audits,致力于为开发者提供一个安心可靠的Rust依赖选择环境。 项目介绍 Google's Rust Crate Audits是一个旨在汇总和分发内部完成的Rust第三方库审...

gitblog_00434的博客 526

第154章 点云大规模并行处理(GPU加速)

优化点云处理✨ 使用。

yumeiguo的博客 374

mediasoup 的 Rust crate 体系与自动化发布流程实战指南

> 本篇指南聚焦 mediasoup 仓库中 Rust 生态的三个 crate——`mediasoup`、`mediasoup-sys`、`mediasoup-types` 的职责划分、版本管理规则,以及基于 `npm run release:rust` 的自动化发布流水线(crates.io OIDC 可信发布)。读完你将掌握:三个 crate 谁依赖谁、改动落在哪个 crate 时如何决定是否

gitblog_00635的博客 183

Devexpress16.2.6破解工具

Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具Devexpress16.2.6破解工具

LinePhone3.2.7(android端最新版本) sip客户端

SIP客户端For android:LinePhone3.2.7(最新版本),官网地址:http://www.linphone.org/

【Rust】——采用发布配置自定义构建

🎯将crate发到Crate.io 🎃编写有用的文档注解 ✨常用(文档注释)部分 ✨文档注释作为测试 ✨注释包含项的结构 🎃使用pub use 导出合适的共有API 🎃创建create.io账户 🎃向新crate添加元信息 🎃发布到Crate.io 🎃使用cargo yank 从Crate.io弃用版本

shsjssnn的博客 8951

霍尼韦尔SoftMaster使用说明

霍尼韦尔SoftMaster使用说明

Chatterbox TTS 使用指南:零样本语音克隆与 23 语言合成速查

Chatterbox 是 Resemble AI 开源的文本转语音(TTS)模型:一条命令装好,几行代码出声。零样本克隆音色、23 种语言切换、情感强度可调,生成音频还内置 Perth 水印,适合做配音、AI 助手和多语言内容的开发者。 [![Chatterbox 多语言语音合成展示](https://raw.gitcode.com/GitHub_Trending/chatterbox7/cha

gitblog_00434的博客 172

Camera2Demo

在Camera2 的基础上进行封装,使得Camera2一堆初始化逻辑与Activity分离,降低耦合度,完成预览拍照并保存的操作

Cargo 速查手册:Rust 包管理器的镜像源配置、项目构建与 crate 发布完整指南

本文是面向开发者的 Cargo 快速参考备忘清单,源自本仓库的 [Cargo 备忘清单](https://link.gitcode.com/i/f29d0614f48fb1814ba475b6dd44f46c),配套 [Rust 备忘清单](https://link.gitcode.com/i/7d4ebb825b09510b63594b9db7b22816) 使用。Cargo 是 Rust 官方

gitblog_00604的博客 503

Fluvio 发布流程完全指南:版本号提升、crate 发布与 Release CI 工作流

本文以 [dev-tools/PUBLISH.md](https://link.gitcode.com/i/418d8dcb41cb9299a1c46b3350c84a13) 为主线,系统讲解 Fluvio 开源仓库中“发布(Publish/Release)”的核心操作链路:先提升仓库顶层 `VERSION` 版本号,再执行 `make` 目标批量发布 crates,最后通过 GitHub Act

gitblog_00532的博客 212

Remory实战指南:用r-codex让AI编码Agent在长会话中保持持久记忆

你是否也被 AI 编码 Agent 的"金鱼记忆"困扰过?会话一长,上下文被反复压缩,Agent 就逐渐忘记任务目标、重复调用工具、甚至丢失关键约束。**Remory** 正是为解决这个问题而生:它为 Agent 的压缩摘要补充经过学习的**残差记忆(Residual Memory)**,让模型在长会话中跨越多次压缩依然可靠工作。本文带你实战 Remory 的 `r-codex`:本地部署推理服务

gitblog_00514的博客 366

Rust 模块、Crate 与 Workspace 组织之道:为 Python 开发者定制的代码组织指南(RustTraining python-book 第 8 章)

> **导读**:本文以 RustTraining 仓库中 [python-book/src/ch08-crates-and-modules.md](https://link.gitcode.com/i/2ba09f49ae4124018d4657ae25b79ff7) 为核心骨架,系统对比 Python 与 Rust 的代码组织方式:从 `import`/`__init__.py` 到 `mod

gitblog_00655的博客 812

从1945行到15个模块:FMHY SafeGuard无打包器模块化架构设计与源码走读

FMHY SafeGuard 是一款用于**网站安全检测**的浏览器扩展:它把当前页面与 FMHY Filterlist 过滤清单实时比对,将站点标记为 starred(精选)、safe(安全)、unsafe(危险)或 potentially unsafe(潜在危险),并通过工具栏图标、弹窗和警告页提醒你。本文以它的源码为例,完整拆解一套**无需打包器(bundler)**就能同时构建 Chrom

gitblog_00674的博客 244

边缘部署 6 大场景:Ministral-3-3B-Instruct-2512-GGUF 图片描述、实时翻译与数据提取应用清单

**Ministral-3-3B-Instruct-2512-GGUF** 是 unsloth 量化打包的 Ministral 3 家族最小型号,专为**边缘部署**设计。它把 3.4B 语言模型与 0.4B 视觉编码器装进一个约 2GB 的 GGUF 文件里,让**图片描述、实时翻译、数据提取**这三类高频任务在笔记本、树莓派级别的设备上就能流畅运行。本文为你梳理 6 大落地场景和量化版本选择清

gitblog_00876的博客 881

阅读APP书源完整导入指南:3分钟让22个书源直接可用

Yuedu 项目在 shuyuan 文件里预置了22个书源,书源导入完成后,阅读APP就能直接搜索和阅读起点中文、番茄小说等站点的小说,书源配置全程大约3分钟。 ## 🧭 书源怎么导入:扫二维码一次导完 1. 打开阅读APP,点右下角「我的」,再点页面下方的「书源管理」 2. 点右上角「⋮」菜单,选「二维码导入」 3. 扫下方二维码,它指向项目中的 shuyuan 书源文件,一次扫完即可导入

gitblog_00388的博客 820

Rust程序设计之第 8 章 crate 与模块(1)

假设你正在编写一个程序,用来模拟蕨类植物从单个细胞开始的生长过程。你的程序,也像蕨类植物一样,一开始会非常简单,所有的代码也许都在一个文件中——这只是想法的萌芽。随着成长,它将开始分化出内部结构,不同的部分会有不同的用途。然后它将分化成多个文件,可能遍布在各个目录中。随着时间的推移,它可能会成为整个软件生态系统的重要组成部分。对于任何超出几个数据结构或几百行代码的程序,进行适当的组织都是很有必要的。本章介绍了 Rust 的一些特性(crate 与模块),这些特性有助于你的程序保持井井有条。

牛牛 983

Simprint MCP 集成指南:如何让外部 AI 客户端接入你的浏览器工作区资源

Simprint 是一款开源的指纹浏览器与可编程浏览器工作区,内置本地 MCP(Model Context Protocol)服务。开启后,VS Code、Cursor、Claude Code、Codex 等外部 AI 客户端即可直接调用 Simprint 的工具接口,完成查询环境、批量启动浏览器、管理代理与标签等工作区操作。本文带你用 4 步完成接入,并梳理全部 56 个内置 MCP 工具。

gitblog_00354的博客 764

Boa 项目架构总览:Rust 编写的可嵌入 ECMAScript 引擎与 13 个核心 Crate 全解析

本文以仓库内 [core/runtime/ABOUT.md](https://link.gitcode.com/i/b3d7aa595522d82003a694d516297a13) 为骨架,系统梳理 Boa 作为一款用 Rust 编写的可嵌入 ECMAScript 引擎的项目定位、执行链路与完整 crate 架构。读完你将掌握 13 个核心 crate(`boa_ast`、`boa_engine

gitblog_00457的博客 438
上一篇: 从零到一构建系统级工具的完整过程:我的第一个Rust项目复盘
下一篇: AI Agent 记忆系统设计:从短期上下文到长期知识库的架构演进
第一程序员
博客等级 码龄1年 1万+粉丝 1822原创
评论 4
成就一亿技术人!
拼手气红包6.0元
还能输入1000个字符
 
 条评论被折叠 查看
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付:10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值