loveyu-kit 0.2.0

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

use serde::Serialize;
use tracing::{Event, Subscriber, field::Visit};
use tracing_subscriber::{
    fmt::{
        FmtContext, FormatEvent, FormattedFields,
        format::{JsonFields, Writer},
        time::{FormatTime, SystemTime},
    },
    registry::LookupSpan,
};

pub(super) const REQUEST_CONTEXT_FIELD: &str = "__loveyu_kit_request_context_json";
pub(super) const REQUEST_HEADERS_FIELD: &str = "__loveyu_kit_request_headers_json";
pub(super) const ERROR_FIELD: &str = "__loveyu_kit_error_json";

/// 将 loveyu-kit 的结构化字段输出为原生嵌套对象的 JSON 事件格式化器。
///
/// 自定义 Subscriber 应同时使用 [`JsonFields`] 作为 span 字段格式化器。
#[derive(Clone, Copy, Debug, Default)]
pub struct StructuredJsonFormatter;

impl StructuredJsonFormatter {
    /// 创建结构化 JSON 事件格式化器。
    #[must_use]
    pub const fn new() -> Self {
        Self
    }
}

impl<S> FormatEvent<S, JsonFields> for StructuredJsonFormatter
where
    S: Subscriber + for<'lookup> LookupSpan<'lookup>,
{
    fn format_event(
        &self,
        context: &FmtContext<'_, S, JsonFields>,
        mut writer: Writer<'_>,
        event: &Event<'_>,
    ) -> fmt::Result {
        let metadata = event.metadata();
        writer.write_str("{\"timestamp\":\"")?;
        SystemTime.format_time(&mut writer)?;
        writer.write_char('"')?;
        write_json_entry(&mut writer, "level", metadata.level().as_str(), false)?;
        writer.write_str(",\"fields\":{")?;

        let mut visitor = StructuredFieldVisitor::new(&mut writer);
        event.record(&mut visitor);
        visitor.finish()?;

        writer.write_char('}')?;
        write_json_entry(&mut writer, "target", metadata.target(), false)?;

        if let Some(span) = context.parent_span() {
            writer.write_str(",\"span\":{")?;
            let extensions = span.extensions();
            let mut has_fields = false;
            if let Some(fields) = extensions.get::<FormattedFields<JsonFields>>() {
                let fields = fields.fields.trim();
                if let Some(inner) = fields
                    .strip_prefix('{')
                    .and_then(|fields| fields.strip_suffix('}'))
                    .filter(|fields| !fields.is_empty())
                {
                    writer.write_str(inner)?;
                    has_fields = true;
                }
            }
            drop(extensions);
            write_json_entry(&mut writer, "name", span.metadata().name(), !has_fields)?;
            writer.write_char('}')?;
        }

        writer.write_str("}\n")
    }
}

struct StructuredFieldVisitor<'writer> {
    writer: &'writer mut dyn fmt::Write,
    first: bool,
    result: fmt::Result,
}

impl<'writer> StructuredFieldVisitor<'writer> {
    fn new(writer: &'writer mut dyn fmt::Write) -> Self {
        Self {
            writer,
            first: true,
            result: Ok(()),
        }
    }

    const fn finish(self) -> fmt::Result {
        self.result
    }

    fn record_serializable<T>(&mut self, field: &tracing::field::Field, value: &T)
    where
        T: Serialize + ?Sized,
    {
        if self.result.is_err() {
            return;
        }

        self.result = self
            .write_field_name(field.name())
            .and_then(|()| write_serialized(self.writer, value));
    }

    fn write_field_name(&mut self, name: &str) -> fmt::Result {
        if self.first {
            self.first = false;
        } else {
            self.writer.write_char(',')?;
        }

        let output_name = match name {
            REQUEST_CONTEXT_FIELD => "request_context",
            REQUEST_HEADERS_FIELD => "headers",
            ERROR_FIELD => "error",
            name => name,
        };
        write_serialized(self.writer, output_name)?;
        self.writer.write_char(':')
    }

    fn is_raw_json_field(name: &str) -> bool {
        matches!(
            name,
            REQUEST_CONTEXT_FIELD | REQUEST_HEADERS_FIELD | ERROR_FIELD
        )
    }
}

impl Visit for StructuredFieldVisitor<'_> {
    fn record_f64(&mut self, field: &tracing::field::Field, value: f64) {
        self.record_serializable(field, &value);
    }

    fn record_i64(&mut self, field: &tracing::field::Field, value: i64) {
        self.record_serializable(field, &value);
    }

    fn record_u64(&mut self, field: &tracing::field::Field, value: u64) {
        self.record_serializable(field, &value);
    }

    fn record_i128(&mut self, field: &tracing::field::Field, value: i128) {
        self.record_serializable(field, &value);
    }

    fn record_u128(&mut self, field: &tracing::field::Field, value: u128) {
        self.record_serializable(field, &value);
    }

    fn record_bool(&mut self, field: &tracing::field::Field, value: bool) {
        self.record_serializable(field, &value);
    }

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

    fn record_bytes(&mut self, field: &tracing::field::Field, value: &[u8]) {
        self.record_serializable(field, value);
    }

    fn record_error(&mut self, field: &tracing::field::Field, value: &(dyn Error + 'static)) {
        self.record_serializable(field, &DisplayAsString(value));
    }

    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn Debug) {
        if self.result.is_err() {
            return;
        }

        self.result = self.write_field_name(field.name()).and_then(|()| {
            if Self::is_raw_json_field(field.name()) {
                write!(self.writer, "{value:?}")
            } else {
                write_serialized(self.writer, &DebugAsString(value))
            }
        });
    }
}

struct DebugAsString<'value>(&'value dyn Debug);

impl fmt::Display for DebugAsString<'_> {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        Debug::fmt(self.0, formatter)
    }
}

impl Serialize for DebugAsString<'_> {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.collect_str(self)
    }
}

struct DisplayAsString<'value>(&'value dyn Error);

impl fmt::Display for DisplayAsString<'_> {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Display::fmt(self.0, formatter)
    }
}

impl Serialize for DisplayAsString<'_> {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.collect_str(self)
    }
}

fn write_json_entry<T>(
    writer: &mut dyn fmt::Write,
    key: &str,
    value: &T,
    first: bool,
) -> fmt::Result
where
    T: Serialize + ?Sized,
{
    if !first {
        writer.write_char(',')?;
    }
    write_serialized(writer, key)?;
    writer.write_char(':')?;
    write_serialized(writer, value)
}

fn write_serialized<T>(writer: &mut dyn fmt::Write, value: &T) -> fmt::Result
where
    T: Serialize + ?Sized,
{
    serde_json::to_writer(FormatWriteAdapter(writer), value).map_err(|_| fmt::Error)
}

struct FormatWriteAdapter<'writer>(&'writer mut dyn fmt::Write);

impl io::Write for FormatWriteAdapter<'_> {
    fn write(&mut self, buffer: &[u8]) -> io::Result<usize> {
        let value = std::str::from_utf8(buffer)
            .map_err(|error| io::Error::new(io::ErrorKind::InvalidData, error))?;
        self.0
            .write_str(value)
            .map_err(|_| io::Error::other("写入 JSON 日志失败"))?;
        Ok(buffer.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}