loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation

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:

[dependencies]
loveyu-kit = { version = "0.2.0", features = ["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。

也可以关闭默认功能后按需组合:

[dependencies]
loveyu-kit = {
    version = "0.2.0",
    default-features = false,
    features = ["response", "logging"]
}

可扩展连接管理

安装与生命周期

只启用项目实际使用的连接器,可以减少无关依赖和编译时间:

[dependencies]
loveyu-kit = {
    version = "0.2.0",
    default-features = false,
    features = [
        "connection-mysql",
        "connection-postgres",
        "connection-redis",
        "connection-kafka",
        "connection-etcd",
        "connection-mqtt",
        "connection-elasticsearch",
    ]
}

内置连接器不会根据 URL 返回运行时枚举,而是通过关联类型保留准确的底层客户端类型。 所有连接器遵循相同流程:

  1. connect(connector) 检查连接器是否启用;
  2. 未启用时输出警告并返回未初始化的强类型句柄,不会解析配置或访问网络;
  3. 启用时建立连接并自动执行首次健康检查;
  4. 使用 connection() 获取底层客户端,未启用时会返回明确错误;
  5. 使用 is_connected() 判断底层客户端是否已经初始化;
  6. 使用 verify() 再次检查连接,未启用时返回 ManagedConnectionError::Unavailable;
  7. 应用停机时使用 close() 显式关闭;未启用时没有资源需要释放,因此幂等返回 Ok(())。
use loveyu_kit::connection::{ManagedConnection, MySqlConnector, connect};

# async fn start() -> Result<(), Box<dyn std::error::Error>> {
let connection: ManagedConnection<MySqlConnector> = connect(
    MySqlConnector::new("mysql://user:password@127.0.0.1:3306/app")
        .with_name("primary-mysql")
        .with_enabled(true),
)
.await?;

connection.verify().await?;
let _pool = connection.connection()?;
connection.close().await?;
# Ok(())
# }

同一项目可以创建多个同类型连接,通过 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 loveyu_kit::connection::{MySqlConnector, connect};

# async fn connect_mysql() -> Result<(), Box<dyn std::error::Error>> {
let mysql = connect(
    MySqlConnector::new("mysql://root:password@127.0.0.1:3306/app")
        .with_name("primary-mysql")
        .with_enabled(true),
)
.await?;

let _pool = mysql.connection()?; // 类型为 &MySqlPool。
mysql.close().await?;
# Ok(())
# }

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 loveyu_kit::connection::{PostgresConnector, connect};

# async fn connect_postgres() -> Result<(), Box<dyn std::error::Error>> {
let postgres = connect(
    PostgresConnector::new("postgres://postgres:password@127.0.0.1:5432/app")
        .with_name("primary-postgres")
        .with_enabled(true),
)
.await?;

let _pool = postgres.connection()?; // 类型为 &PgPool。
postgres.close().await?;
# Ok(())
# }

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 loveyu_kit::connection::{RedisConnector, connect};

# async fn connect_redis() -> Result<(), Box<dyn std::error::Error>> {
let redis = connect(
    RedisConnector::new("redis://username:password@127.0.0.1:6379/0")
        .with_name("session-redis")
        .with_enabled(true),
)
.await?;

redis.verify().await?;
let _manager = redis.connection()?; // 类型为 &RedisConnectionManager。
redis.close().await?;
# Ok(())
# }

RedisConnector 默认把建连超时和命令响应超时都设为 5 秒,避免网络故障时无限等待;需要调整 重连退避、并发数或超时时,可以通过 with_manager_config(RedisConnectionManagerConfig) 注入 Redis 原生配置。显式配置为零的超时会在联网前返回配置错误。

Kafka 生产者

启用 feature:connection-kafka。brokers 接收逗号分隔的 Kafka 节点列表; with_property() 会直接传递当前 librdkafka 构建支持的原生配置:

use std::time::Duration;
use loveyu_kit::connection::{KafkaProducerConnector, connect};

# async fn connect_kafka_producer() -> Result<(), Box<dyn std::error::Error>> {
let producer = connect(
    KafkaProducerConnector::new("kafka-1:9092,kafka-2:9092")
        .with_name("order-producer")
        .with_enabled(true)
        .with_client_id("order-service")
        .with_metadata_timeout(Duration::from_secs(5))
        .with_flush_timeout(Duration::from_secs(10))
        .with_property("enable.idempotence", "true")
        .with_property("acks", "all")
        .with_property("linger.ms", "5"),
)
.await?;

let _client = producer.connection()?; // 类型为 &KafkaProducer。
// close 会在释放生产者之前 flush 已经入队的消息。
producer.close().await?;
# Ok(())
# }

Kafka 消费者

Kafka 消费者与生产者使用同一个 connection-kafka feature。创建消费者时必须提供消费组 ID:

use std::time::Duration;
use loveyu_kit::connection::{
    KafkaConsumerApi as _, KafkaConsumerConnector, connect,
};

# async fn connect_kafka_consumer() -> Result<(), Box<dyn std::error::Error>> {
let consumer = connect(
    KafkaConsumerConnector::new("kafka-1:9092,kafka-2:9092", "order-service")
        .with_name("order-consumer")
        .with_enabled(true)
        .with_client_id("order-worker-1")
        .with_metadata_timeout(Duration::from_secs(5))
        .with_property("enable.auto.commit", "false")
        .with_property("auto.offset.reset", "earliest"),
)
.await?;

consumer.connection()?.subscribe(&["orders"])?;
let _client = consumer.connection()?; // 类型为 &KafkaConsumer。
consumer.close().await?;
# Ok(())
# }

etcd

启用 feature:connection-etcd。支持一个或多个 HTTP/HTTPS endpoint,账号密码、请求超时、 连接超时和 TLS 等能力通过原生 EtcdConnectOptions 配置:

use std::time::Duration;
use loveyu_kit::connection::{
    EtcdConnectOptions, EtcdConnector, connect,
};

# async fn connect_etcd() -> Result<(), Box<dyn std::error::Error>> {
let options = EtcdConnectOptions::new()
    .with_user("root", "password")
    .with_connect_timeout(Duration::from_secs(3))
    .with_timeout(Duration::from_secs(5));

let etcd = connect(
    EtcdConnector::new([
        "http://etcd-1:2379",
        "http://etcd-2:2379",
        "http://etcd-3:2379",
    ])
    .with_name("service-discovery")
    .with_enabled(true)
    .with_options(options),
)
.await?;

let mut client = etcd.connection()?.clone();
client.put("services/order", "127.0.0.1:8080", None).await?;
etcd.close().await?;
# Ok(())
# }

未调用 with_options() 时同样会使用 5 秒建连超时和 5 秒请求超时。节点列表为空或包含空地址 会在访问网络前失败;Debug 只显示节点数量,不输出可能意外包含凭据的完整地址。

MQTT

启用 feature:connection-mqtt。可以使用 URL 快速创建,也可以使用 MqttOptions 配置 keep-alive、TLS、遗嘱消息等原生能力。

URL 方式必须提供 client_id 查询参数,当前构建支持 mqtt://、mqtts://、tcp:// 和 ssl://:

use std::time::Duration;
use loveyu_kit::connection::{MqttConnector, connect};

# async fn connect_mqtt_from_url() -> Result<(), Box<dyn std::error::Error>> {
let mqtt = connect(
    MqttConnector::from_url(
        "mqtt://username:password@127.0.0.1:1883?client_id=order-service",
    )?
    .with_name("event-mqtt")
    .with_enabled(true)
    .with_channel_capacity(100)
    .with_connect_timeout(Duration::from_secs(10))
    .with_shutdown_timeout(Duration::from_secs(5)),
)
.await?;

let _client = mqtt.connection()?.client(); // 类型为 &MqttClient。
mqtt.close().await?;
# Ok(())
# }

MqttOptions 方式:

use std::time::Duration;
use loveyu_kit::connection::{MqttConnector, MqttOptions, connect};

# async fn connect_mqtt_with_options() -> Result<(), Box<dyn std::error::Error>> {
let mut options = MqttOptions::new("order-service", "127.0.0.1", 1883);
options
    .set_credentials("username", "password")
    .set_keep_alive(Duration::from_secs(30));

let mqtt = connect(MqttConnector::new(options)).await?;
mqtt.close().await?;
# Ok(())
# }

工具库会持续轮询 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 loveyu_kit::connection::{ElasticsearchConnector, ElasticsearchCredentials, connect};
use std::time::Duration;

# async fn connect_elasticsearch() -> Result<(), Box<dyn std::error::Error>> {
let elasticsearch = connect(
    ElasticsearchConnector::new("https://127.0.0.1:9200")
        .with_name("search-cluster")
        .with_enabled(true)
        .with_timeout(Duration::from_secs(10))
        .with_credentials(ElasticsearchCredentials::Basic(
            "elastic".to_owned(),
            "password".to_owned(),
        )),
)
.await?;

let _client = elasticsearch.connection()?; // 类型为 &ElasticsearchClient。
elasticsearch.verify().await?;
elasticsearch.close().await?;
# Ok(())
# }

全局 HTTP 请求超时默认为 10 秒。节点 URL 不允许内嵌用户名或密码,应统一通过 with_credentials() 提供,避免 URL 在错误链或代理诊断中泄漏凭据。

其他认证形式:

use loveyu_kit::connection::ElasticsearchCredentials;

let bearer = ElasticsearchCredentials::Bearer("access-token".to_owned());
let api_key = ElasticsearchCredentials::ApiKey("key-id".to_owned(), "key-secret".to_owned());
let encoded_api_key = ElasticsearchCredentials::EncodedApiKey("base64-api-key".to_owned());
# drop((bearer, api_key, encoded_api_key));

当前官方 Elasticsearch Rust 客户端仍为 alpha 版本,升级依赖前应检查其变更说明。

自定义连接器

如果需要支持其他数据库、消息队列或中间件,只需为自己的配置类型实现连接、校验和关闭三个 生命周期 trait:

use std::io;
use loveyu_kit::connection::{
    BoxConnectionFuture, Close, Connect, ConnectionSpec, Verify, connect,
};

struct CustomConnector;

impl ConnectionSpec for CustomConnector {
    type Connection = u64;
    type Error = io::Error;

    fn name(&self) -> &str {
        "custom"
    }
}

impl Connect for CustomConnector {
    fn connect(&self) -> BoxConnectionFuture<'_, Self::Connection, Self::Error> {
        Box::pin(async { Ok(42) })
    }
}

impl Verify for CustomConnector {
    fn verify<'a>(
        &'a self,
        connection: &'a Self::Connection,
    ) -> BoxConnectionFuture<'a, (), Self::Error> {
        Box::pin(async move {
            (*connection == 42)
                .then_some(())
                .ok_or_else(|| io::Error::other("连接校验失败"))
        })
    }
}

