sdforge 0.5.0-rc.2

中文 | English

SDForge 是一个基于 Rust 的声明式 SDK 框架，利用过程宏从统一的函数注解自动生成多协议服务接口（HTTP + MCP + gRPC + WebSocket + CLI）。其核心创新在于通过 Cargo features 进行编译时协议选择——未使用的协议将产生零编译代码。

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

📋 目录

• ✨ 功能特性
• 🚀 快速开始
  • 📦 安装
  • 💡 基本用法
  • 📁 模块前缀
  • 🔢 多版本管理
  • 🛤️ 路径参数
  • ⚠️ 错误处理
  • 🔧 #[forge] 宏参数
  • 🌐 协议组合
  • 🛰️ gRPC Dispatch
  • 🖥️ CLI Dispatch
• 🎨 特性标志
• 📚 文档
• 💻 示例
• 🏗️ 架构
• 📜 OpenAPI 自动生成
• 🔄 MCP 2026-07-28 迁移指南
• 🚀 生产部署
• 🐛 故障排查
• 🧪 测试
• 📊 性能
• 🔒 安全
• 🗺️ 开发路线图
• 🤝 参与贡献
• 📋 更新日志
• 📄 许可证
• 🙏 致谢
• 📞 联系与支持
• ⭐ Star 历史

✨ 功能特性

🔌 可选功能

以下能力均通过 Cargo feature 按需启用，详见特性标志：

🆕 Phase 1 架构改进

近期的架构增强包括：

• 🔄 统一注册系统 — 通过 trait 抽象与过程宏，消除 HTTP、MCP、WebSocket、gRPC 模块间 95+ 行重复代码
• ⚙️ 模块化配置管理 — 配置重构为独立模块（app、cache、security），集中默认值并支持 Builder 模式
• 🔐 增强安全模块 — API Key 版本管理、LRU 缓存、带审计日志的密钥轮换、完善的安全头配置
• 💾 高级缓存 — 基于模式的缓存失效、键规范化、批量操作与统计信息跟踪

🚀 快速开始

📦 安装

cargo add sdforge

或手动添加到 Cargo.toml：

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

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

💡 基本用法

使用单个宏定义你的 API：

use sdforge::prelude::*;

#[forge(
    name = "get_user",
    version = "v1",
    path = "/users/:id",
    method = "GET",
    tool_name = "get_user",
    description = "Get a user by ID"
)]
async fn get_user(id: u64) -> Result<User, ApiError> {
    Ok(User { id, name: "Test".into() })
}

#[tokio::main]
async fn main() {
    let app = sdforge::http::build();
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

📁 模块前缀

使用模块前缀对相关 API 进行分组：

#[service_module(prefix = "/auth")]
mod auth_api {
    use super::*;

    #[forge(
        name = "login",
        version = "v1",
        path = "/login",
        method = "POST"
    )]
    async fn login(credentials: Credentials) -> Result<Token, ApiError> {
        Ok(Token::new())
    }

    #[forge(
        name = "logout",
        version = "v1",
        path = "/logout",
        method = "POST"
    )]
    async fn logout() -> Result<(), ApiError> {
        Ok(())
    }
}

这将生成端点：

• /auth/api/v1/login
• /auth/api/v1/logout

🔢 多版本管理

同时支持多个 API 版本：

#[forge(
    name = "get_user",
    version = "v1",
    path = "/users/:id",
    method = "GET",
    tool_name = "get_user_v1"
)]
async fn get_user_v1(id: u64) -> Result<UserV1, ApiError> {
    Ok(UserV1 { id, name: "John Doe".into() })
}

#[forge(
    name = "get_user",
    version = "v2",
    path = "/users/:id",
    method = "GET",
    tool_name = "get_user_v2"
)]
async fn get_user_v2(id: u64) -> Result<UserV2, ApiError> {
    Ok(UserV2 { id, first_name: "John".into(), last_name: "Doe".into() })
}

这将生成带版本的端点：

• /api/v1/users/:id → get_user_v1
• /api/v2/users/:id → get_user_v2

🛤️ 路径参数

遵循 Rust 命名规范提取路径参数。宏自动将路径段映射到函数参数：

#[forge(
    name = "get_user",
    version = "v1",
    path = "/users/:id",
    method = "GET"
)]
async fn get_user(id: u64) -> Result<User, ApiError> {
    // `id` 自动从 `/users/:id` 提取
    Ok(User { id, name: "John".into() })
}

