pma-rust

Rust 项目实现与验收指南

请将此技能与 /pma 一起使用。/pma 管理工作流、审批和任务跟踪；本指南规定了每个 PMA-Rust 项目的产品级验收基线。

此技能不指定版本：每个 crate、工具链、edition 和基础镜像都从注册表中已验证的最新稳定版本开始（参见 /pma references/workflow.md 中的 Dependency Freshness）。references/evidence.md 中的版本是证据，而非目标。

硬性要求

定义见 references/baseline.md 中的 Hard Locks；如需放宽某项要求，须遵循其中的 Known Trade-offs 部分。未落实这些要求时，/pma 会拒绝批准实现。

1. 优先选用成熟的 crate；不要求使用纯 Rust，但每个发布目标都必须能够构建
2. 仅使用 rustls，并在 main() 中安装 aws-lc-rs 提供程序
3. 每个 crate 根目录都必须包含 #![forbid(unsafe_code)]
4. 在 [workspace.lints] 中禁止警告，而非通过 CLI 实现
5. 声明 MSRV 并在 CI 中验证
6. 运行时路径中不得使用 unwrap / expect / panic!
7. 使用最新稳定版 edition
8. 合并前所有质量门禁均须通过（references/delivery.md）

标杆项目依据

每项建议都以 10 个经克隆验证的项目中的文件行号证据为依据（cargo、rust-analyzer、reth、vector、tokio、axum、linkerd2-proxy、uv、ruff、quickwit）；引用见 references/evidence.md。

加载顺序

始终先加载 references/baseline.md。然后加载与任务相关的资料包：

1. references/baseline.md — 硬性要求、技术栈、命名、代码质量（始终必需）
2. references/toolchain-and-workspace.md — 工作空间布局、edition、[workspace.lints] 与构建标志模式、工具链固定、开发循环工具
3. references/runtime-and-data.md — Axum + tower + tokio 运行时、使用 IntoResponse 处理错误、SQLx/SeaORM/Diesel 选型、分层配置、优雅关闭
4. references/delivery.md — 安全、密钥、OTLP 可观测性、测试层级、供应链（cargo-deny/cargo-shear/typos）、发布自动化、CI
5. references/evidence.md — 引用依据（验证或扩展此技能时加载）

快速路由

如果任务涉及……	加载
新工作空间、lint、工具链、开发工具	toolchain-and-workspace.md
Axum/tower 处理程序、数据库访问、配置、关闭	runtime-and-data.md
测试、CI、可观测性、发布、密钥、供应链	delivery.md
“为什么要有这条规则？”/“有什么证据能证明 X 是最佳实践？”	evidence.md
其他任何内容（始终）	baseline.md

验收清单（PMA 门槛）

在 /pma 接受 Rust crate 或服务用于生产之前：

• 工作区声明最新稳定版 edition 和 rust-version
• 每个 crate 都有 #![forbid(unsafe_code)]（或记录有据的例外）
• CI 运行：fmt + clippy（采用工作区 deny-warnings 策略）+ nextest + --doc 测试 + cargo-deny + cargo-shear（或 machete）+ typos + MSRV 检查（cargo hack check --rust-version 或 cargo msrv verify）
• 没有传递依赖 openssl / native-tls（通过 cargo deny bans 验证）
• 所有 TLS 均使用 rustls；在 main 中尽早安装 aws-lc-rs provider（规范代码片段：references/baseline.md Lock 2）
• 在生产环境中使用 JSON formatter 初始化 tracing；OTLP 可选
• 服务提供 /livez（存活）+ /readyz（就绪）端点
• 通过 axum::serve(...).with_graceful_shutdown(...) + CancellationToken（或等效机制）接入优雅关停
• 使用 secrecy::SecretString / SecretBox<T> 封装密钥；绝不使用 Debug 格式化
• 配置按层加载：默认值 → 文件 → 环境变量 → CLI；合并后进行验证
• 按 crate 定义错误类型（thiserror）；仅在二进制入口点使用 anyhow/eyre
• 发布流水线可复现：标签 → CI → 已签名二进制文件（cargo-dist 或自定义方案）
• 当项目提供可移植 CLI 二进制文件时，使用 *-unknown-linux-musl 和 +crt-static 构建可分发二进制文件（通过 ldd 输出 "not a dynamic executable" 验证）
• 提供 CLI 二进制文件时，定义 [profile.dist]，并使用针对体积优化的选项（lto=fat、codegen-units=1、panic=abort、strip=symbols）
• 有意选择容器基础镜像，并记录在 docs/decisions/ 中：根据运维需求选择（最小运行时、便于调试、依赖 glibc、企业基础镜像、多架构）。不设固定体积目标——合适的体积取决于所选基础镜像和二进制文件的需求
• 在所有可触及的层级禁用核心转储——在 main 中尽早调用进程内的 rlimit::setrlimit(Resource::CORE, 0, 0)（始终如此），并根据环境配置 systemd LimitCORE=0 / 容器 --ulimit core=0:0 / K8s 只读根文件系统 / 内核 kernel.core_pattern = \|/bin/false
• 在 main 中安装 panic hook，在运行时中止前通过结构化的 tracing::error! 输出回溯；生产日志替代事后分析所需的核心转储

如有任何项目未通过，该项目就尚未达到生产就绪状态。