组件开发及管理规范 #371

ZCShou · 2026-03-02T09:10:54Z

ZCShou
Mar 2, 2026
Maintainer

组件开发及管理规范

一、概述

1.1 背景与目的

安全操作系统内核采用组件化架构设计，组件是功能相对独立且可独立测试的实体。目前，各个组件实际上是分散在了独立代码仓库的一个或多个 crate。为了规范组件的开发、管理和发布流程，特制定本规范。

将核心组件发布到 crates.io 的主要目的：

提升开发维护效率：使用版本号而非 Git 仓库地址 + 分支引用依赖项，避免仓库更新导致编译失败，提高依赖项的稳定性和可复现性
促进项目推广：crates.io 是 Rust 生态最主要的代码发布平台，发布后能更方便地让社区用户发现和使用组件
提升代码质量：公开发布需要达到较高的工程质量标准，促使对接口、文档、测试、架构等方面进行系统性审查
增强组件复用性与独立性：保持模块间的低耦合设计，有利于长期演进

1.2 适用范围

本规范适用于所有核心组件的开发、管理和发布流程。

二、组件开发规范

2.1 代码注释规范

所有公开发布的组件必须提供由 rustdoc 生成的 API 文档。文档注释不仅是为了代码可读性，更是为了让用户能够通过 cargo doc 生成完整的 API 参考文档。所有公开发布的 crate 应具备合理的文档注释：

crate 级别文档：必须在 src/lib.rs 顶部添加 crate 级别的文档注释，说明 crate 的用途、主要功能和基本使用方法
公开模块文档：所有公开模块都应有模块级文档注释
公开 API 文档分级：
- 核心公共 API（对外主要接口）：必须具备完整的文档注释，包括用途说明、使用示例、参数说明、返回值说明、错误处理、注意事项
- 辅助 API：建议至少包含用途说明和基本使用方式
- 内部实现（使用 #[doc(hidden)] 标记）：可放宽文档要求

文档验证：CI 中应包含文档检查命令，建议采用分阶段策略：

# 第一阶段：只检查文档链接完整性
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc

# 第二阶段（成熟后）：添加缺失文档警告
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links -W missing-docs" cargo doc

# 可选：对特定目录强制要求完整文档
RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links -D missing_docs" cargo doc --lib

文档示例：文档中的示例代码应可运行，作为 doctest 的一部分：

/// ```
/// let result = crate::function();
/// assert!(result.is_ok());
/// ```

2.2 测试规范

所有组件必须通过测试才能发布。针对系统软件的特殊性，测试分为三个层次：

2.2.1 单元测试

单元测试针对组件内部的 API 进行测试，验证各个函数和方法的正确性。

适用范围：

纯逻辑代码（算法、数据结构、状态机等）
公共 API 的边界条件测试
错误处理路径测试

基本要求：

纯逻辑代码：建议完整的单元测试覆盖（目标覆盖率 ≥ 80%）
硬件抽象层：建议进行接口级别的测试，可使用 mock 对象
无法测试的代码：应使用 #[cfg(not(test))] 或注释说明原因

编写方式：

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

    #[test]
    fn test_basic_functionality() {
        // 测试核心逻辑
        let result = function();
        assert!(result.is_ok());
    }

    #[test]
    fn test_edge_cases() {
        // 测试边界条件
        assert_eq!(calculate(0), 0);
        assert_eq!(calculate(100), 100);
    }
}

2.2.2 功能测试

功能测试通过模拟环境测试组件的功能，验证组件在接近真实场景下的行为。

适用范围：

需要特定环境配置的功能
与外部系统交互的代码
复杂的业务逻辑流程

基本要求：

建议使用 mock 或 stub 模拟外部依赖
应测试正常流程和异常流程
应验证组件的输入输出行为

编写方式：

#[cfg(test)]
mod functional_tests {
    use super::*;
    use mock_object::MockHardware;

    #[test]
    #[cfg(feature = "integration-test")]
    fn test_with_mock_environment() {
        // 创建模拟环境
        let mock_hw = MockHardware::new();
        
        // 测试组件功能
        let result = component_function(&mock_hw);
        assert!(result.is_ok());
    }

    #[test]
    fn test_error_handling() {
        // 测试错误场景
        let result = failing_function();
        assert!(matches!(result, Err(_)));
    }
}

2.2.3 系统测试

系统测试将组件集成到操作系统中进行测试，验证组件在真实环境下的完整功能。

适用范围：

硬件相关代码（驱动、中断处理等）
需要真实硬件环境的功能
跨组件的集成测试

基本要求：

