loveyu-kit 0.2.0

面向 Axum 项目的可组合 API 工具库
Documentation
//! SQLx 查询事件的按需捕获。

use std::{
    fmt::Debug,
    future::Future,
    sync::{Arc, Mutex},
};

use tracing::{
    Event, Metadata, Subscriber,
    field::{Field, Visit},
    subscriber::Interest,
};
use tracing_subscriber::{
    Layer,
    layer::{Context, Filter},
    registry::LookupSpan,
};

const SQLX_QUERY_TARGET: &str = "sqlx::query";

/// SQLx 对一次查询输出的底层执行信息。
#[derive(Clone, Debug, Default)]
pub(crate) struct SqlxQueryEvent {
    pub(crate) statement: Option<String>,
    pub(crate) rows_affected: Option<u64>,
    pub(crate) rows_returned: Option<u64>,
    pub(crate) elapsed_secs: Option<f64>,
}

#[derive(Default)]
struct SqlxCaptureState {
    event: Mutex<Option<SqlxQueryEvent>>,
}

tokio::task_local! {
    static CURRENT_SQLX_CAPTURE: Arc<SqlxCaptureState>;
}

/// 一次可跨多个 Future 轮询复用的 SQLx 事件捕获范围。
#[derive(Default)]
pub(crate) struct SqlxQueryCapture {
    state: Arc<SqlxCaptureState>,
}

impl SqlxQueryCapture {
    pub(crate) fn new() -> Self {
        Self::default()
    }

    pub(crate) async fn scope<F>(&self, future: F) -> F::Output
    where
        F: Future,
    {
        CURRENT_SQLX_CAPTURE
            .scope(Arc::clone(&self.state), future)
            .await
    }

    pub(crate) fn take(&mut self) -> Option<SqlxQueryEvent> {
        if let Some(state) = Arc::get_mut(&mut self.state) {
            return state
                .event
                .get_mut()
                .unwrap_or_else(std::sync::PoisonError::into_inner)
                .take();
        }
        self.state
            .event
            .lock()
            .unwrap_or_else(std::sync::PoisonError::into_inner)
            .take()
    }
}

/// 返回当前任务是否已经由显式 SQL 日志策略接管。
pub(crate) fn is_sqlx_capture_active() -> bool {
    CURRENT_SQLX_CAPTURE.try_with(|_| ()).is_ok()
}

/// 在当前异步执行范围内捕获一条 SQLx 查询事件。
pub(crate) async fn capture_sqlx_query<F>(future: F) -> (F::Output, Option<SqlxQueryEvent>)
where
    F: Future,
{
    let mut capture = SqlxQueryCapture::new();
    let output = capture.scope(future).await;
    (output, capture.take())
}

/// 捕获当前 `.logger_sql(...)` 或 `.logger_err()` 执行范围内的 `sqlx::query` 事件。
///
/// 使用工具库提供的 JSON tracing 初始化函数时会自动安装。应用自行组装 Subscriber 时,
/// 应通过 [`SqlxQueryLayer::with_capture_filter`] 把该 Layer 与自己的输出 Layer 一起安装。
#[derive(Clone, Copy, Debug, Default)]
pub struct SqlxQueryLayer;

impl SqlxQueryLayer {
    /// 创建 SQLx 查询捕获 Layer。
    pub const fn new() -> Self {
        Self
    }

    /// 只在工具库的 SQL 捕获范围内启用该 Layer。
    ///
    /// 自定义 tracing Subscriber 应使用该方法安装 Layer,避免影响其他日志 Layer 的过滤结果。
    pub fn with_capture_filter<S>(self) -> impl Layer<S>
    where
        S: Subscriber + for<'lookup> LookupSpan<'lookup> + 'static,
    {
        self.with_filter(SqlxQueryFilter)
    }
}

impl<S> Layer<S> for SqlxQueryLayer
where
    S: Subscriber,
{
    fn on_event(&self, event: &Event<'_>, _context: Context<'_, S>) {
        if event.metadata().target() != SQLX_QUERY_TARGET {
            return;
        }

        let mut visitor = SqlxQueryEventVisitor::default();
        event.record(&mut visitor);
        let captured = visitor.finish();
        let _ = CURRENT_SQLX_CAPTURE.try_with(|state| {
            *state
                .event
                .lock()
                .unwrap_or_else(std::sync::PoisonError::into_inner) = Some(captured);
        });
    }
}

#[derive(Clone, Copy, Debug, Default)]
struct SqlxQueryFilter;

impl<S> Filter<S> for SqlxQueryFilter {
    fn enabled(&self, metadata: &Metadata<'_>, _context: &Context<'_, S>) -> bool {
        metadata.target() == SQLX_QUERY_TARGET && CURRENT_SQLX_CAPTURE.try_with(|_| ()).is_ok()
    }

    fn callsite_enabled(&self, metadata: &'static Metadata<'static>) -> Interest {
        if metadata.target() == SQLX_QUERY_TARGET {
            Interest::sometimes()
        } else {
            Interest::never()
        }
    }
}

