sdforge 0.5.0-rc.4

中文 | English

一套宏注解，编译时装配多协议 SDK

✨ 功能特性 • 🚀 快速开始 • 📚 文档 • 💻 示例 • 🤝 参与贡献

🎯 一份注解，五种协议

用 #[forge] 宏标注一次函数，编译期生成 HTTP、MCP、gRPC、WebSocket、CLI 注册代码：

📋 目录

• ✨ 功能特性
• 🚀 快速开始
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

参数校验、声明式分页、ETag 条件请求、生命周期钩子、钩子管道、优雅停机、健康探针、Prometheus 指标、OTel 导出、请求上下文、响应时间戳、结构化日志、inklog 桥接、trait-kit 集成、SIMD JSON 等能力均以独立 feature 按需启用，逐项说明与默认值见 特性标志 一节。

🚀 快速开始

📦 安装

cargo add sdforge

或手动添加到 Cargo.toml（当前版本 0.5.0-rc.3）：

[dependencies]
sdforge = { version = "0.5.0-rc.3", features = ["http"] }

最低要求：

• Rust 1.97.1+（edition 2024，rust-toolchain.toml 固定工具链）
• protoc：仅在启用 grpc feature 时需要（build.rs 编译 protobuf）

sdforge 默认不启用任何特性（default = []），按需显式启用协议特性。

💡 最小可运行示例

以下示例来自 examples/basic_cli.rs（cli feature）：

use sdforge::cli::CliBuilder;
use sdforge::core::ApiError;
use sdforge::forge;

#[forge(name = "echo", version = "1.0", description = "Echo a greeting", cli = true)]
async fn echo(name: String) -> Result<String, ApiError> {
    Ok(format!("Hello, {}!", name))
}

#[tokio::main]
async fn main() {
    sdforge::init_all_plugins();
    // execute() 返回 `!`：内部完成 build / parse / dispatch / 输出 / exit
    CliBuilder::new().execute().await;
}

cargo run --example basic_cli --features cli -- echo --name world
# 输出：Hello, world!（Value::String 智能提取，无引号）

🧭 核心概念

• #[forge] 注解描述一份端点元数据（名称、版本、路径、方法、描述），宏按启用的 feature 生成各协议注册代码，编译期经 inventory::submit!() 提交，启动时由 init_all_plugins() 一次性收集固化
• 按协议选择入口：http::build() / rmcp stdio / SdForgeGrpcService / CliBuilder::execute()

🔧 #[forge] 宏参数

#[forge] 必填 name 与 version；常用可选参数包括 path / method / status / description / tool_name / grpc_method / cli。完整参数表（含进阶参数与默认值）见 API 参考 的「#[forge] 参数」一节。

🌐 协议组合

grpc、websocket、streaming、openapi、cli、cache 均可独立于 http 启用，任意组合。

🎨 特性标志

default = []：所有特性均为可选，按需显式启用。

• 独立于 http：mcp / grpc / openapi / cli / streaming / cache / timestamp / context / logging / inklog / i18n / simd-json / limiteron-integration
• 派生自 http：security（含 ratelimit-http → ratelimit 与 cache）、ratelimit-http、websocket（含 streaming）、health / metrics / graceful / validate / paginate / lifecycle / hooks / otel
• docs = openapi + cli（Swagger UI 挂载需另启用 http）
• kit = trait-kit（health + lifecycle）+ limiteron-integration + limiteron/kit + oxcache/kit
• full 覆盖 18 项运行时特性，不含 simd-json / hex

📚 文档

💻 示例

根包示例（cargo run --example）

cargo run --example basic_cli --features cli -- echo --name world
cargo run --example swagger_demo --features "docs http"
cargo run --example perf_regex_cache --features cache

综合示例库（workspace 成员 sdforge-examples，examples/src/）

生态集成示例（sdforge-examples 成员示例）

cargo run -p sdforge-examples --example oxcache_admin --features oxcache_admin_example

示例配置文件位于 examples/config/（default.toml、minimal.toml、production.toml、api-key-auth.toml）。

🏗️ 架构

SDForge 由两个 crate 组成：macros/sdforge-macros 负责解析 #[forge] / #[service_module] 注解并按 feature 门控生成注册代码；sdforge 是运行时库。注册项编译期经 inventory::submit!() 提交、启动期由 init_all_plugins() 固化，各协议模块（http / mcp / grpc / websocket / streaming / cli）彼此独立、按 feature 编译，共享 core 的统一 handler 契约（HandlerArgs + HandlerState）。模块注册全景、仓库布局与设计取舍见 架构文档。

设计原则

编译时协议选择、inventory 注册模式、统一 handler 契约、三种构造模式（new() / builder() / with_dependencies()）、零数据库五大原则的完整阐述见 架构文档。

🔄 核心执行路径

以 HTTP 请求热路径为例：请求经中间件栈（认证 → 限流 → 安全头 / CORS）进入版本路由匹配 /api/{version}，由 forge handler 在统一 handler 契约（HandlerArgs + HandlerState）中执行业务逻辑，经 ServiceResponse 响应管道输出 JSON；MCP、gRPC、CLI 入口复用同一批 handler 与响应契约，中间件栈顺序、版本路由与响应管道由 http::build() / build_with_config() 装配。完整时序图与数据流见 架构文档。