impl Close for CustomConnector {
    fn close(&self, _connection: Self::Connection) -> BoxConnectionFuture<'_, (), Self::Error> {
        Box::pin(async { Ok(()) })
    }
}

# async fn start() -> Result<(), io::Error> {
let connection = connect(CustomConnector).await?;
# drop(connection);
# Ok(())
# }

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 loveyu_kit::{
    connection::{ManagedConnection, MySqlConnector},
    web::response::{AppOk, AppResult},
};

# async fn detail(
#     mysql: &ManagedConnection<MySqlConnector>,
# ) -> AppResult<i32> {
let value: i32 = sqlx::query_scalar("SELECT 1")
    .fetch_one(mysql.connection()?)
    .await?;

Ok(AppOk::new(value))
# }
use loveyu_kit::prelude::*;

async fn detail() -> ApiResult<&'static str> {
    Ok(ApiResponse::new("数据"))
}

async fn failure() -> ApiResult<()> {
    Err(
        ApiError::err_database("查询失败")
            .with_error("数据库连接被拒绝")
            .with_context("user_id", 1001),
    )
}

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 axum::http::StatusCode;
use loveyu_kit::prelude::*;

let error = ApiError::err_unauthorized("请先登录")
    .with_http_status(StatusCode::UNAUTHORIZED);