🔹 多个路径参数

对于嵌套资源：

#[forge(
    name = "get_comment",
    version = "v1",
    path = "/posts/:post_id/comments/:comment_id",
    method = "GET"
)]
async fn get_comment(
    post_id: u64,
    comment_id: u64
) -> Result<Comment, ApiError> {
    // 两个参数均从路径提取
    Ok(Comment { post_id, comment_id, text: "Test".into() })
}

#[forge(
    name = "get_task",
    version = "v1",
    path = "/orgs/:org_id/projects/:project_id/tasks/:task_id",
    method = "GET"
)]
async fn get_task(
    org_id: u64,
    project_id: u64,
    task_id: u64
) -> Result<Task, ApiError> {
    Ok(Task { org_id, project_id, task_id, title: "Task".into() })
}

⚠️ 错误处理

定义自定义错误类型并转换为 ServiceError：

use thiserror::Error;

#[derive(Debug, Error)]
pub enum MyError {
    #[error("Resource not found: {resource}")]
    NotFound { resource: String },

    #[error("Validation failed: {field}")]
    ValidationError { field: String },

    #[error("Unauthorized access")]
    Unauthorized,
}

impl From<MyError> for ServiceError {
    fn from(err: MyError) -> Self {
        match err {
            MyError::NotFound { resource } => ServiceError::with_details(
                "NOT_FOUND",
                format!("Resource not found: {}", resource),
                serde_json::json!({ "resource": resource }),
                404,
            ),
            MyError::ValidationError { field } => ServiceError::with_details(
                "VALIDATION_ERROR",
                format!("Validation failed for field: {}", field),
                serde_json::json!({ "field": field }),
                400,
            ),
            MyError::Unauthorized => ServiceError::new(
                "UNAUTHORIZED",
                "Authentication required",
                401,
            ),
        }
    }
}

🔧 #[forge] 宏参数

🌐 协议组合

仅 HTTP — 传统 REST API：

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

仅 MCP — AI 工具集成：

[dependencies]
sdforge = { version = "0.5.0-rc.2", features = ["mcp"] }

双协议 — 同一份代码同时通过 HTTP 与 MCP 暴露：

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

全量特性 — 启用全部能力：

[dependencies]
sdforge = { version = "0.5.0-rc.2", features = ["full"] }

🛰️ gRPC Dispatch

启用 grpc feature 后，#[forge(grpc_method = "...")] 会通过 inventory 注册到 SdForgeGrpcService，由其 call() 方法路由到对应 handler。返回值需满足 serde::Serialize，错误类型需为 ApiError：

[dependencies]
sdforge = { version = "0.5.0-rc.2", features = ["grpc"] }

use sdforge::prelude::*;
use sdforge::forge;

