HwhKit

HwhKit 是一个面向 Rust Web 服务的工程化脚手架库，目标是把不变的基础设施沉淀到框架层，让业务项目只保留最小可变部分。

0.6.0-alpha.1 — pre-1.0 API stabilization release. The legacy v1 surface (WebServerBuilder, JwtAuth, hwhkit-macros, hwhkit-transport) has been removed. See MIGRATION.md. Use hwhkit::run_and_serve and impl Application for MyApp. Common imports are at hwhkit::prelude::*.

当前仓库已升级为 workspace 架构（0.6.0-alpha.1），提供：

1. 单一入口：hwhkit::run_and_serve + Application trait。
2. OOTB Production Defaults (Tier 1) — 见下方"Production Readiness (Tier 1)"。
3. Tier 2 production capabilities — JWT 链路、限流、幂等键、调度器、熔断器（按需 feature 启用）。
4. CLI：cargo hwhkit init / cargo hwhkit migrate / cargo hwhkit dev。

Production Readiness (Tier 1)

run_and_serve(app, bootstrap).await? 一行调用即获：

Production Readiness (Tier 2, opt-in)

CLI: cargo hwhkit dev

读取 hwhkit.toml（缺省自动启用 Postgres + Redis）后生成 target/.hwhkit-dev/docker-compose.yml，再 shell out 给 docker compose：

• cargo hwhkit dev up [--detach] — 启动依赖容器
• cargo hwhkit dev down — 停止并移除
• cargo hwhkit dev status — 查看容器状态
• cargo hwhkit dev generate --out docker-compose.dev.yml — 仅生成不启动

当前能力（按代码现状）

1. workspace 分层拆包：hwhkit-config、hwhkit-core、hwhkit-observability、hwhkit-buildinfo、hwhkit-scheduler、hwhkit-integration-*、cargo-hwhkit。
2. 配置分层加载：config/default.toml -> config/{env}.toml -> ENV(HWHKIT__) -> remote patch。
3. 严格校验：配置合法性 + feature/config 一致性校验。
4. 集成 provider：postgres/redis/mongodb/nats/qdrant/neo4j/s3 —— Handle 内承载真实连接池，并自动暴露 readiness 健康检查。
5. 模板初始化：minimal-api（0.6 起仅保留这一个模板；旧的 api-grpc / realtime-event 因 transport-grpc / transport-ws 特性已移除而下线）。

仓库结构

hwhkit-rs/
  crates/
    hwhkit/                         # facade：对外唯一依赖入口
    hwhkit-config/                  # 配置加载/合并/校验
    hwhkit-core/                    # bootstrap/Application/IntegrationProvider
    hwhkit-observability/           # logging/tracing 初始化
    hwhkit-buildinfo/               # 编译期 git/rustc 信息
    hwhkit-scheduler/               # 调度器（cron + 一次性任务）
    hwhkit-integration-postgres/
    hwhkit-integration-redis/
    hwhkit-integration-mongodb/
    hwhkit-integration-nats/
    hwhkit-integration-qdrant/
    hwhkit-integration-neo4j/
    hwhkit-integration-s3/
    cargo-hwhkit/                   # cargo hwhkit init
  templates/                        # 模板目录
  doc/

Feature 概览（crates/hwhkit/Cargo.toml）

默认开启（OOTB production defaults，按需 default-features = false 关闭）：

• health-endpoints
• metrics
• process-metrics
• version-endpoints
• middleware-bundle
• graceful-shutdown
• request-id

按需启用：

• jwt
• 集成：postgres、redis、mongodb、nats、qdrant、neo4j、s3
• 观测：otel（启用 OTLP gRPC 导出）；otel-sqlx / otel-redis / otel-reqwest（客户端探针）
• 数据库：migrations（postgres 子能力）
• Tier 2：rate-limit（需要 redis）、idempotency（需要 redis）、circuit-breaker、scheduler

Minimal preset

