一个 Rust 项目里lib.rs往往是最先被打开、却最少被认真设计的文件。很多人从main.rs迁移过来之后顺手就把函数堆进了根模块靠pub把可见性撒得到处都是。但真正决定一个库成败的恰恰是这个文件里那几十行组织结构代码。它决定了用户需要写多长的 use 路径决定了你内部重构会不会破坏公共 API也决定了你在 docs.rs 上留给用户的第一印象是清爽还是劝退。我想结合这几年写 Rust 库的经历把lib.rs的模块组织、API 导出和最佳实践完整梳理一遍给准备做库、或者已经在做库的朋友一些能直接用的套路。1. lib.rs 的真正价值它不只是“库的 main.rs”1.1 从 crate root 说起Rust 的编译器在编译一个库时会先定位到 crate root也就是src/lib.rs。这个文件的地位很特殊它不是被某个函数调用的入口而是整棵模块树的根。所有模块声明mod、所有重导出pub use、所有可见性规则最终都要从lib.rs这个根节点开始遍历。很多人会下意识把lib.rs理解成“库版的 main.rs”这是不对的。main.rs是二进制的入口它关心的是程序怎么启动、事件循环怎么跑、信号怎么处理lib.rs关心的则是“这个库对外呈现什么、内部如何组织、哪些类型能落到用户的 use 语句里”。二进制可以没有lib.rs但一个库如果没有lib.rsCargo 甚至会直接报错。Cargo 默认会去src/lib.rs找库目标你可以在Cargo.toml里通过[lib]段覆盖这个路径[lib] name my_sdk path src/library_root.rs说实话大多数项目不需要改 path默认就是最好的。真正值得注意的是name字段库的 crate 名决定了用户写use xxx::时的第一个词。crate 名允许带连字符但 import 时必须转成下划线我在代码评审里多次见过用户困惑“为什么 Cargo.toml 里写my-sdk代码里却要use my_sdk”所以如果你要自定义库名最好从一开始就统一对外文档中的写法。1.2 库目标与二进制目标的分工一个 package 里可以同时存在src/lib.rs和src/main.rs这种情况通常出现在需要可执行示例的库项目里。此时main.rs会依赖这个库本身就像它是一个外部用户一样// src/main.rs use my_sdk::Client; fn main() { let client Client::new(https://example.com); client.ping(); }这种“库 二进制”的结构很常见也强烈推荐。它强制你从第一个版本就把lib.rs当作公共面来对待main.rs里的使用方式就是你未来用户的使用方式。如果连自己写 main 都觉得很别扭那说明 API 设计还有问题。顺带一提如果你只是写个内部工具不想暴露库 API也可以用src/bin/下多个文件管理多个二进制入口。此时lib.rs不是必需的但一旦你希望共享代码把一个 lib 目标拆出来是更干净的做法。1.3 lib.rs 的“门面”角色我把lib.rs理解为两个角色的合一第一是总装车间它把散落在各个子模块里的零件装配成一个可以对外交付的产品第二是门面docs.rs 上第一屏展示的 crate 级文档、rustdoc 里默认展开的模块树都是从这个文件开始。用户能不能三分钟看懂你库的用法往往不取决于你写了多少注释而取决于lib.rs里那些pub use和组织结构是否恰到好处。后面几节我展开讲模块怎么搭、API 怎么导、特性开关怎么响应以及怎么把lib.rs当作一份长期契约来维护。2. 模块组织实操先理清文件布局再谈 API 设计2.1 三种模块写法以及我如何选用Rust 里有三种组织模块的方式很多新手只见过其中一两种。第一种是内联模块直接在lib.rs里写mod utils { pub fn normalize(s: str) - String { s.trim().to_string() } } pub use utils::normalize;内联模块适合那些非常小、且只在当前文件内使用的东西。比如一个私有辅助函数、一个小型校验逻辑。你不需要为它们单独开文件也不希望它们出现在公共文档里。第二种是单文件模块// src/lib.rs mod parser; pub use parser::{parse, Node};// src/parser.rs pub fn parse(s: str) - Node { /* ... */ } pub struct Node { /* ... */ }编译器看到mod parser;后会在同目录下找parser.rs。这是最轻量的文件化方式适合一个模块只有一个文件的场景。第三种是目录模块通常配合mod.rs或 2018 版的并行文件约定// src/lib.rs pub mod network;目录结构可以是src/ lib.rs network/ mod.rs client.rs protocol.rs也可以是src/ lib.rs network.rs network/ client.rs protocol.rs2018 版之后两种都行mod network;会先找network.rs再找network/mod.rs。我自己的习惯是子模块数量超过 3 个、或者有明确的“协议 / 客户端 / 配置”分层时用目录 mod.rs只有一个文件就放在单文件里。并行文件约定network.rsnetwork/在工具链上完全没问题但团队协作时容易让人困惑“到底哪个是入口文件”所以如果不是个人项目我一般不主动推荐。2.2 可见性pub 不是万能的模块链路要打通Rust 的可见性规则有一个经常被忽略的点一个pub条目要真正落到外部用户手里它所在的每一层包模块路径都必须至少有一个pub或pub(crate)的声明开路。举个例子// src/lib.rs mod internal { pub struct Config { pub timeout: u64, } } pub use internal::Config;这里internal模块本身是私有的Config虽然是pub struct但外部无法通过crate::internal::Config访问。不过因为最后一句pub use internal::Config;把Config重导出来到了根作用域用户就能直接use my_lib::Config这条路径是可行的。反过来如果你没有那一行重导出用户就只能面对“模块是私有的但我拿到了一个pub字段却构造不出来”这种诡异情况吗也不是pub struct的字段可见性规则是独立的用户即便拿到类型如果构造方法没有公开也照样用不了。这个案例说明了一个核心判断对外 API 不看你哪几个pub而看从 crate root 出发的可见路径上有哪些pub。这也是为什么很多成熟库都在lib.rs里堆了一堆pub use而对内模块却保持私有。除了pub还有三个值得掌握的粒度pub(crate)整个 crate 内可见对外完全隐藏。pub(super)仅父模块可见适合模块内部职责隔离。pub(in crate::foo)限定在某条路径内可见很少用但跨模块共享内部实现时很顺手。我在实际项目里最常用的是pub(crate)。测试模块、内部 trait、公共实现的辅助函数先都标成pub(crate)等到确认某个功能确实必须对外开放再升级成pub 重导出。这样能避免很多“API 膨胀”的问题。2.3 常见的模块组织反模式我踩过且看过不少次的反模式有三个。第一个是“全pub化”。也就是把每个mod都写成pub mod恨不得让文档树把所有内部实现都摊开。结果就是用户文档里出现十来个模块、几百个类型想看Client::new都要翻半天。这不是“透明”这是没做设计。第二个是“单向不可回溯”。模块之间互相引用的时候经常要通过crate::打很长的路径。这个不算错但如果lib.rs里没有做好分层路径会越来越深跨模块重构时处处都是路径引用。最好在模块内部就用相对导入或self/super把依赖关系显式表达出来。第三个是“为了分层而分层”。一个功能明明 20 行写完非要拆成core/、models/、services/三个目录层次美其名曰“好扩展”。Rust 没有 Java 的强制包结构模块是为了封装而不是为了分类。模块树层级越深用户的理解成本越高你的导出也越需要注意。最理想的状态是模块内部怎么拆是你的自由但对外呈现尽量保持 1~2 层路径。3. API 导出用 pub use 给用户设计一个“干净入口”3.1 用户应该只看到你的门面而不是你的仓库布局假设你有一个合理的内部结构src/ lib.rs client/ mod.rs builder.rs用户在不知道内部结构的情况下理想用法是use my_sdk::Client;但如果client模块是pub的builder也是pub的那用户写出来的可能是use my_sdk::client::builder::ClientBuilder;这不一定“错”但它把内部组织暴露给了用户。一旦你哪天把builder挪到client/config下所有依赖旧路径的外部代码就都断了。而如果你只做一层lib.rs重导出内部路径怎么改对外毫无影响。我的推荐方式很简单lib.rs里的mod全部保持私有最多pub(crate)把需要公开的类型通过pub use统一暴露到根作用域或少量模块下。// src/lib.rs mod client; mod protocol; mod error; pub use client::{Client, ClientBuilder}; pub use error::SdkError; pub use protocol::Frame;这样用户始终只需要面对my_sdk::Client这种简洁路径。3.2 门面重导出把内部模块藏起来门面重导出的经典模式是// src/lib.rs mod internal { pub const DEFAULT_TIMEOUT: u64 5; pub struct Config { pub retries: u32 } pub fn connect(cfg: Config) {} } pub use internal::{Config, connect, DEFAULT_TIMEOUT};internal是私有模块用户没法通过模块名进入但pub use已经把三个条目搬到了根作用域。从用户视角看这个库只有Config、connect、DEFAULT_TIMEOUT三个 API清爽得很从你视角看后续在internal里加多少个辅助函数都不影响对外契约。这种模式还能配合as重命名解决老 API 兼容问题。比如旧版本里connect的名字写得不够好你想改成open_connection但又不希望直接删掉旧入口#[deprecated(since 0.4.0, note 请使用 open_connection)] pub use internal::connect; pub use internal::open_connection;新用户用新名字老用户依旧能通过旧名字编译只是看到弃用警告。这是语义化版本升级里非常实用的过渡手段。3.3 外部依赖的类型要不要重新导出这是很多人纠结的地方。如果你的公共函数签名里出现了依赖 crate 的类型比如pub fn parse_json(input: str) - serde_json::Value { serde_json::from_str(input).unwrap() }用户想接收这个返回值就必须在自己的Cargo.toml里也依赖serde_json否则类型都没法命名。更麻烦的是如果依赖升级了主版本你的函数签名类型实际上变了用户代码可能悄然编译失败或行为改变。两种主流处理思路第一种是把相关类型重导出出来pub use serde_json::Value; pub fn parse_json(input: str) - Value { /* ... */ }这样用户只需要use my_sdk::Value不直接感知底层依赖的存在。代价是你等于把serde_json当成了公共 API 的一部分未来升serde_json大版本时你必须考虑 API 稳定性不能悄悄换代。第二种是用自己的类型包装。比如把 JSON 值封装到SdkJson结构里内部持有一个serde_json::Value通过From转换给用户。好处是隔离彻底坏处是转换开销和开发成本。多数情况下重导出就够用。我个人的判断标准是这个类型是你 API 的核心还是边角料核心类型比如 URL、JSON 值、日期时间我会重导出边角料比如某个内部调试结构我会尽量改成私有类型或隐藏起来。另外要记住pub use重导出其他 crate 的类型时docs.rs 上会显示一个“Re-export”的跳转链接用户点过去就能看到原始文档体验上其实很自然。3.4 星号导出与 #[doc(hidden)]有人喜欢在lib.rs里写pub use internal::*;这个写法省事但风险不小星号导出会把internal里所有pub的东西都搬出来包括一些你并不想暴露的辅助结构。一旦内部新增了一个pub const DEBUG_LEVEL用户侧文档就多一个常量你根本拦不住。所以除非你确信某个模块的所有pub条目都应该是公共 API否则我强烈建议明确列出导出项。如果确实有必须存在、但不想出现在文档或自动补全里的条目可以用#[doc(hidden)]#[doc(hidden)] pub struct InternalHelper { /* ... */ }注意#[doc(hidden)]只是隐藏文档类型本身在技术上还是可访问的。它适合处理“为了兼容而保留的内部结构”或“derive 宏扩展需要但用户不该触碰的辅助类型”不适合当作安全隔离手段。4. 特性开关与 cfg 分支让 lib.rs 响应 Cargo.toml4.1 可选依赖到特性Rust 里最常见的特性用法是可选依赖。写法是[package] name my-sdk version 0.4.0 [dependencies] serde { version 1, features [derive], optional true }当把一个依赖标记为optional true时Cargo 会自动生成一个同名 featureserde。用户在Cargo.toml里启用features [serde]后这个依赖才被编译进来。此时lib.rs里就可以用cfg(feature serde)做条件编译和条件导出// src/lib.rs #[cfg(feature serde)] mod serde_support; #[cfg(feature serde)] pub use serde_support::*;这种模式非常常见一个库的核心功能不依赖可选服务但当用户开启某特性时会多出一组序列化/反序列化能力或某协议的适配实现。4.2 在 lib.rs 上书写条件导出的完整示例假设我正在写一个配置解析库核心支持 TOML想让它也支持 JSON但不想把serde_json变成硬性依赖[dependencies] serde { version 1, features [derive], optional true } serde_json { version 1, optional true }// src/lib.rs mod format { pub struct Config { pub retries: u32 } } #[cfg(feature json)] mod json_support { use crate::format::Config; pub fn from_json(s: str) - Config { serde_json::from_str(s).unwrap_or_else(|_| Config { retries: 0 }) } } // 核心 API pub use format::Config; // 可选 API #[cfg(feature json)] pub use json_support::from_json;注意即便json_support模块整体被cfg掉了它的可见性路径也不会暴露给用户用户启用json时会看到my_sdk::from_json不启用时这个函数根本不存在。这比运行期返回Err更干净编译期就知道不支持。4.3 特性组合的坑实话说特性开关是最容易出隐蔽问题的地方尤其是多个特性叠加时。第一个坑是“特性泄漏”。如果你有一个内部模块用了可选依赖但没有把它放进cfg(feature)那么即使用户没启用该特性只要开启了full之类的聚合特性模块还是会编译失败。标准解法是让每个可选依赖都有对应的 feature 门聚合特性只是字段组合[features] default [] json [dep:serde_json] full [json, yaml]第二个坑是“特性组合爆炸”。库特性越来越多用户与库作者都没法快速判断某个组合是否成立。我在新项目里会尽量让特性保持正交每个特性只做一件独立的事不互相依赖如果有依赖就通过features [xxx/yyy]显式声明。第三个坑是cfg(any(...))误用。比如你写#[cfg(feature a)]但忘了用户可能同时开启a和b而代码逻辑只在a下成立。这在运行时很容易表现为神秘行为缓慢或 panic。我的习惯是凡是特性交互会影响逻辑的地方都要写测试矩阵或至少要有一个 CI job 覆盖--all-features编译。5. 把 lib.rs 当契约文件文档、弃用与语义化版本5.1 crate 级文档写在哪里crate 级文档应该写在lib.rs顶部用//!开头的内部文档注释//! # my-sdk //! //! 一个面向物联网设备的轻量配置管理库。 //! //! 快速开始 //! //! use my_sdk::{Config, connect}; //! //! let cfg Config { retries: 3 }; //! connect(cfg); //! //! //! 当前支持的格式TOML开启 json 特性后支持 JSON。 pub use format::Config; // ...docs.rs 第一屏展示的就是这段内容。很多用户不会先看 README而是直接逛 docs.rs如果你在lib.rs里就给出最小可用示例用户几乎不会走弯路。示例代码写在这里还有一个好处rustdoc 会把它当测试来跑保证文档示例永远是可编译的。我见过不少项目把文档只写在 README 里lib.rs空空如也。这样 docs.rs 上就只有光秃秃的模块列表用户根本不知道这个库是干嘛的。强烈建议把 README 里最重要的内容提炼成一个精炼版写进lib.rs顶部。5.2 弃用策略先警告后删除公共 API 的删除是语义化版本里最敏感的部分。理想流程是三步走第一步先标记弃用但不删#[deprecated(since 0.4.0, note 请替换为 connect)] pub fn connect_legacy() { /* ... */ }第二步保留一个或多个小版本让用户有充足时间迁移。弃用警告不会停止编译但 CI 里如果开了-D warnings用户会立刻注意到。第三步在主版本升级时才真正移除。对于重导出的 API做法类似#[deprecated(since 0.4.0, note 请使用 open_connection)] pub use internal::connect;这里有个细节值得注意弃用标注会作用在重导出目标上如果内部函数本身没标deprecated你也能在重导出层标。这让“同一个内部函数、两个对外名称”的兼容期变得非常容易管理。5.3 集成测试与公共 API 的天然绑定Rust 的集成测试放在tests/目录下它会把你的 crate 当作外部依赖来编译。也就是说你在集成测试里写的use路径、能访问的类型、能看到的方法跟普通用户看到的完全一致。这是一件好事集成测试就是最佳的用户视角验证。我最常做的一件事就是在tests/里只通过pub use出来的 API 写测试尽量避免直接触摸内部模块// tests/smoke.rs use my_sdk::{Client, Config}; #[test] fn client_connects() { let cfg Config { timeout: 5, retries: 2 }; let client Client::new(cfg); assert!(client.ping()); }如果某天我在lib.rs里漏掉了某个重导出集成测试会立刻编译失败如果我在内部模块里改了字段名但重导出面没变集成测试依然通过。这等于把“对外契约”固化在了测试里非常值得维持。5.4 语义化版本对照什么时候动 lib.rs 才算合理变更内容语义化版本在 lib.rs 里的操作新增一个函数/类型minor在对应模块里新增pub并在根里补pub use修改某个函数的默认行为patch直接改实现保持签名与导出不变修改公共类型字段可见性minor 或 major若只是新增字段算兼容删除/改名字段通常破坏兼容应先标记弃用删除一个公共 APImajor先#[deprecated]留在过渡版本主版本再移除重新导出依赖类型minor在根里pub use dep::Type说明这是公共面的一部分调整内部模块结构但 API 面不变patch可以放轻松重构用户无感这张表的核心逻辑是任何能让用户use路径发生变化、让用户编写的编译代码失败或行为改变的操作都要按破坏性变更处理。而lib.rs里的重导出层越稳定你的语义化版本越容易掌控。6. 我的个人工作流从“顺手写上”到“先设计再写”讲完理论分享一套我实际使用的工作流不复杂但很管用。第一步先写“用户视角的白板”。在动手敲代码前我会在文档里列一个清单这个库要给用户提供哪几个类型、哪几个函数每个函数最核心的调用路径长什么样这个清单先不注模块结构只定义到“根模块层面有哪些pub use”。第二步把模块内部结构当成实现细节。我通常先写出每个子模块的pub(crate)版本跑通所有功能再统一在lib.rs里做重导出。期间很少直接写pub use等差不多稳定了再一次性把公共门面铺好。第三步用cargo doc检查文档树。这一步很关键cargo doc生成的文档完全按可见性呈现你能直观看到用户眼里的模块树。如果文档树超过两层且第二层是大片内部模块我就会回去收紧可见性。大部分项目里理想的 rustdoc 首页应当只有“crate 文档 根模块下几个重导出名称”。第四步用cargo test和集成测试锁住契约。我会把tests/里的文件当成“用户说明书”来写每新增一个公共 API 就补一条测试。这样每次重构都能立刻知道“我破坏了什么”。最后如果项目到了需要认真维护 API 稳定性的阶段我会考虑用cargo-semver-checks这类工具结合 CI 自动检查 API 变更。它会把当前版本和上一个版本的公共 API 差异拉出来直接判断某个变更属于 patch、minor 还是 major比自己肉眼审查可靠得多。我不建议在早期就上这套流程但一旦发布了 1.0它就能帮你守住“语义化版本承诺”。我这些年最深的体会是lib.rs不是写给自己看的是写给用户看的。你有多愿意在lib.rs上花心思决定了你的库在用户心里是“一眼就会用”还是“要翻半天源码”。每次新项目开始之前先花二十分钟把根导出清单列好这二十分钟省下的是未来无数个 issue 和解释邮件。