#[forge(
    name = "grpc_echo",
    version = "v1",
    grpc_method = "comprehensive.echo",
    description = "gRPC echo handler"
)]
async fn echo(msg: String) -> Result<serde_json::Value, ApiError> {
    Ok(serde_json::json!({ "echo": msg }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    sdforge::init_all_plugins();
    let server = sdforge::grpc::SdForgeGrpcService::default();
    server.serve("0.0.0.0:50051").await?;
    Ok(())
}

🖥️ CLI Dispatch

启用 cli feature 后，#[forge(cli = true)] 会注册 CliCommandRegistration + CliHandlerRegistration，由 CliBuilder::execute() 一站式完成 build / parse / dispatch / 输出 / 退出。返回 Value::String 时输出原始串（不带引号），其他类型 输出 JSON：

[dependencies]
sdforge = { version = "0.5.0-rc.2", features = ["cli"] }
tokio = { version = "1", features = ["rt-multi-thread", "macros"] }

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() 返回 `!`：内部 std::process::exit(0/1)，调用方无需 match
    CliBuilder::new().execute().await;
}

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

🎨 特性标志

SDForge 使用 Cargo features 进行编译时协议选择和特性组合。

🔗 特性依赖关系

• default: 空（无预启用特性，需按需显式启用）
• mcp/grpc/openapi/cli/streaming/cache: 独立于 http
• security: 启用 http、ratelimit-http（含 ratelimit）与 cache，并引入 hmac/sha2/uuid 等安全依赖
• ratelimit-http: 需要 http + ratelimit
• websocket: 需要 http + streaming
• docs: 需要 openapi + cli（Swagger UI 子模块需额外启用 http）
• kit: trait-kit AsyncKit 集成，需要 limiteron-integration + trait-kit
• full: 启用全部运行时特性（不含 simd-json 与 hex 工具特性）

🔨 构建与测试

# 默认（无特性）
cargo build

# HTTP 协议
cargo build --features http

# MCP 协议
cargo build --features mcp

# 完整功能
cargo build --features full

# 自定义特性集
cargo build --features "http,cache,security"

# 测试
cargo test --features http
cargo test --features full

# 格式化与 Lint
cargo fmt
cargo clippy --all-features -- -D warnings

📚 文档

💻 示例

仓库包含两类示例。

可运行示例（根包 cargo run --example）

# CLI 示例
cargo run --example basic_cli --features cli -- echo --name world

# Swagger UI 示例
cargo run --example swagger_demo --features "docs http"

# 缓存性能示例
cargo run --example perf_regex_cache --features cache

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

# 运行综合示例库的全部模块测试
cargo test --manifest-path examples/Cargo.toml --lib

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

🏗️ 架构

SDForge 采用「统一宏注解 → 编译期协议门控 → inventory 运行时注册」的架构。完整设计说明见 架构文档。

sdforge/
├── src/                # 主框架 crate
│   ├── core/         # 核心类型、错误处理、验证
│   ├── error/        # 框架错误类型（ApiError、SdForgeError）
│   ├── http/         # HTTP 协议实现 (Axum)
│   ├── mcp/          # MCP 协议实现 (rmcp)
│   ├── security/     # 安全特性 (认证、限流、审计)
│   ├── cache/        # 缓存集成 (oxcache)
│   ├── websocket/    # WebSocket 支持
│   ├── grpc/         # gRPC 支持 (tonic)
│   ├── streaming/    # SSE 流式支持
│   ├── cli/          # CLI 集成 (clap)
│   ├── docs/         # 文档生成 (Swagger UI + Markdown)
│   ├── openapi/      # OpenAPI 3.1 规范生成
│   ├── domain/       # 领域抽象
│   ├── config/       # 配置管理
│   ├── i18n/         # 国际化 (ICU4X)
│   ├── integrations/ # trait-kit AsyncKit 集成
│   └── lib.rs        # 库入口点
├── macros/            # 过程宏 crate (#[forge])
├── examples/          # 综合示例库 (workspace member)
├── docs/              # 文档
├── benches/           # 基准测试
├── proto/             # protobuf 定义 (gRPC)
├── .github/           # GitHub 工作流
└── scripts/           # 构建和实用脚本

设计原则

• 编译时协议选择：未使用的协议不产生任何编译代码
• Inventory 注册模式：inventory::submit!() 用于编译时注册，init_all_plugins() 防止链接器优化
• 三种构造模式：所有组件支持 new()（开箱即用）、builder()（Builder 模式）、with_dependencies()（依赖注入）
• 不使用数据库：所有数据交互通过 oxcache（内存缓存）完成

📜 OpenAPI 自动生成

SDForge 基于 utoipa 5.5 自动生成 OpenAPI 3.1 规范。启用 openapi feature 后，每个 #[forge] 宏在编译期通过 inventory 注册 OpenApiRouteInfo；运行时调用 generate_openapi_spec() 收集全部路由并生成完整规范。

🔧 启用

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

🚀 基本用法

use sdforge::openapi::generate_openapi_spec;

// 收集所有通过 #[forge] 注册的路由并生成 OpenAPI 规范
let spec = generate_openapi_spec();

// 序列化为 JSON 写入文件或返回给客户端
let json = serde_json::to_string_pretty(&spec).unwrap();
println!("{json}");

🎨 自定义元数据

使用 OpenApiBuilder 链式调用自定义 info 部分（title、version、description）。路由始终从全局 inventory 注册表收集：

use sdforge::openapi::OpenApiBuilder;

let spec = OpenApiBuilder::new()
    .title("My Service")
    .version("2.0.0")
    .description("User-facing API for the billing domain")
    .build();

🔗 宏集成

启用 openapi feature 后，#[forge] 自动生成注册代码，无需手动维护：

#[forge(
    name = "get_user",
    version = "v1",
    path = "/users/:id",
    method = "GET",
    description = "Get a user by ID"
)]
async fn get_user(id: u64) -> Result<User, ApiError> { /* ... */ }