AppOk、AppError 和 AppResult 是兼容别名,可以用于迁移已有项目。

请求修改与校验

use axum::Json;
use serde::Deserialize;
use loveyu_kit::prelude::*;
use validify::{Payload, Validify};

#[derive(Deserialize, Payload, Validify)]
struct CreateUser {
    #[modify(trim)]
    #[validate(length(
        min = 3,
        code = "42001",
        message = "用户名长度不能少于 3 个字符"
    ))]
    username: String,
}

async fn create(
    Validated(Json(data)): ValidatedJson<CreateUser>,
) -> ApiResult<String> {
    Ok(ApiResponse::new(data.username))
}

所有参数提取或 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 loveyu_kit::prelude::*;

fn main() -> Result<(), InitTracingError> {
    init_default_json_tracing()?;
    Ok(())
}

默认初始化器同步写入 stdout,适合测试和低流量命令行工具。生产 HTTP 服务应使用内置的 JsonTracingBuilder,把格式化后的日志交给独立线程写出:

use loveyu_kit::prelude::*;

fn main() -> Result<(), InitTracingError> {
    let tracing_guard = JsonTracingBuilder::new("info")
        .queue_capacity(16_384)
        // 延迟优先:满载时丢弃新日志,并通过 guard 暴露累计数量。
        .overflow_policy(LogOverflowPolicy::DropAndCount)
        .init_stdout()?;

    // 在 guard 存活期间启动并运行 Axum 服务;关闭前可上报丢弃数量。
    eprintln!("累计丢弃日志:{}", tracing_guard.dropped_lines());
    Ok(())
}