建议在 tests/ 目录下编写集成测试
应在真实或模拟的操作系统环境中运行
应测试组件与系统其他部分的交互

编写方式：

// tests/integration_test.rs

#[test]
#[cfg(target_arch = "x86_64")]
fn test_x86_hardware_integration() {
    // x86 特定的硬件集成测试
}

#[test]
#[cfg(feature = "system-test")]
fn test_system_integration() {
    // 系统级集成测试
    // 验证组件在操作系统中的行为
}

2.2.4 文档测试

文档注释中的示例代码应作为 doctest 运行，确保文档示例的正确性：

/// ```
/// let result = function();
/// assert!(result.is_ok());
/// ```
pub fn function() -> Result<()> {
    // ...
}

2.2.5 测试运行要求

跨平台测试要求：
- 组件应根据其支持的平台进行相应的测试
- 必须测试：组件声明的所有支持平台
- 测试分层：
  - 单元测试和文档测试：应在所有支持平台上运行
  - 功能测试：可在模拟环境中运行，与平台无关
  - 系统测试：应在真实或模拟的操作系统环境中运行

覆盖率检查（可选）：

cargo install cargo-tarpaulin
cargo tarpaulin --out Html

测试命令：

# 运行所有测试
cargo test --all-features

# 仅运行单元测试
cargo test --lib

# 运行文档测试
cargo test --doc

# 运行集成测试
cargo test --test integration_test

# 交叉编译测试（指定目标平台）
cargo test --target riscv64gc-unknown-none-elf

2.3 代码结构规范

模块划分：crate 内部应有合理的模块划分，建议避免过深或过浅的模块层级
API 设计：应清晰划分公共 API 与内部实现，避免无意中暴露内部接口
模块组织：相关功能应组织在同一模块内，保持高内聚低耦合

2.4 命名规范

遵循 Rust 命名规范：
- 模块必须使用 snake_case
- 类型必须使用 CamelCase（结构体、枚举、类型别名）
- 函数和方法必须使用 snake_case
- 常量必须使用 SCREAMING_SNAKE_CASE
语义清晰：名称应准确表达其用途，避免歧义、模糊和通用的缩写
用户视角：公共接口的命名应以使用者角度考虑，做到易用、可理解、易检索

2.5 Cargo.toml 规范

每个 crate 的 Cargo.toml 必须包含完整信息：

[package]
name = "crate-name"
version = "0.1.0"  # 遵循 SemVer 规范
edition = "2021"
authors = ["ArceOS Team <xxx>"]
description = "Brief description of the crate"
documentation = "https://docs.rs/crate-name"
repository = "https://github.com/arceos-org/crate-name"
readme = "README.md"
license = "GPL-3.0-or-later OR Apache-2.0 OR MIT"
keywords = ["keyword1", "keyword2"]
categories = ["category1", "category2"]

[dependencies]
# 依赖项列表

[dev-dependencies]
# 开发依赖项列表

2.6 提交信息规范

使用约定式提交（Conventional Commits）格式：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型（type）：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式（不影响代码运行的变动）
refactor: 重构（既不是新增功能，也不是修复 bug）
perf: 性能优化
test: 增加测试
chore: 构建过程或辅助工具的变动
release: 发布版本

示例：

feat(runtime): add support for dynamic loading

This commit adds support for dynamically loading modules at runtime,
which enables more flexible system configuration.

Closes #123

三、组件仓库分支管理

3.1 分支规划

为不同版本规划清晰的分支结构，严格限制分支数量。

3.1.1 固定分支

每个组件仓库必须且只能维护以下永久分支：

main 分支：维护稳定版本（如 v0.1.x 系列）
- 只接受经过充分测试的代码
- 对应正式发布版本
- 保持向后兼容性
- 用于补丁修复和版本发布
- 必须启用分支保护（PR review + CI 检查通过）
  - PR review（至少 1 人批准）
  - CI 检查全部通过
  - 合并前必须通过状态检查
dev 分支：维护下一个大版本的开发版（如 v0.2.0-pre.x）
- 用于新功能开发和实验性特性
- 可能包含破坏性变更
- 使用预发布版本号
- 功能稳定后合并到 main 分支发布
- 开发分支默认没有分支保护，任何开发人员可以发布预览版

3.1.2 临时分支

原则上不允许在组件仓库中建立其他分支。如确需建立临时分支，必须遵守以下规则：

命名规范：
- feature/xxx - 新功能开发
- fix/xxx - Bug 修复
- hotfix/xxx - 紧急修复
- refactor/xxx - 代码重构
使用原则：
- 原则上应直接在 dev 分支进行新功能开发
- 临时分支仅用于复杂功能或多人协作场景
- 合并到目标分支后必须立即删除
- 超过 30 天未活动的临时分支将被自动删除
清理机制：
- 建议定期检查并清理长期未活动的分支
- 建议使用 GitHub 的分支保护规则自动删除已合并的分支