上述代码会在编译期自动向全局注册表提交 OpenApiRouteInfo { path: "/users/{id}", method: "GET", ... }，generate_openapi_spec() 会将其纳入生成的规范。

注意：未启用 openapi feature 时，宏不生成任何 utoipa 相关代码——零运行时开销。

🔄 MCP 2026-07-28 迁移指南

v0.2.0 将 MCP 实现从 mcp-sdk 0.0.3 全面迁移至官方 rmcp SDK（当前为 rmcp 3.2），适配 MCP 2026-07-28 规范。该迁移是一次 BREAKING 变更。

⚠️ BREAKING 变更

🛠️ 无状态适配层

StatelessServerHandler 实现了 rmcp::ServerHandler trait，其方法均不依赖会话状态，适配 2026-07-28 规范的无状态协议模型：

use sdforge::mcp::stateless::StatelessServerHandler;

let handler = StatelessServerHandler::new();
// 通过 rmcp 的 axum 集成挂载到 HTTP 路由

📨 HTTP 头协议

无状态协议通过 HTTP 头传递方法名与工具名，由 parse_mcp_headers 解析：

use sdforge::mcp::headers::parse_mcp_headers;

// 客户端请求必须携带：
//   Mcp-Method: tools/call
//   Mcp-Name: get_user
let info = parse_mcp_headers(&headers)?;

缺少请求头返回 400 Bad Request，与 2026-07-28 规范一致。

🔁 多轮往返请求（MRTR）

新增 MRTR 支持。工具可通过 InputRequiredResult 挂起执行，等待客户端补充输入；300 秒超时后自动取消：

use sdforge::mcp::mrtr::MrtrSessionManager;

let manager = MrtrSessionManager::new();
let result = manager.create_session("session-1", "get_user")?;
// 客户端随后通过 session_id 恢复执行

💾 缓存语义

cache_semantics 模块处理 ttlMs 与 cacheScope 字段，支持 global 与 request 两种缓存作用域，并与 oxcache 集成实现工具结果缓存。

📚 迁移步骤

1. 将 Cargo.toml 中的 mcp-sdk 依赖替换为 rmcp
2. 将 register_mcp(&mut Server) 调用改为 register_mcp(&mut dyn McpToolRegistry)
3. 移除 initialize 握手相关代码，改用 server/discover 端点
4. 如需 MRTR 或缓存语义，导入对应模块

完整迁移示例见 examples/src/mcp/migration_2026.rs。

🚀 生产部署

🐳 Docker 部署

FROM rust:1.85 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features full

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/sdforge /usr/local/bin/
EXPOSE 3000
CMD ["sdforge", "serve", "--port", "3000"]

☸️ Kubernetes 部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: sdforge-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: sdforge-api
  template:
    metadata:
      labels:
        app: sdforge-api
    spec:
      containers:
      - name: sdforge
        image: sdforge:latest
        ports:
        - containerPort: 3000
        env:
        - name: FEATURES
          value: "full"
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

🔧 环境配置

# 生产环境变量
export RUST_LOG=info
export SD_FORGE_PORT=3000
export SD_FORGE_HOST=0.0.0.0
export SD_FORGE_CONFIG_PATH=/etc/sdforge/config.toml
export SD_FORGE_FEATURES=full

🐛 故障排查

🔍 常见问题

编译错误

# 错误：找不到 feature
# 解决：检查可用的 features
cargo check --help | grep features

# 启用指定 features
cargo build --features "http,security,cache"

运行时问题

# 使用 tracing 查看日志
RUST_LOG=debug cargo run --features logging

# 端口冲突
# 解决：更换端口或结束占用进程
lsof -i :3000
kill -9 <PID>

性能问题

# 使用 cargo-flamegraph 剖析
cargo install flamegraph
cargo flamegraph --bin sdforge --features full

# 内存占用分析
valgrind --tool=massif target/release/sdforge

📋 健康检查端点

#[forge(
    name = "health_check",
    version = "v1",
    path = "/health",
    method = "GET"
)]
async fn health_check() -> Result<HealthStatus, ApiError> {
    Ok(HealthStatus {
        status: "healthy".to_string(),
        version: env!("CARGO_PKG_VERSION").to_string(),
        uptime: get_uptime(),
    })
}

