Rust 公共接口设计

1. 适用方式

当改动改变调用方可见类型、方法、错误、功能开关、软件包布局、重新导出、依赖来源或跨层能力边界时使用本技能。先完整阅读 类型与接口，再在涉及软件包、模块、条件编译、依赖或宏时完整阅读 模块与依赖。

公共不只指 pub。工作区内多个软件包依赖的私有约定、驱动和操作系统之间的适配契约、配置文件格式及测试运行器输入同样属于共享接口。

2. 设计顺序

先确定调用方、所有者、有效状态、失败语义和兼容边界，再选择类型和方法。现有项目边界能够表达所需语义时优先扩展，不并行创建第二套登记表、错误体系或配置来源。

新增或扩展能力时同时使用 feature-development。同一契约需要跨多个目标架构归纳共同性、保留特异性或集中条件编译选择时使用 multi-arch-layering。锁、原子操作、异步执行或共享生命周期使用 rust-concurrency-safety；接口要求调用方维护内存安全前置条件时使用 rust-unsafe-safety；驱动与操作系统适配边界继续使用 cross-kernel-driver。

3. 验收条件

接口改动应让调用方无需穿透内部对象或猜测状态即可完成领域操作。成功、暂不可用、不支持和失败能够被类型区分；资源与能力的所有权、生命周期和线程安全保证可从类型与文档判断；功能开关组合、重新导出和发布依赖在项目任务工具覆盖的配置中一致。