3.1.3 工作流程

功能开发流程：
- 在 dev 分支进行新功能开发
- 功能完成后进行测试和代码审查
- 功能稳定、通过 CI 检查后合并到 main 分支
版本发布流程：
- 当 dev 分支的功能稳定后，合并到 main 分支
- 在 main 分支创建 Git Tag 发布正式版本
- 详见 3.2 版本发布与管理
补丁修复流程：
- 在 main 分支进行 bug 修复
- 通过测试后创建 Git Tag 发布补丁版本
- 详见 3.2 版本发布与管理

3.2 版本发布与管理

所有版本发布必须通过 Git Tag 方式进行，这是组件版本管理的唯一正式方式。

3.2.1 版本号规范

发布版本号必须遵循 Semantic Versioning 2.0.0 规范：

主版本号（MAJOR）：不兼容的 API 变更
次版本号（MINOR）：向后兼容的功能新增
修订号（PATCH）：向后兼容的 bug 修复

3.2.2 Git Tag 发布规范

Tag 命名规范：所有版本 tag 必须以 v 开头，格式为 vX.Y.Z 或 vX.Y.Z-pre.X
- 稳定版：v0.1.2、v0.2.0
- 预发布版：v0.2.0-pre.1、v0.2.0-preview.1
Tag 与版本号一致性：Git tag 必须与 Cargo.toml 中的版本号完全一致
- 例如：tag 为 v0.1.2，则 Cargo.toml 中 version 必须为 0.1.2
Tag 创建时机：只有在准备发布到 crates.io 时才创建 tag
- tag 创建后应立即推送到远程仓库
Tag 不可修改：已发布的 tag 严禁修改或删除
- 如发布错误，应使用 cargo yank 撤销 crates.io 上的版本
- 如需重新发布，必须创建新的 tag 和版本号
Tag 与分支对应关系：
- 稳定版（v0.1.2、v0.2.0）：必须在 main 或 master 分支创建
- 预发布版（v0.2.0-pre.1）：必须在 dev 分支创建

四、组件依赖管理

4.1 版本号规范

4.1.1 版本声明原则

必须使用 crates.io 版本号：所有已发布的组件依赖必须使用 crates.io 上的版本号，禁止使用 Git 仓库地址、path 依赖或私有 registry
遵循 SemVer 规范：版本号必须符合 Semantic Versioning 2.0.0 规范，详见 3.2.1 版本号规范

版本范围指定：

[dependencies]
# 推荐使用 caret 要求（默认）
some-crate = "1.2"      # 兼容 >=1.2.0 且 <2.0.0
some-crate = "1.2.3"    # 兼容 >=1.2.3 且 <1.3.0

# 精确版本（不推荐，除非有特殊原因）
some-crate = "=1.2.3"   # 仅使用 1.2.3

# 比较运算符（谨慎使用）
some-crate = ">=1.2, <1.5"
some-crate = "~1.2.3"   # 兼容 >=1.2.3 且 <1.3.0

# 通配符（不推荐）
some-crate = "1.*"      # 兼容 >=1.0.0 且 <2.0.0

版本号锁定策略：
- 生产环境：建议使用 Cargo.lock 锁定确切版本，确保可复现构建
- 库开发：建议使用 caret 要求（"1.2"），允许补丁更新
- 关键依赖：建议使用精确版本或严格范围（"=1.2.3" 或 ">=1.2.3, <1.2.4"）

4.1.2 依赖版本管理

版本更新检查：

# 检查可更新的依赖
cargo outdated

# 查看依赖树
cargo tree

# 检查版本冲突
cargo tree -d

依赖更新策略：
- 补丁更新（安全）：cargo update - 更新到兼容的最新版本
- 小版本更新（需测试）：手动修改 Cargo.toml 中的版本号
- 大版本更新（需审查）：应评估破坏性变更后更新

版本兼容性验证：

# 更新依赖后运行完整测试
cargo update
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings

依赖审计与健康检查：

# 检查未使用的依赖
cargo +nightly udeps

# 检查依赖的安全漏洞
cargo audit

# 查看依赖大小
cargo diet

# 查看完整依赖树（检查深度）
cargo tree --depth 5

# 统计依赖数量
cargo tree | grep "└──" | wc -l

注意：建议定期（每月）运行依赖审计命令，确保依赖项的健康和安全。

4.2 依赖声明顺序规范