🆘 获取帮助

• 📖 文档
• 🐛 Issue 跟踪
• 💬 Discussions

🧪 测试

测试分类

运行命令

# 按特性运行测试
cargo test --features http
cargo test --features mcp
cargo test --features "http,mcp"
cargo test --features full

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

# 运行指定测试
cargo test test_get_user --features http

# 带输出运行
cargo test --features http -- --nocapture

# Release 模式测试
cargo test --release --features http

CI 通过 cargo llvm-cov --features full --lib 生成覆盖率并上传 Codecov。

📊 性能

SDForge 的编译时特性门控带来显著的编译时间与产物体积优势（vs 全量打包 --features full）：

数据来源：docs/benchmarks/vs-server-less.md（2026-07-03 实测，AMD Ryzen 9 9950X / rustc 1.93.1 / WSL2）。完整方法论、二进制体积分析与复现命令见该文档。

🔒 安全

SDForge 内置全套安全能力（security feature）：API Key / JWT Bearer 认证、限流（limiteron）、审计日志、安全头（CORS/CSP）、输入校验。概要设计与最佳实践见 安全文档。

🛡️ API Key 认证

use sdforge::security::{ApiKeyAuth, auth_middleware};

let app = Router::new()
    .route("/api/*path", get(handler))
    .layer(auth_middleware(ApiKeyAuth::new("your-secret-key")));

⚡ 限流配置

# config.toml
[rate_limit]
enabled = true
requests_per_minute = 60
burst_size = 10

⚠️ 安全默认值（v0.3.0+）

注意：v0.3.0 收紧了安全默认值，迁移时请检查：

• JWT 密钥最小长度：MIN_SECRET_LENGTH=32，短于 32 字符的密钥将被拒绝
• ServerConfig 默认 host：从 "0.0.0.0"（fail-open）改为 "127.0.0.1"（fail-safe 回环），生产部署必须显式配置 host
• CORS 校验收紧："http://"（仅 scheme 无 host）将被拒绝

另：v0.4.4 起 extract_client_ip_core 在无 ConnectInfo 时不再信任 X-Forwarded-For / X-Real-IP 头，生产部署必须配置 ConnectInfo 以启用不可伪造的 TCP 对端 IP 提取。

🗺️ 开发路线图

以下规划整理自 CHANGELOG.md 未发布条目与工作区验收计划（ACCEPTANCE_PLAN.md）：

• v0.5.0 发布（进行中） — 当前处于 0.5.0-rc.2，按工作区验收计划完成依赖链（trait-kit/oxcache/inklog/limiteron）协同发布与终验
• 自定义成功状态码（已合入待发布） — #[forge(status = <code>)] 静态声明 + ServiceResponse::success_with_status 动态控制（见 CHANGELOG [Unreleased]）
• 错误码行为契约统一 — 评估统一同一校验错误在 HTTP（400）与 gRPC（422）间的状态码差异（验收计划 SIMPL-001，现为记录在案的行为契约）
• 依赖治理 — 中期评估将 bincode（RUSTSEC-2025-0141 unmaintained）迁移至 postcard / bitcode / rkyv
• MSRV 声明收敛 — 已按工作区 CONFIG_BASELINE 统一为 1.97.1（2026-09-06），覆盖 --all-features 下 1.94 的有效要求

🤝 参与贡献

我们欢迎贡献！请阅读 贡献指南 了解开发环境、TDD 工作流和 PR 流程。

# 克隆仓库
git clone https://github.com/Kirky-X/sdforge.git
cd sdforge

# 安装 pre-commit 钩子
./scripts/install-pre-commit.sh

# 验证环境
cargo build --all-features
cargo test --all-features --lib

📋 更新日志

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

• [Unreleased] — #[forge(status = <code>)] 自定义成功状态码（静态声明 + ServiceResponse::success_with_status 动态控制，HTTP/gRPC 拉通，OpenAPI 同步）
• [0.4.7] — 依赖版本约束移除波浪号；补公开 bincode RUSTSEC-2025-0141 ignore 决策
• [0.4.6] — CI Clippy 修复；恢复 examples 的 serde 依赖
• [0.4.5] — 新增 tests/e2e_advanced.rs（178 个测试）

📄 许可证

本项目基于 MIT + Commons Clause 许可证发布，商业使用需单独授权。详见 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

📞 联系与支持

• 🐛 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