默认队列容量为 8192 行,默认 DropAndCount,保证日志磁盘变慢时不阻塞请求线程; JsonTracingGuard::dropped_lines() 可接入监控。对绝不能主动丢弃的低流量任务可改用 LogOverflowPolicy::Block,但队列满时会把背压传到产生日志的线程。guard 必须保持到应用退出, 释放时后台线程才会刷新剩余日志并退出。仍需自定义 MakeWriter 的应用可以继续使用 init_json_tracing_with_writer。

如果应用需要自行组装 Subscriber,应使用工具库提供的格式化器,才能保留嵌套对象结构:

use loveyu_kit::prelude::StructuredJsonFormatter;
use tracing_subscriber::fmt::format::JsonFields;

let subscriber = tracing_subscriber::fmt()
    .fmt_fields(JsonFields::new())
    .event_format(StructuredJsonFormatter::new())
    .finish();

将请求日志安装到已经添加路由的 Router:

use axum::{Router, routing::get};
use loveyu_kit::prelude::*;

let app = Router::new()
    .route("/health", get(|| async { "ok" }))
    .with_request_logging();

with_request_logging() 默认也会捕获 handler 或被该层包裹的 middleware 中的 panic:客户端收到 HTTP 500 和统一响应 {"code":500000,"msg":"系统内部错误"},panic 的真实内容只会写入 该请求最终的 ERROR 日志,不会泄露给客户端。

可以修改 panic 响应配置:

use axum::http::StatusCode;
use loveyu_kit::prelude::*;

let config = RequestLoggingConfig::new().with_panic_recovery_config(
    PanicRecoveryConfig::new()
        .with_code(50000)
        .with_client_message("服务暂时不可用")
        .with_http_status(StatusCode::INTERNAL_SERVER_ERROR),
);

let app = app.with_request_logging_config(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 loveyu_kit::prelude::*;

async fn update() -> ApiResult<&'static str> {
    audit::command("resource.update", "修改资源", "resource");

    // 应在数据库事务提交成功后记录最终目标和字段变化。
    audit::target("resource", "resource-1001");
    audit::field_change("enabled", false, true);

    Ok(ApiResponse::new("完成"))
}

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 = RequestLoggingLimits::new()
    .max_fields(64)
    .max_value_bytes(32 * 1024)
    .max_diagnostics(8);