为避免依赖声明杂乱无章，所有 Cargo.toml 应遵循统一的声明顺序：

4.2.1 依赖分组规则

# 1. 核心依赖（必需的运行时依赖）
[dependencies]
# 建议按字母顺序排列

# 2. 特定平台依赖
[target.'cfg(target_arch = "x86_64")'.dependencies]
# x86_64 特定依赖

[target.'cfg(target_arch = "riscv64")'.dependencies]
# RISC-V 特定依赖

# 3. 特定 feature 依赖
[features]
default = []

[features.feature-name]
# feature 相关依赖

# 4. 开发依赖（仅用于测试、文档生成、基准测试等）
[dev-dependencies]
# 建议按字母顺序排列

# 5. 构建依赖（用于 build.rs）
[build-dependencies]
# 建议按字母顺序排列

4.2.2 依赖声明模板

[dependencies]
# === 核心组件 ===
axstd = "0.1"
axhal = "0.1"
axruntime = "0.1"

# === 第三方库 ===
log = "0.4"
spin = "0.9"
lazy_static = "1.4"

# === 平台特定依赖 ===
[target.'cfg(target_arch = "x86_64")'.dependencies]
x86_64 = "0.14"
x2apic = "0.4"

[target.'cfg(target_arch = "riscv64")'.dependencies]
riscv = "0.10"
sbi-rt = "0.0.2"

# === Feature 依赖 ===
[features]
default = ["std"]
std = []
network = ["smoltcp = "0.10""]

[dev-dependencies]
# 测试框架
criterion = "0.5"

# Mock 工具
mockall = "0.11"

[build-dependencies]
# 构建脚本依赖
cc = "1.0"

4.2.3 依赖注释规范

建议为每个依赖添加简短注释说明用途：

[dependencies]
# 核心组件
axstd = "0.1"           # 标准库替代
axhal = "0.1"           # 硬件抽象层
axruntime = "0.1"       # 运行时支持

# 同步原语
spin = "0.9"            # 自旋锁
lock_api = "0.11"       # 锁接口抽象

# 内存管理
buddy_system_allocator = "0.9"  # 物理内存分配器
slab_allocator = "0.1"          # 对象分配器

4.3 依赖层级控制

4.3.1 最大依赖深度

为避免过深的依赖层级导致维护困难，规定：

依赖深度限制：
- 直接依赖：组件直接使用的依赖（无限制）
- 间接依赖：依赖的依赖（建议不超过 3 层）
- 传递依赖：超过 3 层的间接依赖应考虑重构
依赖深度检查：建议使用 cargo tree --depth 5 查看依赖树，详见 4.1.2 依赖版本管理
过深依赖的处理：
- 合并依赖：建议将多个小功能依赖合并为一个功能更完整的依赖
- 移除中间层：建议直接使用底层依赖，减少中间包装
- 重新设计：应重新审视架构，简化依赖关系

4.3.2 循环依赖检测与避免

循环依赖的危害：
- 导致编译失败
- 增加维护复杂度
- 违反模块化设计原则

检测方法：

# 使用 cargo tree 检测循环依赖
cargo tree

# 如果出现类似输出，说明存在循环依赖：
# error: cyclic package dependency: crate-a -> crate-b -> crate-a

避免循环依赖的设计原则：
- 单向依赖：依赖关系应形成有向无环图（DAG）
- 抽取公共层：将循环依赖的共同部分抽取为独立的底层组件
- 依赖倒置：使用 trait 抽象，通过依赖注入打破循环

循环依赖解决方案示例：

问题：A 依赖 B，B 依赖 A

解决方案 1：抽取公共接口 C
A -> C <- B

解决方案 2：合并为一个组件
AB (合并后的组件)

解决方案 3：使用 trait 抽象
A 定义 trait，B 实现 trait，A 依赖 trait 而非 B

4.3.3 依赖数量控制

依赖数量建议：
- 核心组件：建议直接依赖 ≤ 20 个
- 工具库：建议直接依赖 ≤ 10 个
- 应用层：可适当放宽，但应保持合理
依赖审计：建议使用 cargo audit、cargo +nightly udeps、cargo diet 等工具，详见 4.1.2 依赖版本管理
减少依赖的策略：
- 功能内聚：建议将相关功能合并到同一组件
- 可选依赖：建议使用 feature 标记非核心功能
- 条件编译：建议使用 cfg 属性减少平台无关代码的依赖

4.4 特定架构依赖管理

4.4.1 平台特定依赖

对于只能在特定平台编译的依赖，使用条件编译：

[dependencies]
# 通用依赖
log = "0.4"