🌐 一份注解，五种协议

#[forge] 宏按当前启用的 feature 生成对应协议的注册项（HTTP / MCP / gRPC / CLI / OpenAPI），未启用的协议不生成任何代码；MCP 经 Mcp-Method / Mcp-Name 头（或 stdio）路由，gRPC 经 SdForgeGrpcService::call() 按 grpc_method 分发，CLI 经 CliBuilder::execute() 完成解析、分发与退出码，协议之间无运行时耦合。编译期注册流与请求期数据流详见 架构文档。

🧪 测试

测试策略矩阵

运行命令

# 与 CI 矩阵一致（http / mcp / http,mcp / http,security / http,cache /
# http,websocket / http,grpc / http,streaming / full 共 9 种组合）
cargo test --features "http,mcp" --workspace
cargo test --features full --workspace

# lib 测试（CI 覆盖率口径）
cargo test --features full --lib

# 覆盖率（CI 门禁 ≥80% 行覆盖，lefthook pre-push 同口径）
cargo llvm-cov --features full --lib --lcov --fail-under-lines 80

# 格式化与零告警 Lint
cargo fmt --all -- --check
cargo clippy --workspace --all-targets --all-features -- -D warnings

覆盖率测量经 llvm-cov.toml 排除 build.rs 生成的 protobuf 代码（src/grpc/pb/）。

测试规模

约 2,900 个测试函数（src/ 2,015 + tests/ 704 + macros/ 59 + examples/ 126，grep 统计，截至 v0.5.0-rc.3）。

📊 性能

运行时热路径（criterion 基线）

plain_get 路由分发中位延迟约 553 ns（约 1.81 M req/s），1 个路径参数约 604 ns；HandlerArgs 装配与 JSON 序列化/反序列化等完整基线、环境口径与复现命令见 性能基线。

编译时门控收益（feature 门控 vs 全量打包）

http only 相比 full 节省约 47% 编译时间、框架库 rlib 体积缩减约六成、唯一依赖少 82 个 crate；完整数据与方法论见 编译期门控基准（2026-07-03 实测，AMD Ryzen 9 9950X / rustc 1.93.1 / WSL2）。

🔒 安全

🚨 漏洞上报

请勿通过公开 issue 报告安全漏洞。 请使用 GitHub Security Advisories 私密披露通道提交，响应时限与流程见 安全文档。

🛡️ 安全设计要点

认证（API Key / JWT Bearer 与密钥长度强制）、fail-safe 默认值（默认绑定 127.0.0.1）、不可伪造的客户端 IP、审计签名、错误脱敏、输入防御（MCP schema 校验与 1 MiB 载荷上限）等设计与取舍，详见 架构文档 与 安全文档。

🔍 供应链安全

CI 安全门禁常开：cargo deny check（deny.toml 策略）+ cargo audit，配合 CodeQL、Dependabot 与 pre-commit 密钥扫描（detect-secrets）；发布前另设 tiangang SAST 与 diting 审查门槛，见 贡献指南 发布流程。

🗺️ 开发路线图

🤝 参与贡献

欢迎贡献！开发环境初始化（工具链、protoc、lefthook / pre-commit 钩子）、TDD 工作流、特性组合校验与 Conventional Commits 提交规范（commit-msg 钩子强制校验），见 贡献指南。

📋 更新日志

详见 CHANGELOG.md。最近版本要点：

• [0.5.0-rc.3] (2026-09-10)：ResponseCacheLayer 响应缓存中间件、AppConfig security/cache 字段、AuditSink 审计存储抽象与 InklogAuditSink
• [0.5.0-rc.2] (2026-09-07)：#[forge(status = <code>)] 自定义成功状态码、i18n_key 参数与翻译注册表、rmcp 2.2 → 3.2
• [0.4.7] (2026-07-23)：依赖版本约束移除波浪号；补公开 bincode RUSTSEC-2025-0141 ignore 决策

📄 许可证

本项目基于 MIT + Commons Clause 双重条款发布：在 MIT 许可下可自由使用、修改与分发，但未经作者单独书面授权不得销售。详见 LICENSE。

Copyright (c) 2026 Kirky.X

🙏 致谢

SDForge 站在优秀的开源生态之上，感谢以下项目：

• Axum / Tower — HTTP 服务与中间件
• rmcp — MCP 官方 Rust SDK
• Tonic / Prost — gRPC 与 protobuf
• utoipa — OpenAPI 规范生成
• clap — 命令行解析
• inventory — 编译期注册
• ICU4X — 国际化
• base 工作区姊妹项目 oxcache、limiteron、trait-kit、inklog、dbnexus

📞 联系与支持

• 🐛 Issue：github.com/Kirky-X/sdforge/issues
• 💬 讨论：github.com/Kirky-X/sdforge/discussions
• 🏠 仓库：https://github.com/Kirky-X/sdforge
• 📖 文档：https://docs.rs/sdforge
• 👤 维护者：Kirky.X

⭐ Star 历史

💝 支持本项目

如果您觉得这个项目有用，请考虑给它一个 ⭐️！

Built with ❤️ using Rust