The default feature set is lean — health, metrics, request-id, graceful shutdown, version, middleware bundle, multi-tenant primitives. For the smallest possible binary set default-features = false and pull in only what you need:

hwhkit = { version = "0.6.0-alpha.1", default-features = false, features = [
  "graceful-shutdown",
] }

聚合：

• full

安装与使用

1) 作为库使用（推荐）

[dependencies]
async-trait = "0.1"
tokio = { version = "1", features = ["full"] }
# Default features already provide health/metrics/version/middleware/shutdown/request-id.
hwhkit = { version = "0.6.0-alpha.1", features = [
  "postgres",
  "redis",
  "mongodb",
  "nats",
  "qdrant",
  "neo4j",
  "s3",
  # Tier 2 (opt-in):
  # "jwt", "rate-limit", "idempotency", "circuit-breaker", "scheduler",
] }

2) 使用脚手架命令

本仓库内开发：

cargo run -p cargo-hwhkit -- init my-service --template minimal-api

安装为 cargo 子命令后：

cargo install --path crates/cargo-hwhkit
cargo hwhkit init my-service --template minimal-api

快速开始 (OOTB)

use async_trait::async_trait;
use axum::{routing::get, Router};
use hwhkit::prelude::*;
use hwhkit::config::AppConfig;

struct App;

#[async_trait]
impl Application for App {
    async fn build_router(&self, _ctx: AppContext, _cfg: &AppConfig) -> Result<Router> {
        Ok(Router::new().route("/hello", get(|| async { "hi" })))
    }
}

#[tokio::main]
async fn main() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Mounts /health, /health/ready, /metrics, /version, /info,
    // applies CORS/timeout/body-limit/compression/catch-panic,
    // adds request-id, listens for SIGTERM/SIGINT for graceful shutdown.
    run_and_serve(App, BootstrapConfig::default()).await
}

If you want to manage the listener yourself, use hwhkit::run to get a BuiltApplication and drive built.router() / built.shutdown() yourself.

配置示例（v2）

config/default.toml：

[server]
host = "0.0.0.0"
port = 3000

[observability]
service_name = "my-service"
environment = "dev"

[observability.logging]
level = "info"
format = "pretty"

[integrations.sql.postgres]
enabled = true
required = true
url = "postgres://postgres:postgres@127.0.0.1:5432/app"
max_connections = 20

[integrations.redis]
enabled = true
required = false
url = "redis://127.0.0.1:6379"

[integrations.mongodb]
enabled = false
required = false
url = "mongodb://127.0.0.1:27017"
database = "app"

[integrations.messaging.nats]
enabled = false
required = false
url = "nats://127.0.0.1:4222"

[integrations.vector.qdrant]
enabled = false
required = false
url = "http://127.0.0.1:6334"
api_key = ""

[integrations.neo4j]
enabled = false
required = false
url = "bolt://127.0.0.1:7687"
username = "neo4j"
password = "password"

质量状态

cargo build  --workspace --all-features
cargo test   --workspace --all-features
cargo clippy --workspace --all-features --all-targets -- -D warnings

文档

• 执行方案：doc/2026-02-09-05-execution-plan-confirmed.md
• 执行进度：doc/2026-02-09-06-execution-progress.md
• 架构路线：doc/2026-02-09-01-architecture-roadmap-v2.md
• Golden Path：doc/2026-02-09-02-golden-path-extreme-performance.md
• 协议网格：doc/2026-02-09-03-transport-and-protocol-mesh.md
• 结构方案：doc/2026-02-09-04-structure-options.md
• 项目指南：doc/guides/QUICK_START.md、doc/guides/CONTRIBUTING.md

当前边界说明

1. hwhkit-integration-* provider 骨架已就位，真实连接池 + readiness 已接入；驱动深度接入会随版本推进。
2. 0.6 周期发布前，hwhkit-transport 与 hwhkit-macros 这两个旧 crate 已删除（参见 MIGRATION.md）。

License

MIT OR Apache-2.0