# x86_64 特定依赖
[target.'cfg(target_arch = "x86_64")'.dependencies]
x86_64 = "0.14"
x2apic = "0.4"
uart_16550 = "0.2"

# RISC-V 特定依赖
[target.'cfg(target_arch = "riscv64")'.dependencies]
riscv = "0.10"
sbi-rt = "0.0.2"

# ARM 特定依赖
[target.'cfg(target_arch = "aarch64")'.dependencies]
aarch64 = "0.0.2"
armv8-a = "0.1"

# 操作系统特定依赖
[target.'cfg(target_os = "none")'.dependencies]
# 裸机环境依赖

[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
libc = "0.2"

4.4.2 条件依赖

使用 feature 标记控制可选依赖：

[dependencies]
# 核心依赖（必需）
log = { version = "0.4", optional = true }
spin = "0.9"

# 可选依赖
serde = { version = "1.0", optional = true }
smoltcp = { version = "0.10", optional = true }

[features]
default = ["log"]

# 启用序列化支持
serialize = ["serde"]

# 启用网络功能
network = ["smoltcp"]

# 完整功能
full = ["log", "serialize", "network"]

4.4.3 裸机目标依赖

对于裸机目标（如 riscv64gc-unknown-none-elf），需要特殊配置：

[package.metadata.docs.rs]
default-target = "riscv64gc-unknown-none-elf"
targets = ["riscv64gc-unknown-none-elf", "x86_64-unknown-none"]

[dependencies]
# 裸机环境不依赖标准库
# 核心依赖
spin = "0.9"
buddy_system_allocator = "0.9"

# 平台特定依赖
[target.'cfg(target_arch = "riscv64")'.dependencies]
riscv = "0.10"
sbi-rt = "0.0.2"

# 开发时可以启用标准库（用于测试）
[dev-dependencies]
# 仅在测试时使用标准库

4.4.4 docs.rs 构建配置

确保文档能在 docs.rs 正确构建：

[package.metadata.docs.rs]
all-features = true
# 指定默认目标
default-target = "x86_64-unknown-linux-gnu"
# 指定需要构建的目标列表
targets = ["x86_64-unknown-linux-gnu", "riscv64gc-unknown-none-elf"]

# 定义文档构建时的环境变量
[package.metadata.docs.rs.env]
# 设置特定的环境变量

发布前本地验证：

# 验证文档构建
RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps --all-features

# 验证特定目标
cargo doc --no-deps --target riscv64gc-unknown-none-elf

五、组件发布流程

组件发布流程仅针对特殊情况下需要手动发布组件，否则请参考六、CI/CD 规范中的要求，统一通过 CI/CD 来进行发布版本！

5.1 发布前检查清单

在发布 crate 到 crates.io 之前，必须完成以下检查：

所有公开 API 都有完整的文档注释
文档测试通过（cargo test --doc）
集成测试通过
CI 检查全部通过（构建、测试、clippy、文档）
Cargo.toml 信息完整
版本号已更新且符合 SemVer
README.md 清晰完整

5.2 发布流程

发布流程按分支类型分为三种场景：

5.2.1 发布稳定版

适用场景：功能稳定、向后兼容的正式版本

发布分支：main/master 分支

发布流程：

切换到 main 分支并更新到最新代码
修改 Cargo.toml 版本号（PATCH 版本如 0.1.2 或 MINOR 版本如 0.2.0）
提交版本修改（使用约定式提交格式：release: v0.1.2）
按照 3.2.2 Git Tag 发布规范创建并推送 tag
如果使用手动发布：
1. 运行 cargo publish --dry-run 检查
2. 运行 cargo publish 正式发布
如果在 CI 中配置了发布工作流：
1. 确认CI工作正常

5.2.2 发布预览版

适用场景：新功能开发、可能包含破坏性变更的版本

发布分支：dev 分支

发布流程：

切换到 dev 分支并更新到最新代码
修改 Cargo.toml 版本号为预发布格式（如 0.2.0-pre.1）
提交版本修改（使用约定式提交格式：release: v0.2.0-pre.1）
按照 3.2.2 Git Tag 发布规范创建并推送 tag
如果使用手动发布：
1. 运行 cargo publish --dry-run 检查
2. 运行 cargo publish 正式发布
如果在 CI 中配置了发布工作流：
1. 确认 CI 工作正常

5.3 版本回撤

如果发布了错误版本，可以使用 cargo yank 撤销：

# 撤销特定版本（防止新用户下载）
cargo yank crate-name@0.1.2

# 恢复被撤销的版本
cargo yank --undo crate-name@0.1.2

注意：已发布的版本不能删除，只能 yank。yank 的版本仍然可以被已有项目使用，但不会出现在新项目的依赖解析中。

六、CI/CD 规范

为了简化开发人员的工作，我们通过统一的 CI/CD 来自动执行本规范中的各项检查，因此，每个组件仓库必须配置 CI/CD。

我们为 CI/CD 以及本地测试，创建了 https://github.com/arceos-hypervisor/axci 独立仓库，其他组件只需要直接通过 use 使用改仓库的 CI/CD 文件即可！

6.1 工作流规范

所有组件仓库必须配置以下四个工作流文件。

┌─────────────┐
│   check.yml │ ─┐
└─────────────┘  │
                 ├──> ┌──────────────┐
┌─────────────┐  │    │  deploy.yml  │
│   test.yml  │ ─┘    │  (文档部署)   │
└─────────────┘       └──────────────┘
                 │
                 ├──> ┌──────────────┐
                 │    │  release.yml │
                 └─── │  (自动发布)   │
                      └──────────────┘

依赖规则：

deploy.yml 和 release.yml 必须等待 check.yml 和 test.yml 全部通过
check.yml 和 test.yml 可以并行执行
deploy.yml 和 release.yml 可以并行执行（在依赖满足后）

6.2 代码质量检查

文件位置：.github/workflows/check.yml

用途：检查代码格式、文档完整性、代码质量等静态检查

触发条件：

push 到 main、dev 分支
pull_request 到 main、dev 分支

必须包含的检查项：

检查项	命令	说明
格式化检查	`cargo fmt --all -- --check`	确保代码格式统一
Clippy 检查	`cargo clippy --all-targets --all-features -- -D warnings`	检查代码质量问题
构建检查	`cargo build --all-features`	确保代码能正常编译
文档构建	`RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc`	确保文档可构建

可选检查项：

检查项	命令	说明
文档完整性	`RUSTDOCFLAGS="-D missing-docs" cargo doc`	检查缺失的文档（成熟后启用）
安全审计	`cargo audit`	检查依赖的安全漏洞

环境变量：

env:
  CARGO_TERM_COLOR: always
  RUSTDOCFLAGS: "-D rustdoc::broken_intra_doc_links"
  RUST_BACKTRACE: 1

配置示例：https://github.com/drivercraft/phytium-mci/blob/main/.github/workflows/check.yml

6.3 测试执行

文件位置：.github/workflows/test.yml

用途：执行单元测试、集成测试，确保功能正确性

触发条件：

push 到 main、dev 分支
pull_request 到 main、dev 分支

必须包含的测试项：

测试项	命令	说明
单元测试	`cargo test --lib --all-features`	测试库代码功能
集成测试	`cargo test --all-features`	运行所有测试（包括集成测试）
文档测试	`cargo test --doc`	验证文档示例代码

可选测试项：

测试项	命令	说明
覆盖率检查	`cargo tarpaulin --out Xml`	生成测试覆盖率报告
性能测试	`cargo bench`	检查性能退化

平台支持：

必须支持：x86_64-unknown-linux-gnu
可选平台：x86_64-pc-windows-msvc、x86_64-apple-darwin、riscv64gc-unknown-none-elf
如果组件声明支持某平台，CI 必须在该平台上运行测试

环境变量：

env:
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: 1

配置示例：https://github.com/drivercraft/phytium-mci/blob/main/.github/workflows/test.yml

6.4 文档部署

文件位置：.github/workflows/deploy.yml

用途：自动部署组件 API 文档到 GitHub Pages 或其他文档平台

触发条件：

push 到 main 分支
依赖关系：必须等待 check.yml 和 test.yml 全部通过后才执行

必须包含的步骤：

依赖检查：

needs: [check, test]  # 确保 check 和 test 工作流通过

文档生成：
```
cargo doc --no-deps --all-features
```
文档部署：
- 部署到 GitHub Pages
- 或部署到内部文档平台
- 生成文档索引

配置示例：https://github.com/drivercraft/phytium-mci/blob/main/.github/workflows/deploy.yml

注意，我们统一使用 Github Actions 方式部署 Pages，而不是旧的从分支部署，进而避免引入不必要的分支

6.5 自动发布

文件位置：.github/workflows/release.yml

用途：自动发布 GitHub Release 和 crates.io

触发条件：

push tags（v*）
依赖关系：必须等待 check.yml 和 test.yml 全部通过后才执行

必须包含的步骤：

依赖检查：

needs: [check, test]  # 确保 check 和 test 工作流通过

版本号一致性验证：
- 检查 Git tag 版本与 Cargo.toml 版本是否一致
- 不一致时必须拒绝发布
GitHub Release 发布：
- 创建 GitHub Release
- 生成 CHANGELOG
- 附加发布说明
crates.io 发布：
- 运行 cargo publish
- 验证发布成功

环境变量：

env:
  CARGO_REGISTRY_TOKEN: crates.io 上传 TOKEN

配置示例：https://github.com/drivercraft/phytium-mci/blob/main/.github/workflows/release.yml

七、维护与更新

7.1 维护列表

当任意 crate 有更新时，应及时更新 AxVisor Crates 维护列表。

7.2 版本维护策略

长期支持版本：建议为重要的稳定版本（如 0.1.x）创建专门的维护分支，接受 bug 修复和安全更新
兼容性保证：
- 同一主版本内（如 0.1.x）必须保持向后兼容
- 破坏性变更必须在新的主版本（如 0.2.0）中引入
弃用策略：
- 弃用的 API 应保留至少一个主版本周期
- 必须在文档中明确标注弃用状态和替代方案

7.3 安全更新

对于安全漏洞的修复：

必须在受影响的维护分支上修复
必须尽快发布补丁版本
必须在安全公告中说明影响范围和修复方案
必须更新所有受影响的下游依赖

八、常见问题与解决方案

8.1 版本冲突

问题：发布时提示版本已存在

原因：

在不同分支发布了相同版本号
之前发布过但忘记了

解决方案：

# 1. 查看已发布的版本
cargo search crate-name

# 2. 查看本地 git tags
git tag -l

# 3. 更新到新的版本号
# 修改 Cargo.toml 中的版本号

# 4. 如果确实需要重新发布，先 yank 旧版本
cargo yank crate-name@0.1.2
# 然后发布新版本
cargo publish

8.2 文档编译失败

问题：docs.rs 编译失败

原因：

crate 依赖特定平台
文档中的示例代码有错误
文档链接失效

解决方案：

# 1. 本地验证文档编译
RUSTDOCFLAGS="--cfg docsrs" cargo doc --no-deps --all-features

# 2. 检查文档链接
cargo doc --no-deps 2>&1 | grep "broken"

# 3. 配置 docs.rs 元数据
[package.metadata.docs.rs]
default-target = "riscv64gc-unknown-none-elf"
targets = ["riscv64gc-unknown-none-elf"]

# 4. 修复文档示例
# 确保文档中的代码可以编译和运行

8.3 依赖解析失败

问题：下游项目无法解析依赖版本

原因：

版本号不符合 SemVer
依赖的版本范围不合理
存在循环依赖

解决方案：

# 1. 检查依赖树
cargo tree

# 2. 检查版本冲突
cargo tree -d

# 3. 更新依赖
cargo update

# 4. 使用 cargo fix 修复问题
cargo fix --edition-idioms

8.4 发布失败

问题：cargo publish 失败

常见原因和解决方案：

# 原因 1：未登录
error: no token found for crates.io
# 解决：cargo login

# 原因 2：crate 名称已被占用
error: crate 'xxx' already exists
# 解决：更换 crate 名称

# 原因 3：版本已存在
error: version 0.1.0 is already uploaded
# 解决：更新版本号

# 原因 4：有未提交的更改
error: files in the working directory contain changes
# 解决：先提交或暂存更改

# 原因 5：dry-run 失败
error: failed to verify package
# 解决：修复错误后再发布

8.5 CI 检查失败

问题：CI 检查失败但本地通过

原因：

本地和 CI 环境差异
缓存问题
平台差异

解决方案：

# 1. 本地复现 CI 环境
cargo clean
cargo build --all-features

# 2. 检查 Rust 版本
rustc --version
# 确保与 CI 中的版本一致

# 3. 检查环境变量
# CI 中可能设置了特殊的环境变量

# 4. 使用 act 本地运行 GitHub Actions
act push

8.6 测试失败

问题：测试在 CI 中失败但本地通过

原因：

时区或时间相关
随机性
并发问题
环境差异

解决方案：

// 1. 使用固定的测试数据
#[test]
fn test_with_fixed_data() {
    let data = [1, 2, 3, 4, 5];
    // 测试逻辑
}

// 2. 设置随机种子
#[test]
fn test_random() {
    use rand::SeedableRng;
    let mut rng = rand::rngs::StdRng::seed_from_u64(42);
    // 测试逻辑
}

// 3. 避免时间相关测试
#[test]
fn test_time_independent() {
    // 不使用当前时间
    // 使用固定的时间戳
}

// 4. 使用串行测试
#[test]
#[serial]
fn test_concurrent() {
    // 需要串行执行的测试
}

附录：快速检查清单

说明：本清单仅列出关键检查项，详细规范请参考对应章节。CI/CD 会自动执行大部分检查，开发者只需关注本地验证和人工审查项。

A. 提交代码前

必须检查：

cargo fmt 格式化代码
cargo clippy 无警告
cargo test 测试通过
提交信息符合约定式提交格式（feat/fix/docs/refactor等）

可选检查（根据变更内容）：

新增公开 API 有文档注释
新增功能有对应测试
CHANGELOG.md 已更新（用户可见变更）

B. 创建 PR 前

必须检查：

CI 检查全部通过（自动执行）
代码已自我审查
相关文档已更新

可选检查（根据变更内容）：

破坏性变更已在文档中说明
新增依赖有必要且合理

C. 发布版本前

注意：大部分发布工作由 CI 自动完成，以下为人工确认项。

版本号与元数据：

版本号符合 SemVer 规范
Cargo.toml 信息完整（description、license、repository 等）
CHANGELOG.md 已更新
在正确分支创建 tag（稳定版在 main、预发布版在 dev）

质量确认：

CI 检查全部通过
cargo publish --dry-run 成功
核心功能已手动验证

发布后：

确认 crates.io 发布成功
确认 GitHub Release 创建成功
更新维护列表（如有）

D. 应急处理

严重 Bug 修复：

在受影响分支修复
更新 PATCH 版本号
快速发布补丁版本
通知受影响用户

错误版本撤回：

执行 cargo yank <version>
分析并修复问题
发布新版本

安全漏洞处理：

在维护分支修复
尽快发布补丁版本
发布安全公告
通知下游依赖维护者

E. 定期维护（可选）

每月检查：

运行 cargo audit 检查安全漏洞
运行 cargo outdated 检查依赖更新

每季度检查：

评估是否需要发布新版本
处理用户反馈和问题

版本历史

v3.0 (2026-03-02):
- 清理了一些不符合的内容
- 更新了 CI/CD 章节
v2.0 (2026-01-27):
- 清理了不必要的仓库分支
- 更新了 CI/CD 章节
- 规范发布流程
v1.0 (2026-01-21): 初始版本
- 建立基本的组件管理规范
- 定义分支管理策略
- 规范发布流程
- 添加 CI/CD 配置

本规范由 AxVisor 团队维护，如有疑问或建议，请提交 Issue 或 PR。

最后更新：2026-03-02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

arceos-hypervisor

组件开发及管理规范 #371

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

arceos-hypervisor

组件开发及管理规范 #371

Uh oh!

ZCShou Mar 2, 2026 Maintainer

组件开发及管理规范

一、概述

1.1 背景与目的

1.2 适用范围

二、组件开发规范

2.1 代码注释规范

2.2 测试规范

2.2.1 单元测试

2.2.2 功能测试

2.2.3 系统测试

2.2.4 文档测试

2.2.5 测试运行要求

2.3 代码结构规范

2.4 命名规范

2.5 Cargo.toml 规范

2.6 提交信息规范

三、组件仓库分支管理

3.1 分支规划

3.1.1 固定分支

3.1.2 临时分支

3.1.3 工作流程

3.2 版本发布与管理

3.2.1 版本号规范

3.2.2 Git Tag 发布规范

四、组件依赖管理

4.1 版本号规范

4.1.1 版本声明原则

4.1.2 依赖版本管理

4.2 依赖声明顺序规范

4.2.1 依赖分组规则

4.2.2 依赖声明模板

4.2.3 依赖注释规范

4.3 依赖层级控制

4.3.1 最大依赖深度

4.3.2 循环依赖检测与避免

4.3.3 依赖数量控制

4.4 特定架构依赖管理

4.4.1 平台特定依赖

4.4.2 条件依赖

4.4.3 裸机目标依赖

4.4.4 docs.rs 构建配置

五、组件发布流程

5.1 发布前检查清单

5.2 发布流程

5.2.1 发布稳定版

5.2.2 发布预览版

5.3 版本回撤

六、CI/CD 规范

6.1 工作流规范

6.2 代码质量检查

6.3 测试执行

6.4 文档部署

6.5 自动发布

七、维护与更新

7.1 维护列表

7.2 版本维护策略

7.3 安全更新

八、常见问题与解决方案

8.1 版本冲突

8.2 文档编译失败

8.3 依赖解析失败

8.4 发布失败

8.5 CI 检查失败

8.6 测试失败

附录：快速检查清单

A. 提交代码前

B. 创建 PR 前

C. 发布版本前

D. 应急处理

E. 定期维护（可选）

版本历史

Replies: 0 comments

ZCShou
Mar 2, 2026
Maintainer