let config = RequestLoggingConfig::new().with_limits(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 axum::http::HeaderName;
use loveyu_kit::prelude::*;

let config = RequestLoggingConfig::new()
    .trusted_subject_header(HeaderName::from_static("x-gateway-subject"))
    .trusted_subject_kind("user");

let app = app.with_request_logging_config(config);

async fn profile(subject: TrustedSubject, request_id: RequestId) -> ApiResult<String> {
    Ok(ApiResponse::new(format!("{}:{request_id}", subject.id())))
}

不需要身份的接口无需提取 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 loveyu_kit::prelude::*;

const UPDATE_USER: &str = "UPDATE users SET nickname = ? WHERE id = ?";

# async fn update(pool: &MySqlPool) -> AppResult<u64> {
let result = sqlx::query(UPDATE_USER)
    .bind("新昵称")
    .bind(1001_u64)
    .logger_sql("user.update")
    .not_found_if_zero("用户不存在")
    .with_safe_parameter("user_id", 1001_u64)
    .execute(pool)
    .await?;

Ok(AppOk::new(result.rows_affected()))
# }

通过 MySqlConnector 或 PostgresConnector 创建的连接池默认启用失败记录,因此普通查询不需要 手动调用 .logger_err()。RowNotFound 会自动映射为 err_not_found,唯一索引冲突会自动映射为 err_unique_index_conflict:

use loveyu_kit::prelude::*;

const SELECT_USER: &str = "SELECT id, nickname FROM users WHERE id = ?";

# async fn detail(pool: &MySqlPool) -> AppResult<(u64, String)> {
let user = sqlx::query_as::<_, (u64, String)>(SELECT_USER)
    .bind(1001_u64)
    .fetch_one(pool)
    .await?;

Ok(AppOk::new(user))
# }

默认策略与显式策略如下:

策略 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 = Router::new()
    .route("/articles", get(list_articles))
    .with_access_logging();

with_access_logging() 与完整模式使用相同的过滤、采样、慢请求、错误和 panic 恢复策略,但不会 创建 RequestLogContext,也不会将其写入请求或响应扩展。完整模式默认只注入请求扩展;需要通过 Extension<RequestLogContext> 收集业务字段的路由应继续使用 with_request_logging()。 测试或外层 middleware 确实需要从响应读取最终上下文时,显式配置 .expose_context_in_response(true)。

通过白名单指定允许记录的请求头:

use axum::http::{
    HeaderName,
    header::{CONTENT_TYPE, USER_AGENT},
};
use loveyu_kit::prelude::*;

let config = RequestLoggingConfig::new()
    .include_headers([USER_AGENT, CONTENT_TYPE])
    .include_header(HeaderName::from_static("x-client-version"));

let app = app.with_request_logging_config(config);

轻量模式同样支持自定义配置:app.with_access_logging_config(config)。

控制请求日志数量:

use std::time::Duration;

use loveyu_kit::prelude::*;

let config = RequestLoggingConfig::new()
    // 精确匹配实际路径或 Axum 路由模板,成功响应不记录。
    .skip_success_path("/health")
    .skip_success_path("/metrics")
    // 匹配一组路径前缀,查询字符串不参与判断。
    .skip_success_prefix("/static/")
    // 达到 400ms 的请求始终记录,成功的慢请求使用 WARN 级别。
    .slow_request_threshold(Duration::from_millis(400))
    // 记录全部普通成功请求;必须位于 0.0 到 1.0 之间。
    .success_sample_rate(1.0)
    // 错误忽略成功路径过滤和采样策略,始终记录。
    .always_log_errors(true)
    // 可选:普通成功查询和预期查询错误静默;系统错误仍记录。
    .quiet_queries(true)
    // quiet_queries 启用时仍记录慢查询;默认就是 true。
    .log_slow_queries(true)
    // 可选:命令操作绕过路径过滤和采样,成功或失败都记录。
    .always_log_commands(true);

let app = app.with_request_logging_config(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 = Router::new()
    .route("/health", get(|| async { "正常" }))
    .route("/metrics", get(metrics));

let business_routes = Router::new()
    .route("/users", get(users))
    .with_request_logging();

let app = Router::new().merge(quiet_routes).merge(business_routes);

Authorization、Cookie、Set-Cookie 和 X-Api-Key 即使加入请求头白名单也会默认输出 [已脱敏]。密码、原始 Token 和个人敏感信息同样不得加入请求上下文;项目还可以通过 redact_header 扩充请求头脱敏名单。

仓库提供可重复执行的日志固定成本基准:

cargo bench --features logging --bench logging

SQL_LOG_BENCH_DATABASE_URL='postgresql://用户@localhost/基准库' \
  cargo bench --features logging,connection-postgres --bench sql_logging

基准分别测量无日志层、完整上下文但事件被过滤、轻量访问日志但事件被过滤三条请求路径, 以及字符串和小型 JSON 上下文写入。SQL 基准同时区分无请求上下文快速路径和完整请求上下文, 覆盖正常查询、数据库错误与 256 行流式读取。数据库组按顺序运行时可能出现连接调度和系统负载漂移, 因此图表使用多轮点估计中位数,不把单轮相减得到的亚微秒差异表述为确定收益。发布前应保留同一机器、 同一 Rust 工具链和同一 Criterion 配置下的基线,避免把环境波动误判为回归。

企业微信消息推送

wecom 不在 full Web 功能中,需要单独启用,避免普通 API 项目被迫引入 HTTP、TLS、Base64 和媒体处理依赖:

[dependencies]
loveyu-kit = {
    version = "0.2.0",
    default-features = false,
    features = ["wecom"]
}

客户端没有全局单例。它是 Clone + Send + Sync 的不可变句柄,内部复用 reqwest::Client 连接池,应由应用在启动期构造并放入 AppState:

use loveyu_kit::prelude::*;

#[derive(Clone)]
struct AppState {
    wecom: WeComRobotClient,
}

fn build_state(webhook_url: String) -> Result<AppState, MessagingError> {
    let config = WeComRobotConfig::from_webhook_url(webhook_url)?
        .with_timeout(std::time::Duration::from_secs(10))
        .with_max_in_flight_requests(32)
        .with_max_request_body_bytes(3 * 1024 * 1024)
        .with_max_response_body_bytes(64 * 1024);
    let wecom = WeComRobotClient::new(config)?;
    Ok(AppState { wecom })
}

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("## 发布完成\n> 环境:生产").await?;
wecom.send_markdown_v2("| 项目 | 结果 |\n| --- | --- |\n| API | 成功 |").await?;

文本消息 @ 成员:

let message = WeComRobotMessage::from(
    WeComTextContent::new("服务出现异常,请及时处理")
        .mention_user("zhangsan")
        .mention_mobile("13800138000"),
);
wecom.send(&message).await?;

Markdown V2 支持表格、图片链接和代码块,但按官方协议不支持字体颜色和 @ 成员。

发送图文和模板卡片:

let article = WeComNewsArticle::new("今日日报", "https://example.com/daily")
    .with_description("查看今日运营数据")
    .with_picture_url("https://example.com/daily.png");
wecom.send_news([article]).await?;

let card = WeComTextNoticeCard::new(
    WeComMainTitle::new("发布完成").with_description("生产环境"),
    WeComCardAction::url("https://example.com/releases/1"),
)
.with_horizontal_content(WeComHorizontalContent::text("版本", "1.0.0"));
wecom.send_template_card(card).await?;

图片会自动校验 JPG/PNG 文件头、2 MiB 上限并计算 Base64 与 MD5;已编码图片会在解码前 先检查 Base64 长度,避免超大输入带来第二份内存峰值:

let bytes = tokio::fs::read("alert.png").await?;
wecom.send_image_bytes(&bytes).await?;

本地文件使用流式上传,不会整个加载进内存;读取流还会固定在校验元数据时的长度,即使文件在 上传过程中增长,也不会突破已校验上限。普通文件不超过 20 MiB; 语音不超过 2 MiB,仅支持 AMR,时长不超过 60 秒。库会校验大小、扩展名和 AMR 文件头,但不解码语音时长,时长仍会由企业微信服务端最终校验:

wecom.send_file_path("report.xlsx").await?;
wecom.send_voice_path("notice.amr").await?;

客户端不会自动重试,避免请求已到达企业微信后重复发送。 请在 Outbox Worker 中根据 MessagingError::is_retryable() 和幂等键决定是否重试。 请求内发送失败时,可以把已脱敏诊断加入当前聚合日志:

下面的组合用法需要同时启用 wecom、response 和 logging;使用默认功能并额外 启用 wecom 时已经满足:

let receipt = wecom.send_text("告警").await.map_err(|error| {
    ApiError::err_request_external_service("企业微信消息发送失败")
        .with_source(&error)
        .with_diagnostic(error.to_diagnostic("wecom.send"))
})?;

实现依据企业微信官方的 消息推送配置说明:

  • 文本最长 2,048 个 UTF-8 字节。
  • Markdown 和 Markdown V2 最长 4,096 个 UTF-8 字节。
  • 图文每次 1 至 8 条。
  • 媒体 ID 有效期为三天,且只能由同一 Webhook 使用。
  • 每个 Webhook 最多发送 20 条/分钟;该限制由多实例共享,库不做错误的单进程本地限流。

分页

use loveyu_kit::prelude::*;

let request = PageRequest::verify(query.page, query.page_size)?;
let offset = request.offset_i64()?;
let limit = request.page_size_i64()?;
let response = ApiResponse::new(Page::new(items, total, request));
# drop((offset, limit, response));

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 漏洞审计。发布前还应执行:

cargo test --all-features --release --locked
cargo audit

当前 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 双重许可,使用者可任选其一。