#[derive(Default)]
struct SqlxQueryEventVisitor {
    message: Option<String>,
    summary: Option<String>,
    statement: Option<String>,
    rows_affected: Option<u64>,
    rows_returned: Option<u64>,
    elapsed_secs: Option<f64>,
}

impl SqlxQueryEventVisitor {
    fn finish(self) -> SqlxQueryEvent {
        let statement = self
            .statement
            .filter(|statement| !statement.trim().is_empty())
            .or(self.summary)
            .or(self.message)
            .map(|statement| statement.trim().to_owned());
        SqlxQueryEvent {
            statement,
            rows_affected: self.rows_affected,
            rows_returned: self.rows_returned,
            elapsed_secs: self.elapsed_secs,
        }
    }

    fn record_text(&mut self, field: &Field, value: String) {
        match field.name() {
            "message" => self.message = Some(value),
            "summary" => self.summary = Some(value),
            "db.statement" => self.statement = Some(value),
            _ => {}
        }
    }
}

impl Visit for SqlxQueryEventVisitor {
    fn record_f64(&mut self, field: &Field, value: f64) {
        if field.name() == "elapsed_secs" {
            self.elapsed_secs = Some(value);
        }
    }

    fn record_u64(&mut self, field: &Field, value: u64) {
        match field.name() {
            "rows_affected" => self.rows_affected = Some(value),
            "rows_returned" => self.rows_returned = Some(value),
            _ => {}
        }
    }

    fn record_i64(&mut self, field: &Field, value: i64) {
        if let Ok(value) = u64::try_from(value) {
            self.record_u64(field, value);
        }
    }

    fn record_str(&mut self, field: &Field, value: &str) {
        self.record_text(field, value.to_owned());
    }

    fn record_debug(&mut self, field: &Field, value: &dyn Debug) {
        self.record_text(field, format!("{value:?}"));
    }
}

#[cfg(test)]
mod tests {
    use std::sync::{
        Arc,
        atomic::{AtomicUsize, Ordering},
    };

    use tracing_subscriber::prelude::*;

    use super::*;

    #[derive(Clone)]
    struct EventCounter {
        target: &'static str,
        count: Arc<AtomicUsize>,
    }

    impl<S> Layer<S> for EventCounter
    where
        S: Subscriber,
    {
        fn on_event(&self, event: &Event<'_>, _context: Context<'_, S>) {
            if event.metadata().target() == self.target {
                self.count.fetch_add(1, Ordering::Relaxed);
            }
        }
    }

    #[tokio::test(flavor = "current_thread")]
    async fn layer_captures_sqlx_query_fields_only_inside_scope() {
        let subscriber =
            tracing_subscriber::registry().with(SqlxQueryLayer::new().with_capture_filter());
        let _guard = tracing::subscriber::set_default(subscriber);

        tracing::event!(
            target: SQLX_QUERY_TARGET,
            tracing::Level::DEBUG,
            {
                db.statement = "SELECT ignored",
                rows_returned = 1_u64,
                elapsed_secs = 0.001_f64
            },
            "SELECT ignored"
        );

        let (_, event) = capture_sqlx_query(async {
            tracing::event!(
                target: SQLX_QUERY_TARGET,
                tracing::Level::DEBUG,
                {
                    summary = "SELECT id FROM students",
                    db.statement = "",
                    rows_affected = 0_u64,
                    rows_returned = 2_u64,
                    elapsed_secs = 0.012_f64
                }
            );
        })
        .await;

        let event = event.expect("应捕获 SQLx 查询事件");
        assert_eq!(event.statement.as_deref(), Some("SELECT id FROM students"));
        assert_eq!(event.rows_affected, Some(0));
        assert_eq!(event.rows_returned, Some(2));
        assert_eq!(event.elapsed_secs, Some(0.012));

        let (_, event) = capture_sqlx_query(async {
            tracing::event!(
                target: SQLX_QUERY_TARGET,
                tracing::Level::DEBUG,
                {
                    summary = "SELECT id, username FROM …",
                    db.statement = "\n\nSELECT id, username FROM students WHERE id = ?\n",
                    rows_affected = 0_u64,
                    rows_returned = 1_u64,
                    elapsed_secs = 0.006_f64
                }
            );
        })
        .await;

        let event = event.expect("应捕获包含完整语句的 SQLx 事件");
        assert_eq!(
            event.statement.as_deref(),
            Some("SELECT id, username FROM students WHERE id = ?")
        );
    }

    #[test]
    fn capture_filter_does_not_suppress_other_events() {
        let count = Arc::new(AtomicUsize::new(0));
        let subscriber = tracing_subscriber::registry()
            .with(SqlxQueryLayer::new().with_capture_filter())
            .with(EventCounter {
                target: "loveyu_kit::普通日志测试",
                count: Arc::clone(&count),
            });
        let _guard = tracing::subscriber::set_default(subscriber);

        tracing::info!(target: "loveyu_kit::普通日志测试", "普通日志不应被 SQL 捕获层过滤");

        assert_eq!(count.load(Ordering::Relaxed), 1);
    }
}