loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation
use std::{error::Error, io};

use tracing_appender::non_blocking::{ErrorCounter, NonBlockingBuilder, WorkerGuard};
use tracing_subscriber::{
    EnvFilter, Layer,
    fmt::{MakeWriter, format::JsonFields},
    layer::SubscriberExt,
    util::SubscriberInitExt,
};

#[cfg(any(feature = "connection-mysql", feature = "connection-postgres"))]
use super::SqlxQueryLayer;
use super::StructuredJsonFormatter;

/// tracing 初始化错误。
pub type InitTracingError = Box<dyn Error + Send + Sync + 'static>;

/// 非阻塞日志队列满载时的处理策略。
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum LogOverflowPolicy {
    /// 丢弃新日志并累加计数,优先保证请求线程不被日志 I/O 阻塞。
    DropAndCount,
    /// 阻塞日志发送方直到队列恢复容量,优先保证进程存活期间的日志不被主动丢弃。
    Block,
}

/// 非阻塞 JSON 日志的生命周期守卫。
///
/// 应在整个应用运行期间保持它存活;释放时会通知后台写入线程刷新并退出。
#[must_use = "必须在应用生命周期内保留日志守卫"]
pub struct JsonTracingGuard {
    error_counter: ErrorCounter,
    _worker_guard: WorkerGuard,
}

impl JsonTracingGuard {
    /// 返回因队列满载而被丢弃的日志行数。
    #[must_use]
    pub fn dropped_lines(&self) -> usize {
        self.error_counter.dropped_lines()
    }
}

/// 生产级非阻塞 JSON 日志构建器。
#[derive(Clone, Debug)]
#[must_use = "需要调用 init_stdout 或 init_with_writer 初始化日志"]
pub struct JsonTracingBuilder {
    default_filter: String,
    queue_capacity: usize,
    overflow_policy: LogOverflowPolicy,
    worker_thread_name: String,
}

impl JsonTracingBuilder {
    /// 创建非阻塞 JSON 日志配置。
    pub fn new(default_filter: impl Into<String>) -> Self {
        Self {
            default_filter: default_filter.into(),
            queue_capacity: 8_192,
            overflow_policy: LogOverflowPolicy::DropAndCount,
            worker_thread_name: "loveyu-kit-log-writer".into(),
        }
    }

    /// 设置后台队列最多缓冲的日志行数。
    pub const fn queue_capacity(mut self, capacity: usize) -> Self {
        self.queue_capacity = capacity;
        self
    }

    /// 设置队列满载时的处理策略。
    pub const fn overflow_policy(mut self, policy: LogOverflowPolicy) -> Self {
        self.overflow_policy = policy;
        self
    }

    /// 设置后台日志写入线程名称。
    pub fn worker_thread_name(mut self, name: impl Into<String>) -> Self {
        self.worker_thread_name = name.into();
        self
    }

    /// 将 JSON 日志非阻塞地写入 stdout。
    ///
    /// # Errors
    ///
    /// 队列容量、线程名、日志过滤器无效,或全局 Subscriber 已经初始化时返回错误。
    pub fn init_stdout(self) -> Result<JsonTracingGuard, InitTracingError> {
        self.init_with_writer(std::io::stdout())
    }

    /// 将 JSON 日志非阻塞地写入指定的同步输出目标。
    ///
    /// # Errors
    ///
    /// 队列容量、线程名、日志过滤器无效,或全局 Subscriber 已经初始化时返回错误。
    pub fn init_with_writer<W>(self, writer: W) -> Result<JsonTracingGuard, InitTracingError>
    where
        W: io::Write + Send + 'static,
    {
        if self.queue_capacity == 0 {
            return Err(io::Error::new(
                io::ErrorKind::InvalidInput,
                "非阻塞日志队列容量必须大于 0",
            )
            .into());
        }
        if self.worker_thread_name.trim().is_empty() {
            return Err(
                io::Error::new(io::ErrorKind::InvalidInput, "日志写入线程名称不能为空").into(),
            );
        }

        let (writer, worker_guard) = NonBlockingBuilder::default()
            .buffered_lines_limit(self.queue_capacity)
            .lossy(self.overflow_policy == LogOverflowPolicy::DropAndCount)
            .thread_name(&self.worker_thread_name)
            .finish(writer);
        let error_counter = writer.error_counter();
        init_json_tracing_with_writer(&self.default_filter, writer)?;
        Ok(JsonTracingGuard {
            error_counter,
            _worker_guard: worker_guard,
        })
    }
}

/// 使用默认 `info` 过滤级别同步初始化 JSON 日志。
///
/// 该便捷入口适合测试和低流量工具;生产 HTTP 服务应使用 [`JsonTracingBuilder`]。
/// # Errors
///
/// 当过滤器无效或全局 Subscriber 已经初始化时返回错误。
pub fn init_default_json_tracing() -> Result<(), InitTracingError> {
    init_json_tracing("info")
}

/// 同步初始化 JSON 日志。
///
/// 如果环境中存在有效的 `RUST_LOG`,它会覆盖 `default_filter`。
/// 全局 Subscriber 只能初始化一次,因此应由二进制应用在启动阶段调用。
/// 生产 HTTP 服务应使用 [`JsonTracingBuilder`] 将输出 I/O 移到独立线程。
///
/// # Errors
///
/// 当环境变量和默认过滤器均无效,或全局 Subscriber 已经初始化时返回错误。
pub fn init_json_tracing(default_filter: &str) -> Result<(), InitTracingError> {
    init_json_tracing_with_writer(default_filter, std::io::stdout)
}

/// 使用自定义输出目标初始化 JSON 日志。
///
/// 可以传入 `tracing_appender::non_blocking` 返回的 writer,让实际 I/O 在独立线程执行;
/// 调用方必须在应用生命周期内保留对应的 `WorkerGuard`。
///
/// # Errors
///
/// 当环境变量和默认过滤器均无效,或全局 Subscriber 已经初始化时返回错误。
pub fn init_json_tracing_with_writer<W>(
    default_filter: &str,
    writer: W,
) -> Result<(), InitTracingError>
where
    W: for<'writer> MakeWriter<'writer> + Send + Sync + 'static,
{
    let filter = match EnvFilter::try_from_default_env() {
        Ok(filter) => filter,
        Err(_) => EnvFilter::try_new(default_filter)?,
    }
    // SQLx 原始事件只交给捕获 Layer,避免与最终请求聚合日志重复输出。
    .add_directive("sqlx::query=off".parse()?);

    let format_layer = tracing_subscriber::fmt::layer()
        .fmt_fields(JsonFields::new())
        .event_format(StructuredJsonFormatter::new())
        .with_writer(writer)
        .with_filter(filter);

    #[cfg(any(feature = "connection-mysql", feature = "connection-postgres"))]
    tracing_subscriber::registry()
        .with(SqlxQueryLayer::new().with_capture_filter())
        .with(format_layer)
        .try_init()?;
    #[cfg(not(any(feature = "connection-mysql", feature = "connection-postgres")))]
    tracing_subscriber::registry()
        .with(format_layer)
        .try_init()?;

    Ok(())
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn non_blocking_builder_rejects_zero_capacity_before_initializing_subscriber() {
        let result = JsonTracingBuilder::new("info")
            .queue_capacity(0)
            .init_with_writer(std::io::sink());

        assert!(result.is_err());
    }
}