attested-delivery/rust-template

# `rust_template` [](https://github.com/attested-delivery/rust-template) [](https://github.com/attested-delivery/rust-template/actions/workflows/pipeline.yml) [](https://crates.io/crates/rust_template) [](https://docs.rs/rust_template) [](https://www.rust-lang.org/) [](https://github.com/attested-delivery/rust-template/blob/main/LICENSE) [](https://github.com/rust-lang/rust-clippy) [](https://github.com/EmbarkStudios/cargo-deny) [](https://github.com/gitleaks/gitleaks) [](https://docs.github.com/en/code-security/dependabot) 一个具备现代工具链和最佳实践的 Rust 模板 crate。 ## 功能 - **类型安全的错误处理**：使用 `thiserror` 提供清晰的错误类型 - **构建者模式**：通过编译期 `const` 函数进行配置 - **全面的测试**：包括单元测试、集成测试和基于属性的测试 - **现代工具链**：包含 clippy pedantic lints 和 cargo-deny 供应链安全检查 - **完整的文档**：所有公共 API 均附带示例 ## 安装说明 将以下内容添加到你的 `Cargo.toml` 中： ``` [dependencies] rust_template = "0.1" ``` 或者使用 cargo add： ``` cargo add rust_template ``` ## 快速开始 ``` use rust_template::{add, divide, Config}; fn main() -> Result<(), rust_template::Error> { // Basic arithmetic let sum = add(2, 3); println!("2 + 3 = {sum}"); // Safe division with error handling let quotient = divide(10, 2)?; println!("10 / 2 = {quotient}"); // Using configuration builder let config = Config::new() .with_verbose(true) .with_max_retries(5) .with_timeout(60); println!("Config: verbose={}, retries={}, timeout={}s", config.verbose(), config.max_retries(), config.timeout_secs()); Ok(()) } ``` ## API 概述 ### 函数 | 函数 | 描述 | |----------|-------------| | `add(a, b)` | 将两个数字相加（纯函数，`const fn`） | | `divide(a, b)` | 执行除法，针对除以零的情况返回 `Result` | | `process(input)` | 将 `&str` 解析并验证为 `i64` | ### 类型 | 类型 | 描述 | |------|-------------| | `Config` | 带有 consuming-self 构建者的配置结构 | | `Error` | 用于操作的错误类型（`thiserror`） | | `Result` | `Result` 的类型别名 | ## 入门指南 **初次使用？** 请阅读 [**你的第一个项目** 教程](docs/tutorials/first-project.md) —— 这是一份以学习为导向的详细指南，涵盖了从“使用此模板”到成功构建、完成第一次代码修改以及发布第一个版本的全过程。 如需以任务为导向的步骤，请参阅 [入门指南](docs/template/GETTING-STARTED.md)。 ## 开发说明 ### 前置条件 - Rust 1.92+（2024 edition）—— 通过 [rustup](https://rustup.rs/) 安装，**不要**使用 Homebrew - [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) 用于保障供应链安全 ### 配置 ``` # 通过 rustup 安装 Rust（而非 Homebrew） curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" # Clone 仓库 git clone https://github.com/attested-delivery/rust-template.git cd rust-template # Build cargo build # 运行测试 cargo test # 运行 linting cargo clippy --all-targets --all-features # 格式化代码 cargo fmt # 检查供应链安全 cargo deny check # 生成文档 cargo doc --open ``` ### 项目结构 ``` crates/ ├── lib.rs # Library entry point ├── main.rs # Binary entry point └── ... # Additional modules tests/ └── integration_test.rs Cargo.toml # Project manifest clippy.toml # Clippy configuration rustfmt.toml # Formatter configuration deny.toml # cargo-deny configuration CLAUDE.md # AI assistant instructions AGENTS.md # AI coding agent instructions .editorconfig # Cross-editor defaults .devcontainer/ # Codespaces / dev container config .vscode/ # VS Code settings and extensions ``` ### 代码质量 本项目保持着高标准的代码质量： - **Lint 检查**：包含 pedantic 和 nursery lints 的 clippy - **代码格式化**：采用自定义配置的 rustfmt - **测试**：单元测试、集成测试以及基于属性的测试 - **文档**：所有公共 API 均已编写文档并附带示例 - **供应链**：使用 cargo-deny 进行依赖审计 - **CI/CD**：利用 GitHub Actions 进行自动化测试 ### 运行检查 ``` # 运行所有检查 cargo fmt -- --check && \ cargo clippy --all-targets --all-features -- -D warnings && \ cargo test && \ cargo doc --no-deps && \ cargo deny check # 使用 MIRI 运行以检测 undefined behavior cargo +nightly miri test ``` ## CI/CD 和部署 此模板包含了可用于生产环境的工作流： ### 持续集成 - **CI** (`.github/workflows/pipeline.yml`) - 格式化、lint、测试、文档、供应链安全、MSRV 检查、覆盖率测试 - **安全审计** (`.github/workflows/security-audit.yml`) - 每日 cargo-audit 扫描 - **质量门禁** (`.github/workflows/quality-gates.yml`) - 在推送/PR 时以及每周计划任务中运行 `CodeQL` SAST、`OSV`/dependency-review SCA、`OpenSSF` Scorecard 以及 Trivy `IaC`/许可证检查 - **基准测试** (`.github/workflows/benchmark.yml`) - 使用 criterion 进行性能追踪 - **ADR 校验** (`.github/workflows/adr-validation.yml`) - 架构决策记录验证 ### 发布和部署 - **Release** (`.github/workflows/release.yml`) - 包含多平台二进制文件的经过验证的 GitHub 发布 - 构建目标：Linux (`x86_64`, ARM64)、macOS (`x86_64`, ARM64)、Windows (`x86_64`) - 制品命名为 `{bin}-{version}-{platform}`（例如 `rust_template-0.2.0-linux-amd64`） - 每个二进制文件均附带 SLSA 构建来源和 `CycloneDX` SBOM 证明 - 在发布正式发布前，会运行严格失败（fail-closed）的 `gh attestation verify` 门禁 - 单一的 `{bin}-{version}-checksums.txt` 校验和文件 - **Docker** (`.github/workflows/release-docker.yml` via `pipeline.yml`) - 多平台容器构建 - 支持平台：linux/amd64、linux/arm64 - 采用 Distroless 基础镜像以提升安全性 - 发布至 GitHub Container Registry (ghcr.io) - 使用版本号和 'latest' 进行标签标记 - 由集中式的签名工作流进行签名和验证，随后进行严格失败（fail-closed）验证 - **Publish** (`.github/workflows/publish.yml`) - 自动化发布到 crates.io - 完整的发布前验证 - 由版本标签触发 - crates.io Trusted Publishing (OIDC) - 无需 registry token 密钥 - registry 分发的 `.crate` 文件会被重新下载，进行字节比较并生成证明 - **Homebrew** (`.github/workflows/package-homebrew.yml`) - Tap formula 更新 - 在每次 Release 完成后运行 - 根据 Cargo.toml 元数据生成源 formula 到 `{owner}/homebrew-tap` ### 创建发布 发布流程由 `/release` 技能（`.claude/skills/release/SKILL.md`）进行端到端的编排。完整的流程、门禁和时机记录在权威的 [发布运行手册](docs/runbooks/RELEASING.md) 中；设计原理请参阅 [签名发布](docs/security/SIGNED-RELEASES.md)。 简而言之：在 `Cargo.toml` 中提升版本号，推送一个 `vX.Y.Z` 标签，随后工作流将使用 SLSA 来源构建所有平台的二进制文件，生成并验证 `CycloneDX` SBOM，对每项证明进行严格失败（fail-closed）验证，然后创建 GitHub release，对镜像进行签名/推送，发布到 crates.io（通过 Trusted Publishing），并更新 Homebrew tap。 针对每种制品类型的验证命令位于 [SECURITY.md](SECURITY.md#verifying-release-artifacts) 中。 ### AI 编程助手 - **Copilot 配置** (`.github/workflows/copilot-setup-steps.yml`) - GitHub Copilot 编程助手的环境配置 - **Agent 指令**：`AGENTS.md`、`.github/copilot-instructions.md`、`CLAUDE.md` - **特定路径指令**：`.github/instructions/` 用于 Rust 代码和测试模式 - **可复用 Prompts**：`.github/prompts/` 用于常见开发任务 ### Docker 使用 拉取并运行容器： ``` # 拉取最新代码 docker pull ghcr.io/attested-delivery/rust-template:latest # 运行特定版本 docker pull ghcr.io/attested-delivery/rust-template:v0.1.0 docker run --rm ghcr.io/attested-delivery/rust-template:v0.1.0 --version ``` ## MSRV 策略 最低支持的 Rust 版本 (MSRV) 为 **1.92**。提升 MSRV 被视为一次次要的破坏性变更。 ## 许可证 本项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](https://github.com/attested-delivery/rust-template/blob/main/LICENSE) 文件。 ## 致谢 - [The Rust Programming Language](https://www.rust-lang.org/) - [Cargo](https://doc.rust-lang.org/cargo/) - [clippy](https://github.com/rust-lang/rust-clippy)

标签：DevSecOps, Rust, 上游代理, 可视化界面, 网络流量审计, 请求拦截, 软件供应链安全, 远程方法调用, 项目模板