loveyu-kit
loveyu-kit 是面向 Axum 项目的可组合工具库,用于统一 API 响应、错误处理、
Validify 请求校验、分页、请求级结构化诊断日志、可扩展连接生命周期管理和可选的企业微信消息推送。
最低支持 Rust 1.94。CI 会同时在该最低版本和最新稳定版上运行全特性测试,避免依赖升级 无意中抬高工具链要求。
库只提供跨项目可复用的机制,不内置业务项目的请求头名称、角色、资源或审计规则。 主体 ID 来自哪个可信请求头、哪些操作需要日志、哪些字段可以记录,均由应用显式配置。
库按能力域组织,可以继续增加互不耦合的集成模块:
src/
├── lib.rs
├── prelude.rs
├── connection/
│ ├── mod.rs
│ ├── error.rs
│ ├── elasticsearch.rs
│ ├── etcd.rs
│ ├── kafka.rs
│ ├── mysql.rs
│ ├── mqtt.rs
│ ├── postgres.rs
│ └── redis.rs
├── messaging/
│ ├── error.rs
│ └── wecom/
│ ├── client.rs
│ └── message/
│ ├── media.rs
│ ├── news.rs
│ ├── template_card.rs
│ └── text.rs
├── observability/
│ ├── mod.rs
│ ├── context.rs
│ ├── diagnostic.rs
│ ├── identity.rs
│ ├── json_format.rs
│ ├── panic_recovery.rs
│ ├── request_log.rs
│ ├── sql_execution.rs
│ └── tracing_init.rs
└── web/
├── mod.rs
├── extract/
│ ├── mod.rs
│ └── validated.rs
├── pagination.rs
└── response/
└── mod.rs
功能开关
默认只启用核心的 response,避免未使用校验、multipart 和日志能力的项目编译额外依赖。
需要完整 Web API 功能以及常用的 MySQL、PostgreSQL、Redis 连接器时显式启用 full:
[]
= { = "0.2.0", = ["full"] }
| Feature | 能力 |
|---|---|
response |
统一成功响应、错误响应和结果类型 |
validation |
JSON、Query、Path、Form URL 的修改校验提取器 |
multipart |
multipart 普通字段和文件字段的修改校验提取器 |
pagination |
与数据库无关的分页请求和值对象 |
logging |
请求上下文、可信主体传播、结构化诊断、SQL 执行记录、单请求日志和 tracing JSON 初始化 |
connection |
通用连接生命周期 trait、connect 和强类型连接包装 |
connection-mysql |
内置 MySQL 连接池连接器 |
connection-postgres |
内置 PostgreSQL 连接池连接器 |
connection-redis |
内置 Redis ConnectionManager 连接器 |
connection-kafka |
内置 Kafka 异步生产者和流式消费者连接器 |
connection-etcd |
内置 etcd v3 客户端连接器 |
connection-mqtt |
内置 MQTT 异步客户端及事件循环连接器 |
connection-elasticsearch |
内置 Elasticsearch 官方 HTTP 客户端连接器 |
connection-es |
connection-elasticsearch 的简写别名 |
connections |
启用全部内置连接器 |
full |
启用全部 Web API 功能及 MySQL、PostgreSQL、Redis 连接器 |
wecom |
企业微信消息推送、媒体上传和强类型消息,需要显式启用 |
full 不包含 connection-kafka、connection-etcd、connection-mqtt、
connection-elasticsearch 和 wecom。这些依赖体积较大或具有更明确的部署环境要求,
需要时应单独追加对应 Feature;希望一次启用全部连接器时仍可使用 connections。
也可以关闭默认功能后按需组合:
[]
= {
version = "0.2.0",
= false,
= ["response", "logging"]
}
可扩展连接管理
安装与生命周期
只启用项目实际使用的连接器,可以减少无关依赖和编译时间:
[]
= {
version = "0.2.0",
= false,
= [
"connection-mysql",
"connection-postgres",
"connection-redis",
"connection-kafka",
"connection-etcd",
"connection-mqtt",
"connection-elasticsearch",
]
}
内置连接器不会根据 URL 返回运行时枚举,而是通过关联类型保留准确的底层客户端类型。 所有连接器遵循相同流程:
connect(connector)检查连接器是否启用;- 未启用时输出警告并返回未初始化的强类型句柄,不会解析配置或访问网络;
- 启用时建立连接并自动执行首次健康检查;
- 使用
connection()获取底层客户端,未启用时会返回明确错误; - 使用
is_connected()判断底层客户端是否已经初始化; - 使用
verify()再次检查连接,未启用时返回ManagedConnectionError::Unavailable; - 应用停机时使用
close()显式关闭;未启用时没有资源需要释放,因此幂等返回Ok(())。
use ;
# async
同一项目可以创建多个同类型连接,通过 with_name() 设置不同的日志名称。连接地址和认证配置
不会出现在连接器的 Debug 输出中。
连接器未启用时,connect() 仍返回相同的 ManagedConnection<C> 强类型句柄,但不会创建底层
客户端。此时各生命周期方法遵循以下约定:
| 操作 | 未启用时的结果 | 原因 |
|---|---|---|
is_connected() |
false |
用于无错误地检查初始化状态 |
connection() |
Err(ConnectionUnavailable) |
不存在可供业务操作的底层客户端 |
into_inner() |
Err(ConnectionUnavailable) |
不存在可移交所有权的底层客户端 |
verify() |
Err(ManagedConnectionError::Unavailable) |
未初始化连接不能通过健康检查 |
close() |
Ok(()) |
未分配资源,关闭操作保持幂等 |
verify() 对已经初始化的连接会把连接器自身错误保存在
ManagedConnectionError::Connector(C::Error) 中。自定义连接器不需要让自己的错误类型实现
From<ConnectionUnavailable>,只需继续在 Verify trait 中返回自身的 C::Error;未启用状态由
ManagedConnection 统一包装。这项约定让扩展连接器能够区分“未启用”和“健康检查失败”。
| 连接器 | 底层连接类型 | 首次校验 | 关闭行为 |
|---|---|---|---|
MySqlConnector |
MySqlPool |
执行 SELECT 1 |
等待连接池关闭 |
PostgresConnector |
PgPool |
执行 SELECT 1 |
等待连接池关闭 |
RedisConnector |
RedisConnectionManager |
执行 PING |
释放连接管理器 |
KafkaProducerConnector |
KafkaProducer |
获取集群元数据 | flush 后释放生产者 |
KafkaConsumerConnector |
KafkaConsumer |
获取集群元数据 | 取消订阅并释放消费者 |
EtcdConnector |
EtcdClient |
查询成员状态 | 释放 gRPC 客户端 |
MqttConnector |
MqttConnection |
检查 CONNACK 和事件任务 | 发送 DISCONNECT 并停止事件任务 |
ElasticsearchConnector |
ElasticsearchClient |
调用 Ping API | 释放 HTTP 客户端 |
MySQL 和 PostgreSQL 默认使用 PoolOptions::DEFAULT:
min_connections = 1
max_connections = 20
acquire_timeout = 5 秒
不调用 with_pool_options() 就会使用这组参数;需要覆盖时再调用
with_pool_options(PoolOptions::new(...))。配置值来自文件或环境变量时,优先使用
PoolOptions::try_new(...),可以在启动期以 Result 返回错误,不必等到连接时才发现非法参数。
MySQL
启用 feature:connection-mysql。URL 格式为
mysql://用户名:密码@主机:端口/数据库名,无密码时可以省略 :密码。
use ;
# async
MySqlConnector::new() 默认会把每条新建连接的会话时区设置为北京时间 +08:00,该值通过
DEFAULT_MYSQL_TIME_ZONE 公开。with_time_zone("") 或只传空白字符时仍使用北京时间;可以用
with_time_zone("其他时区") 覆盖,或用 without_time_zone() 完全沿用 MySQL 服务端时区。
连接器还会默认设置以下严格模式:
ONLY_FULL_GROUP_BY,STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION
该值也通过 DEFAULT_MYSQL_SQL_MODE 公开。调用 with_sql_mode("") 或只传空白字符时仍会使用
默认值;调用 with_sql_mode("自定义模式") 可以覆盖它。如果希望完全沿用 MySQL 服务端配置,
应显式调用 without_sql_mode()。
PostgreSQL
启用 feature:connection-postgres。URL 支持 postgres:// 和 postgresql://:
use ;
# async
Redis
启用 feature:connection-redis。Redis URL 可以不带认证、只带密码或同时携带用户名和密码:
redis://127.0.0.1:6379/0
redis://:password@127.0.0.1:6379/0
redis://username:password@127.0.0.1:6379/0
use ;
# async
RedisConnector 默认把建连超时和命令响应超时都设为 5 秒,避免网络故障时无限等待;需要调整
重连退避、并发数或超时时,可以通过 with_manager_config(RedisConnectionManagerConfig) 注入
Redis 原生配置。显式配置为零的超时会在联网前返回配置错误。
Kafka 生产者
启用 feature:connection-kafka。brokers 接收逗号分隔的 Kafka 节点列表;
with_property() 会直接传递当前 librdkafka 构建支持的原生配置:
use Duration;
use ;
# async
Kafka 消费者
Kafka 消费者与生产者使用同一个 connection-kafka feature。创建消费者时必须提供消费组 ID:
use Duration;
use ;
# async
etcd
启用 feature:connection-etcd。支持一个或多个 HTTP/HTTPS endpoint,账号密码、请求超时、
连接超时和 TLS 等能力通过原生 EtcdConnectOptions 配置:
use Duration;
use ;
# async
未调用 with_options() 时同样会使用 5 秒建连超时和 5 秒请求超时。节点列表为空或包含空地址
会在访问网络前失败;Debug 只显示节点数量,不输出可能意外包含凭据的完整地址。
MQTT
启用 feature:connection-mqtt。可以使用 URL 快速创建,也可以使用 MqttOptions 配置
keep-alive、TLS、遗嘱消息等原生能力。
URL 方式必须提供 client_id 查询参数,当前构建支持 mqtt://、mqtts://、tcp:// 和
ssl://:
use Duration;
use ;
# async
MqttOptions 方式:
use Duration;
use ;
# async
工具库会持续轮询 MQTT 事件循环、维护重连状态并等待首次 CONNACK。首次握手默认最多等待
10 秒,关闭默认最多等待 5 秒,事件通道容量和两个超时都不能为零。调用 close() 时会发送
DISCONNECT;即使调用方忘记关闭,丢弃连接也会终止后台事件任务。
当前 rumqttc 0.25.1 的 Rustls 可选依赖仍锁定在存在多个 2026 年证书校验漏洞的
rustls-webpki 0.102,因此工具库使用其原生 TLS 后端,避开受影响代码路径。在 Linux 上这会使用
系统 OpenSSL,在 macOS 和 Windows 上使用系统 TLS 实现;部署镜像需要具备对应的系统 TLS 库。
Elasticsearch
启用 connection-elasticsearch 或简写 feature connection-es。支持 HTTP/HTTPS 和官方客户端的
Basic、Bearer、API Key、编码后的 API Key 等认证方式:
use ;
use Duration;
# async
全局 HTTP 请求超时默认为 10 秒。节点 URL 不允许内嵌用户名或密码,应统一通过
with_credentials() 提供,避免 URL 在错误链或代理诊断中泄漏凭据。
其他认证形式:
use ElasticsearchCredentials;
let bearer = Bearer;
let api_key = ApiKey;
let encoded_api_key = EncodedApiKey;
# drop;
当前官方 Elasticsearch Rust 客户端仍为 alpha 版本,升级依赖前应检查其变更说明。
自定义连接器
如果需要支持其他数据库、消息队列或中间件,只需为自己的配置类型实现连接、校验和关闭三个 生命周期 trait:
use io;
use ;
;
# async
ConnectionSpec 负责声明强类型连接、错误、名称及开关;Connector 会自动为同时实现
Connect + Verify + Close 的类型实现,使用者无需手动实现组合 trait。
统一响应与错误
启用连接和响应相关 feature 后,ApiError 为常用连接错误提供默认的安全转换:
ConnectionUnavailable转为服务繁忙错误;ManagedConnectionError<E>转为依赖服务健康检查错误;- 内置连接器统一使用的
ConnectionError根据错误来源转换为数据库、Redis 或依赖服务错误; sqlx::Error::RowNotFound转为数据不存在错误;- SQLx 唯一索引或主键冲突转为唯一索引冲突错误;
- SQLx 连接池超时转为服务繁忙错误,其他 SQLx 错误转为数据库错误;
redis::RedisError转为 Redis 错误;rdkafka::error::KafkaError以及异步生产发送返回的(KafkaError, OwnedMessage)转为 Kafka 操作错误,失败消息载荷不会进入日志;etcd_client::Error转为 etcd 操作错误;rumqttc::ClientError、rumqttc::ConnectionError、rumqttc::OptionError转为 MQTT 错误;elasticsearch::Error转为 Elasticsearch 操作错误。
真实错误只进入服务端诊断,客户端只收到稳定的中文提示。因此返回 AppResult<T> 的处理器可以
直接对连接初始化、健康检查以及底层客户端操作使用 ?;需要自定义业务提示时,仍可以显式调用
map_err() 覆盖默认转换。对应原生错误转换只在启用该连接器 Feature 时参与编译,不会额外引入依赖。
use ;
# async
use *;
async
async
ApiResponse::new() 的默认成功消息使用静态字符串,不发生堆分配;map() 可以在保留业务码和
消息的同时转换数据,into_data() 可以直接取回数据。自定义业务码使用
ApiError::new(code, message)。
每个错误构造方法只接收客户端提示 msg,业务码由方法固定:
| 方法 | 业务码 | 建议提示 |
|---|---|---|
err_request_external_service |
100000 | 服务请求失败,请稍后重试 |
err_bad_request |
400000 | 请求错误 |
err_invalid_param |
400001 | 请求参数错误 |
err_token_client_invalid |
400002 | 登陆凭证无效 |
err_token_server_invalid |
400003 | 登陆凭证生成失败 |
err_unauthorized |
401000 | 请先登录 |
err_forbidden_auth |
403000 | 权限不足 |
err_user_disabled |
403001 | 用户不存在或已被禁用 |
err_not_found |
404000 | 数据不存在 |
err_data_exists |
409000 | 数据已存在 |
err_unique_index_conflict |
409001 | 数据已存在 |
err_version_conflict |
409002 | 当前数据并非最新数据 |
err_foreign_key_conflict |
409003 | 关联数据冲突 |
err_constraint_conflict |
409004 | 数据约束冲突 |
err_server_busy |
500000 | 服务繁忙,请稍后重试 |
err_database |
500001 | 服务异常,请稍后重试 |
err_redis |
500002 | 服务异常,请稍后重试 |
err_encrypt |
600000 | 数据处理失败 |
err_other |
999999 | 操作失败,请稍后重试 |
错误的内部原因、来源链和诊断上下文不会返回给客户端,只会交给日志中间件。内部错误文本、
来源链深度、上下文字段数量和值长度、诊断数量和嵌套 JSON 都有硬上限;格式化超长错误时使用
限长写入器,不会先分配一个无限大的临时字符串。
错误默认使用 200 OK + 业务码;需要语义化 HTTP 状态时可以显式设置:
use StatusCode;
use *;
let error = err_unauthorized
.with_http_status;
AppOk、AppError 和 AppResult 是兼容别名,可以用于迁移已有项目。
请求修改与校验
use Json;
use Deserialize;
use *;
use ;
async : ,
)
所有参数提取或 Validify 校验失败都会通过 ApiError::err_invalid_param(message) 返回,
业务码固定为 400001;校验注解中的自定义 message 仍会作为客户端提示。
可用提取器:
ValidatedJson<T>ValidatedQuery<T>ValidatedPath<T>ValidatedFormUrl<T>ValidatedFormData<T>
所有包装器都支持 Deref、DerefMut、AsRef 和 into_inner():handler 可以继续使用模式匹配,
也可以在需要传递所有权时直接调用 validated.into_inner(),无需依赖元组字段 .0。
单请求日志
应用启动时初始化 JSON 日志:
use *;
默认初始化器同步写入 stdout,适合测试和低流量命令行工具。生产 HTTP 服务应使用内置的
JsonTracingBuilder,把格式化后的日志交给独立线程写出:
use *;
默认队列容量为 8192 行,默认 DropAndCount,保证日志磁盘变慢时不阻塞请求线程;
JsonTracingGuard::dropped_lines() 可接入监控。对绝不能主动丢弃的低流量任务可改用
LogOverflowPolicy::Block,但队列满时会把背压传到产生日志的线程。guard 必须保持到应用退出,
释放时后台线程才会刷新剩余日志并退出。仍需自定义 MakeWriter 的应用可以继续使用
init_json_tracing_with_writer。
如果应用需要自行组装 Subscriber,应使用工具库提供的格式化器,才能保留嵌套对象结构:
use StructuredJsonFormatter;
use JsonFields;
let subscriber = fmt
.fmt_fields
.event_format
.finish;
将请求日志安装到已经添加路由的 Router:
use ;
use *;
let app = new
.route
.with_request_logging;
with_request_logging() 默认也会捕获 handler 或被该层包裹的 middleware 中的 panic:客户端收到
HTTP 500 和统一响应 {"code":500000,"msg":"系统内部错误"},panic 的真实内容只会写入
该请求最终的 ERROR 日志,不会泄露给客户端。
可以修改 panic 响应配置:
use StatusCode;
use *;
let config = new.with_panic_recovery_config;
let app = app.with_request_logging_config;
如果项目希望 panic 继续向外传播,可以使用
RequestLoggingConfig::new().without_panic_recovery() 关闭恢复。只有使用 Rust 默认的
panic = "unwind" 策略时才能捕获 panic;panic = "abort" 会直接终止进程。Rust 的全局
panic hook 仍可能额外向标准错误输出诊断信息,工具库不会擅自修改进程级 hook。
应在添加路由和业务 middleware 之后调用 with_request_logging(),让恢复层包裹完整的业务链路。
handler、service 和 repository 只向请求上下文收集信息,不逐层调用 println! 或为同一请求
重复发出 tracing 事件:
use *;
async
audit 模块随 logging feature 开启,提供项目无关的快捷接口:
audit::command(name, description, resource):记录会改变状态或产生外部副作用的操作;audit::query(name, description, resource):记录只读查询;audit::target(kind, id):记录实际影响的资源;audit::target_resource(target):记录带安全属性的完整资源目标;audit::field_change(field, before, after):以字符串形式记录已提交的前后值;audit::change(field, before, after):直接保留可转换为 JSON 的原始类型;audit::attempted_change/audit::json_attempted_change:记录尚未确认提交的尝试变化;audit::json_field_change(field, before, after):保留布尔值、数字、数组和对象等 JSON 类型记录已提交的前后值;audit::diagnostic/audit::failure/audit::sql_error:追加失败诊断。
command 和 query 接受静态字符串,常见的字面量调用不会分配三个业务描述字符串;确实需要
运行时字符串时使用 command_owned 或 query_owned。
json_field_change 返回 Result<bool, serde_json::Error>。Ok(true) 表示已写入当前
请求上下文,Ok(false) 表示当前没有安装完整请求日志,Err 表示值无法
序列化。公共工具库不会静默吞掉序列化错误,应用可以根据自身日志策略处理它。
这些接口在当前请求上下文不存在时不会导致业务失败。
对于需要记录主体、目标属性、未提交变化或诊断信息的复杂场景,仍可以直接使用
RequestLogContext、RequestSubject、ResourceTarget 和 FieldChange 等底层类型。
命中记录策略的请求会在结束时统一输出一条日志。默认不记录通用请求头,也不会记录查询字符串;
X-Request-Id 仍作为链路关联使用的独立 request_id 字段处理。请求没有合法 ID 时会生成 UUID v7,
并通过同名响应头返回。
请求方法、路由、路径、URI、请求 ID、响应状态、handler 耗时和请求上下文都直接位于 JSON 日志的
fields 对象中,不会额外创建或输出请求 span。
request_context、headers 和 error 会输出为真正的嵌套 JSON 对象,而不是需要
再次解析的 JSON 字符串。
一次请求的聚合信息包括:
subject:谁发起了请求;operation:执行的是查询还是命令,以及稳定操作名;targets:影响了哪些资源;changes/attempted_changes:已提交变化和失败前尝试的变化;diagnostics:SQL、缓存、外部服务或内部失败;outcome、业务错误、HTTP 状态、耗时和请求 ID。
这些内容由最外层中间件在请求结束时合并为一行 JSON。普通应用日志仍可使用 tracing 独立输出;
但属于单次请求结果的业务步骤和 SQL 错误应使用上述上下文接口,否则任何日志库都无法把已经独立
写出的多行事件重新可靠地变成一行。
默认容量保护为:32 个自定义字段、32 个目标、各 32 个已提交/尝试变化、16 条诊断、单值
16 KiB、集合 64 项、嵌套 8 层、请求头单值 2 KiB、URI 4 KiB。超出的内容会被截断或丢弃,
并在 request_context.truncation 中记录计数。可以集中调整:
let limits = new
.max_fields
.max_value_bytes
.max_diagnostics;
let config = new.with_limits;
配置来自外部时,可以使用对应的 try_max_fields、try_max_value_bytes、
try_max_diagnostics 等 try_ 方法,把非法值转换成 RequestLoggingLimitsError,避免启动期 panic。
上下文的 JSON 大小检查使用无分配计数写入器;JSON 字段和诊断参数也会在序列化
过程中立即停止于字节上限,不会先构造无界的 serde_json::Value。上下文满载后不再执行
无意义的 JSON 序列化。
Tokio 的 task-local 不会自动穿过普通 tokio::spawn。后台子任务需要继续追加当前请求信息时,
应使用 RequestLogContext::spawn_current(future);它在没有请求上下文时也能正常创建任务。
可信主体
工具库没有默认主体请求头。网关完成认证、移除外部伪造值并写入主体 ID 后,应用可以显式配置:
use HeaderName;
use *;
let config = new
.trusted_subject_header
.trusted_subject_kind;
let app = app.with_request_logging_config;
async
不需要身份的接口无需提取 TrustedSubject;需要身份的接口在主体缺失时会返回统一未认证错误。
仅在应用能够证明该请求头来自可信边界时配置此功能。
SQL 执行链路与错误映射
同时启用 logging 和 connection-mysql 或 connection-postgres 后,可以直接在 SQLx 查询上
声明日志策略。显式日志策略从 SQLx 实际执行时发出的 sqlx::query tracing 事件中取得 SQL 模板、
数据库执行耗时、影响行数和返回行数;连接池默认失败策略直接截取 SQLx Execute::sql() 最终交给
驱动的同一条 SQL 模板,成功路径不需要逐次处理 tracing 事件。两种方式都不需要把 SQL 常量再传一遍。
扩展返回 Result<T, ApiError>,因此返回 AppResult<T> 的 handler 可以直接使用 ?。
新增、修改和删除通常使用 execute:
use *;
const UPDATE_USER: &str = "UPDATE users SET nickname = ? WHERE id = ?";
# async
通过 MySqlConnector 或 PostgresConnector 创建的连接池默认启用失败记录,因此普通查询不需要
手动调用 .logger_err()。RowNotFound 会自动映射为 err_not_found,唯一索引冲突会自动映射为
err_unique_index_conflict:
use *;
const SELECT_USER: &str = "SELECT id, nickname FROM users WHERE id = ?";
# async
默认策略与显式策略如下:
| 策略 | SQL 成功 | SQL 失败 |
|---|---|---|
| 本库连接池默认策略 | 不记录 | 记录 SQL、耗时、可用行数和错误详情 |
.logger_sql("user.detail") |
记录 SQL、耗时和行数 | 记录 SQL、耗时、行数和错误详情 |
.logger_err() |
不记录 | 记录 SQL、耗时、行数和错误详情 |
默认失败记录使用查询名称 sqlx.query。需要给仅失败记录设置稳定名称,或使用业务自行创建的原始
SQLx 连接池时,仍可显式调用 .logger_err().query_name("user.detail")。显式
.logger_sql(...) 会接管默认策略:成功时增加记录,失败时仍然只产生一条记录。
默认策略适用于把本库返回的 &MySqlPool 或 &PgPool 直接作为 SQLx Executor。通过
.inner() 取得原始 SQLx 连接池,或在原始连接、事务上执行时,不经过连接池包装器;这类调用需要
显式使用 .logger_err() 或 .logger_sql(...)。
无论是否启用日志,SQLx 错误都会自动按结构化错误类别转换为 ApiError。需要覆盖所有自动映射结果时
使用 .api_err(ApiError::err_database("查询失败"));需要按类别或约束分别覆盖时使用
.api_err_for(SqlErrorClass, ApiError) 或 .api_err_for_constraint(...)。not_found、
unique_conflict、foreign_key_conflict 和 check_conflict 是常用分类的便捷方法。
直接使用 .api_err(...) 时会自动记录失败,不需要再追加 .logger_err()。
四种 SQLx 执行方式的语义保持不变:
| SQLx 方法 | 返回值 | 无数据时 | 链路记录 |
|---|---|---|---|
execute() |
QueryResult |
成功,rows_affected() 可能为 0 |
rows_affected |
fetch_all() |
Vec<T> |
成功,返回空数组 | rows_returned |
fetch_optional() |
Option<T> |
成功,返回 None |
rows_returned 为 0 或 1 |
fetch_one() |
T |
返回 RowNotFound |
成功时 rows_returned 为 1 |
fetch_optional() 返回 None、execute() 影响 0 行都是 SQLx 成功结果。只有显式配置
.not_found_if_none("数据不存在") 或 .not_found_if_zero("数据不存在") 时,才会转为
ApiError。fetch_one() 和 fetch_optional() 只返回第一行,不会校验结果是否严格只有一行;
查询应使用主键、唯一索引或显式 LIMIT 1。
这里的“实际执行 SQL”是 SQLx 交给数据库驱动的预编译语句模板,仍然包含 ? 或 $1 等
占位符。SQLx 不提供安全、通用的反向参数展开能力,工具库不会伪造一条把参数拼接进去的 SQL。
需要排障的非敏感参数只能通过 with_safe_parameter 或 with_safe_json_parameter 明确加入;
密码、令牌、身份证、人脸数据、完整手机号等敏感值不得写入。
单次请求默认最多保留 16 条 SQL 记录,可以通过
RequestLoggingLimits::max_sql_executions() 调整;超出数量会写入 dropped_sql_executions。
成功 SQL 需要路由安装 with_request_logging() 才能进入请求上下文;轻量
with_access_logging() 不创建上下文,因此只能从最终返回的 ApiError 中记录失败诊断。
应用自行组装 tracing Subscriber 时,需要安装
SqlxQueryLayer::new().with_capture_filter();使用本库的 init_json_tracing*
时会自动安装。
事务中的 rows_affected 是 SQLx 在语句执行后报告的数值,不代表事务已经提交。事务后续回滚时,
该行数不应被解读为持久化成功的数据量。
对于不使用 SQLx 扩展的数据库客户端,原有 map_sql_error 和
RequestLogContext::record_sql_error 仍可用于仅失败诊断。
请求日志与业务审计的边界
请求聚合日志用于链路排障,loveyu-kit 不自动向业务数据库写审计表。需要长期可靠追溯的重要
管理操作,应由应用在同一个数据库事务中写入自己的审计记录,内容通常包括主体、目标、操作、
前后值和结果。已经由领域业务表完整表达的事实不应再机械复制到通用操作表。
这种取舍属于业务一致性设计,通用工具库只提供 RequestSubject、ResourceTarget 和
FieldChange 等可复用值对象,不替项目决定哪些操作必须永久保存。
如果接口只需要访问日志,不需要在 handler 或 service 中追加链路字段,可以使用轻量模式:
let app = new
.route
.with_access_logging;
with_access_logging() 与完整模式使用相同的过滤、采样、慢请求、错误和 panic 恢复策略,但不会
创建 RequestLogContext,也不会将其写入请求或响应扩展。完整模式默认只注入请求扩展;需要通过
Extension<RequestLogContext> 收集业务字段的路由应继续使用 with_request_logging()。
测试或外层 middleware 确实需要从响应读取最终上下文时,显式配置
.expose_context_in_response(true)。
通过白名单指定允许记录的请求头:
use ;
use *;
let config = new
.include_headers
.include_header;
let app = app.with_request_logging_config;
轻量模式同样支持自定义配置:app.with_access_logging_config(config)。
控制请求日志数量:
use Duration;
use *;
let config = new
// 精确匹配实际路径或 Axum 路由模板,成功响应不记录。
.skip_success_path
.skip_success_path
// 匹配一组路径前缀,查询字符串不参与判断。
.skip_success_prefix
// 达到 400ms 的请求始终记录,成功的慢请求使用 WARN 级别。
.slow_request_threshold
// 记录全部普通成功请求;必须位于 0.0 到 1.0 之间。
.success_sample_rate
// 错误忽略成功路径过滤和采样策略,始终记录。
.always_log_errors
// 可选:普通成功查询和预期查询错误静默;系统错误仍记录。
.quiet_queries
// quiet_queries 启用时仍记录慢查询;默认就是 true。
.log_slow_queries
// 可选:命令操作绕过路径过滤和采样,成功或失败都记录。
.always_log_commands;
let app = app.with_request_logging_config;
以上就是 RequestLoggingConfig::new() 使用的默认策略:跳过 /health、/metrics 和
/static/ 的成功日志,将 400ms 及以上请求视为慢请求,记录全部普通成功请求,并始终记录错误。
quiet_queries 和 always_log_commands 默认关闭,应用按自身日志政策显式启用。没有设置
RequestOperation 时,GET、HEAD、OPTIONS 被识别为查询,其余 HTTP 方法被识别为命令。
日志判断顺序为:查询静默、命令/慢请求/错误必记、成功路径过滤、成功采样。ApiError、HTTP
4xx/5xx 和 panic 都属于错误;如果设置 always_log_errors(false),错误也会经过路径过滤
和采样判断。采样使用工具库内部的线程本地序列,避免逐请求原子竞争,也不需要额外随机数依赖。
路径过滤和采样会跳过上下文序列化和日志事件构造;完整模式仍要注入共享上下文、测量耗时并
保留 panic 恢复。不需要业务链路字段的高频接口可使用 with_access_logging() 降低固定成本;
完全不需要请求日志的接口应放在没有安装日志层的 Router 中:
let quiet_routes = new
.route
.route;
let business_routes = new
.route
.with_request_logging;
let app = new.merge.merge;
Authorization、Cookie、Set-Cookie 和 X-Api-Key 即使加入请求头白名单也会默认输出
[已脱敏]。密码、原始 Token 和个人敏感信息同样不得加入请求上下文;项目还可以通过
redact_header 扩充请求头脱敏名单。
仓库提供可重复执行的日志固定成本基准:
SQL_LOG_BENCH_DATABASE_URL='postgresql://用户@localhost/基准库' \
基准分别测量无日志层、完整上下文但事件被过滤、轻量访问日志但事件被过滤三条请求路径, 以及字符串和小型 JSON 上下文写入。SQL 基准同时区分无请求上下文快速路径和完整请求上下文, 覆盖正常查询、数据库错误与 256 行流式读取。数据库组按顺序运行时可能出现连接调度和系统负载漂移, 因此图表使用多轮点估计中位数,不把单轮相减得到的亚微秒差异表述为确定收益。发布前应保留同一机器、 同一 Rust 工具链和同一 Criterion 配置下的基线,避免把环境波动误判为回归。
企业微信消息推送
wecom 不在 full Web 功能中,需要单独启用,避免普通 API 项目被迫引入
HTTP、TLS、Base64 和媒体处理依赖:
[]
= {
version = "0.2.0",
= false,
= ["wecom"]
}
客户端没有全局单例。它是 Clone + Send + Sync 的不可变句柄,内部复用
reqwest::Client 连接池,应由应用在启动期构造并放入 AppState:
use *;
Webhook URL 或 Key 必须来自环境变量或密钥管理服务,不得硬编码进仓库。
Key 使用秘密类型保存,客户端、配置和已脱敏错误的 Debug 都不会输出它。
库内创建的 HTTP 客户端默认禁止自动重定向和 Referer,防止位于查询参数中的 Webhook Key 被
传播给其他主机;同时最多允许 32 个在途请求,避免突发任务耗尽本机临时端口;等待并发名额也
受请求超时限制。JSON 请求体默认最多 3 MiB,可以容纳协议允许的 2 MiB 原始图片编码结果;
响应体默认最多 64 KiB,读取时最多预分配 8 KiB。所有限制都可以在配置中调整且不能设为零。非本机的
Webhook 和自定义基础地址必须使用 HTTPS;localhost、127.0.0.0/8 和 ::1 仅为本地测试
保留 HTTP 能力。
如果通过 WeComRobotClient::with_http_client() 注入应用共享客户端,该客户端也必须禁用自动
重定向和 Referer。消息进入队列前可以先调用 WeComRobotMessage::validate() 做纯本地校验。
发送简单消息:
wecom.send_text.await?;
wecom.send_markdown.await?;
wecom.send_markdown_v2.await?;
文本消息 @ 成员:
let message = from;
wecom.send.await?;
Markdown V2 支持表格、图片链接和代码块,但按官方协议不支持字体颜色和 @ 成员。
发送图文和模板卡片:
let article = new
.with_description
.with_picture_url;
wecom.send_news.await?;
let card = new
.with_horizontal_content;
wecom.send_template_card.await?;
图片会自动校验 JPG/PNG 文件头、2 MiB 上限并计算 Base64 与 MD5;已编码图片会在解码前 先检查 Base64 长度,避免超大输入带来第二份内存峰值:
let bytes = read.await?;
wecom.send_image_bytes.await?;
本地文件使用流式上传,不会整个加载进内存;读取流还会固定在校验元数据时的长度,即使文件在 上传过程中增长,也不会突破已校验上限。普通文件不超过 20 MiB; 语音不超过 2 MiB,仅支持 AMR,时长不超过 60 秒。库会校验大小、扩展名和 AMR 文件头,但不解码语音时长,时长仍会由企业微信服务端最终校验:
wecom.send_file_path.await?;
wecom.send_voice_path.await?;
客户端不会自动重试,避免请求已到达企业微信后重复发送。
请在 Outbox Worker 中根据 MessagingError::is_retryable() 和幂等键决定是否重试。
请求内发送失败时,可以把已脱敏诊断加入当前聚合日志:
下面的组合用法需要同时启用 wecom、response 和 logging;使用默认功能并额外
启用 wecom 时已经满足:
let receipt = wecom.send_text.await.map_err?;
实现依据企业微信官方的 消息推送配置说明:
- 文本最长 2,048 个 UTF-8 字节。
- Markdown 和 Markdown V2 最长 4,096 个 UTF-8 字节。
- 图文每次 1 至 8 条。
- 媒体 ID 有效期为三天,且只能由同一 Webhook 使用。
- 每个 Webhook 最多发送 20 条/分钟;该限制由多实例共享,库不做错误的单进程本地限流。
分页
use *;
let request = verify?;
let offset = request.offset_i64?;
let limit = request.page_size_i64?;
let response = new;
# drop;
verify() 直接接收 Option<u64>。页码缺省时默认为 1,每页数量缺省时默认为
20;两者都不能为 0,每页数量最大为 50。校验失败直接返回
ApiError::err_invalid_param,因此在 AppResult 中可以直接使用 ?。需要自定义最大值时,仍可使用
PageRequest::new(page, page_size, max_page_size)。
PageRequest 不绑定 SQLx 或任何数据库;offset() 保留 u64 结果,
offset_i64() 和 page_size_i64() 便于直接绑定常见数据库参数。默认值与上限也可通过
DEFAULT_PAGE、DEFAULT_PAGE_SIZE 和 MAX_PAGE_SIZE 读取。
质量与安全
持续集成会在最低支持的 Rust 1.94 和最新 stable 上执行全特性测试,并在 stable 上覆盖无默认 功能及各 Web 能力组合;同时执行格式、严格 Clippy、文档和 RustSec 漏洞审计。发布前还应执行:
当前 validify 2.0.0 直接依赖存在 RUSTSEC-2024-0421 的 idna 0.5.0,上游尚未发布
包含修复的版本。.cargo/audit.toml 和 CI 只对这一项做了有说明的精确例外;其他漏洞仍会使
审计失败。在上游升级到 idna 1.0.3 或更高版本前,不要把 Validify 内置的 email
校验结果直接用于域名同源判断、权限判断或唯一身份归一化;这些安全敏感场景应使用基于
idna 1.x 的自定义校验。参考:
许可证
本项目采用 MIT 或 Apache-2.0 双重许可,使用者可任选其一。