Rust 基础设施组件库,采用 Workspace 多 Crate 架构,提供配置管理、加解密、日志、监控、平滑退出以及 MySQL/Redis/Pulsar 等中间件封装。
| 项目 | 值 |
|---|---|
| 版本 | v1.3.0 |
| 仓库 | https://github.com/rs-god/hera |
| 协议 | MIT |
| 作者 | daheige |
| 组件 | 定位 | 核心能力 |
|---|---|---|
config |
配置读取 | YAML 配置文件加载与反序列化 |
crypto |
加解密 | AES-128/192/256 CBC 模式加密,Base64 输出 |
logger |
日志 | 普通文本 / JSON 输出,支持 log key/value,可自定义时间格式 |
monitor |
监控 | 基于 autometrics 自动采集函数级 Prometheus 指标 |
shutdown |
平滑退出 | 监听系统信号,支持异步优雅关闭 |
xmysql |
MySQL | 基于 sqlx 的异步连接池 |
xredis |
Redis | 单节点 / 集群连接池,支持同步与异步 |
xpulsar |
Pulsar | 异步 Producer/Consumer 封装,支持 Token 认证 |
在 Cargo.toml 中通过 git + tag 引入指定 crate:
[dependencies]
crypto = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
logger = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
monitor = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
shutdown = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
config = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
xmysql = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
xredis = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }
xpulsar = { git = "https://github.com/rs-god/hera.git", tag = "v1.3.0" }如需使用
logger的 key/value 语法,请同时依赖log = { version = "0.4", features = ["kv"] }。
- Rust: 1.85 或更高版本
- Edition: 2024
- 部分组件需要额外运行环境:
xmysql:MySQL 服务xredis:Redis 单节点或集群xpulsar:Pulsar 服务monitor:可选 Prometheus 拉取端点
下面以 logger 为例,演示如何在业务项目中使用 hera 组件:
use log::info;
use logger::Logger;
fn main() {
Logger::new()
.with_caller_line()
.with_json()
.init();
info!(a = 1, b = "xxx"; "hello,world");
}运行:
RUST_LOG=info cargo run输出:
{"ts":"2026-07-18T14:25:16Z","level":"INFO","module":"my_app::main","caller":7,"msg":"hello,world","a":1,"b":"xxx"}功能点
- 读取 YAML 配置文件内容
- 支持反序列化为
serde_yaml::Value或自定义结构体 - 基于
ConfigTraittrait 抽象
使用示例
use config::{Config, ConfigTrait};
use serde::{Deserialize, Serialize};
#[derive(Debug, Deserialize, Serialize, Default)]
struct AppConfig {
app_debug: bool,
app_name: String,
app_port: i32,
}
let mut c = Config::new("config/app.yaml");
c.load().expect("read file failed");
// 方式1:读取为自定义结构体
let cfg: AppConfig = serde_yaml::from_str(c.content()).unwrap();
// 方式2:读取为 serde_yaml::Value
let val = c.sections();
let cfg: AppConfig = serde_yaml::from_value(val).unwrap();功能点
- 支持 AES-128、AES-192、AES-256 三种密钥长度
- CBC 模式 + PKCS7 填充
- 加密结果采用 Base64 编码
- 内置随机 key/iv 生成方法(16 进制字符串)
核心类型
Aes128Crypto— 16 字节密钥Aes192Crypto— 24 字节密钥Aes256Crypto— 32 字节密钥AesCrypto<T>— 泛型底层结构
使用示例
use crypto::Aes256Crypto;
let key = Aes256Crypto::generate_key(); // 32 位 16 进制字符串
let iv = Aes256Crypto::generate_iv(); // 16 位 16 进制字符串
let c = Aes256Crypto::new(&key, &iv);
let s = "hello world";
let encrypted = c.encrypt(s).unwrap(); // Base64 密文
let decrypted = c.decrypt(&encrypted).unwrap();
assert_eq!(s, decrypted);功能点
- 基于
env_logger与 crates.iologcrate 封装 - 支持标准输出(Stdout)
- 普通文本格式与 JSON 结构化格式可选
- 完整支持
log原生 key/value 语法:info!(key = value; "msg") - 可选
caller_line模式:日志中携带模块路径与代码行号 - 可选
with_json()模式:输出 JSON 格式日志 - 可选
with_time_format()自定义时间格式,默认%Y-%m-%dT%H:%M:%SZ - 可选
with_local_time()本地时间输出(默认 UTC 时间),普通文本与 JSON 格式均生效 - 自定义
target:标签可自动输出到 JSON - 日志级别通过环境变量
RUST_LOG控制,优先级:error > warn > info > debug > trace
使用示例
use log::info;
use logger::Logger;
// JSON 格式,携带 caller 行号
Logger::new()
.with_caller_line()
.with_json()
.init();
info!(a = 1, b = "xxx"; "hello,world");输出:
{"ts":"2026-07-18T14:25:16Z","level":"INFO","module":"my_app::main","caller":7,"msg":"hello,world","a":1,"b":"xxx"}自定义时间格式:
Logger::new()
.with_json()
.with_time_format("%Y-%m-%d %H:%M:%S")
.init();本地时间输出(默认 UTC 时间):
Logger::new()
.with_json()
.with_local_time()
.with_time_format("%Y-%m-%d %H:%M:%S")
.init();普通文本格式(带行号):
Logger::new().with_caller_line().init();
info!("hello,world");
// [2026-07-18T14:25:16Z INFO my_app::main:7] hello,world配合环境变量使用:
RUST_LOG=info cargo run功能点
- 基于
autometrics自动采集函数级指标(调用次数、延迟、成功率) - 内置 SLO(Service Level Objective)定义:成功率 P99.9、延迟 P99 < 1000ms
- 提供
/metricsPrometheus 拉取端点 - 提供
/check健康检查端点 - 集成
axumHTTP 服务与平滑退出
核心 API
prometheus_init(port)— 启动独立 metrics HTTP 服务API_SLO— 预定义 SLO 常量,配合#[autometrics(objective = API_SLO)]使用
使用示例
use monitor::metrics::{prometheus_init, API_SLO};
use autometrics::autometrics;
#[tokio::main]
async fn main() {
// 启动 metrics 服务,监听 8090 端口
prometheus_init(8090).await;
}
#[autometrics(objective = API_SLO)]
pub async fn home() -> &'static str {
"Hello, home!"
}完整用法参考 crates/monitor/examples/metrics_basic.rs。
功能点
- 监听系统退出信号(Ctrl+C / SIGTERM)
- 信号触发后等待指定时长再退出,便于执行清理逻辑
- 跨平台兼容(Unix/Windows)
使用示例
use shutdown::graceful_shutdown;
use std::time::Duration;
#[tokio::main]
async fn main() {
// 启动你的服务...
// 等待退出信号,收到后等待 5 秒再退出
graceful_shutdown(Duration::from_secs(5)).await;
}与 axum 集成:
axum::serve(listener, router)
.with_graceful_shutdown(graceful_shutdown(Duration::from_secs(5)))
.await
.unwrap();功能点
- 基于
sqlx的异步 MySQL 连接池 - 可配置最大/最小连接数、最大生命周期、空闲超时、连接超时
- 返回
sqlx::MySqlPool,可直接用于sqlx查询 API
配置项(默认值)
max_connections: 100min_connections: 10max_lifetime: 1800sidle_timeout: 600sconnect_timeout: 10s
使用示例
use xmysql::MysqlConf;
let dsn = "mysql://root:root123456@localhost/test";
let pool = MysqlConf::new(dsn)
.with_max_connections(10)
.init_pool()
.await
.unwrap();
// 使用 sqlx API 查询
let row: (i64,) = sqlx::query_as("select ?")
.bind(120i64)
.fetch_one(&pool)
.await?;功能点
- 基于
pulsarcrate 的异步客户端封装 - 支持 Token 认证
- 提供 Producer / Consumer Builder 快捷创建
- 内置
Message结构体,基于serde_json序列化/反序列化
使用示例
use xpulsar::{PulsarConf, Message};
use pulsar::{producer, proto};
let conf = PulsarConf::new("pulsar://127.0.0.1:6650")
.with_token("your-token"); // 可选
let builder = conf.pulsar_builder();
let pulsar_obj = conf.pulsar_obj(builder).await.unwrap();
// 创建生产者
let mut producer = pulsar_obj
.producer()
.with_topic("my-topic")
.with_name("my_producer")
.build()
.await?;
producer.send_non_blocking(Message { data: "hello".into() }).await?;
// 创建消费者
let mut consumer = pulsar_obj
.consumer()
.with_topic("my-topic")
.with_consumer_name("group-1")
.with_subscription_type(SubType::Exclusive)
.with_subscription("my_sub")
.build()
.await?;功能点
- 支持单节点 Redis(
redis::Client)和 Redis Cluster(ClusterClient) - 基于
r2d2的连接池管理 - 支持同步与异步操作
- Builder 风格配置
配置项(默认值)
max_size: 20min_idle: 3max_lifetime: 1800sidle_timeout: 300sconnection_timeout: 10s
使用示例
use xredis::RedisConf;
use redis::Commands;
// 单节点 + 连接池
let dsn = "redis://:@127.0.0.1:6379/0";
let pool = RedisConf::builder()
.with_dsn(dsn)
.init_pool();
let mut conn = pool.get().unwrap();
let _: () = conn.set("my_user", "daheige").unwrap();
// 集群 + 连接池
let nodes = vec![
"redis://:@127.0.0.1:6380/0",
"redis://:@127.0.0.1:6381/0",
// ...
];
let pool = RedisConf::builder()
.with_cluster_nodes(nodes)
.init_cluster_pool();
// 异步操作
use redis::AsyncCommands;
let client = RedisConf::builder().with_dsn(dsn).client()?;
let mut con = client.get_multiplexed_async_connection().await?;
let _: () = con.set("name", "hello").await?;
let name: String = con.get("name").await?;每个 crate 的源码目录下都有独立的 readme.md,包含更详细的 API 说明与示例:
- config — YAML 配置读取
- crypto — AES 加解密
- logger — 日志初始化(JSON / 普通文本)
- monitor — Prometheus 监控指标
- shutdown — 平滑退出
- xmysql — MySQL 连接池
- xpulsar — Pulsar 消息队列
- xredis — Redis 客户端/集群
本项目采用 MIT 协议开源。