use std::fmt::Display;
use serde::Serialize;
use super::{
Diagnostic, DiagnosticKind, FieldChange, RequestLogContext, RequestOperation, ResourceTarget,
SqlDiagnostic,
};
pub fn command(name: &'static str, description: &'static str, resource: &'static str) {
RequestLogContext::with_current(|context| {
context.set_operation(
RequestOperation::command_static(name)
.with_description_static(description)
.with_resource_static(resource),
);
});
}
pub fn command_owned(
name: impl Into<String>,
description: impl Into<String>,
resource: impl Into<String>,
) {
RequestLogContext::with_current(|context| {
context.set_operation(
RequestOperation::command(name)
.with_description(description)
.with_resource(resource),
);
});
}
pub fn query(name: &'static str, description: &'static str, resource: &'static str) {
RequestLogContext::with_current(|context| {
context.set_operation(
RequestOperation::query_static(name)
.with_description_static(description)
.with_resource_static(resource),
);
});
}
pub fn query_owned(
name: impl Into<String>,
description: impl Into<String>,
resource: impl Into<String>,
) {
RequestLogContext::with_current(|context| {
context.set_operation(
RequestOperation::query(name)
.with_description(description)
.with_resource(resource),
);
});
}
pub fn target(kind: impl Into<String>, id: impl Display) {
RequestLogContext::with_current(|context| {
context.add_target(ResourceTarget::new(kind).with_id(id.to_string()));
});
}
pub fn target_resource(target: ResourceTarget) {
RequestLogContext::with_current(|context| context.add_target(target));
}
pub fn field_change(field: impl Into<String>, before: impl Display, after: impl Display) {
RequestLogContext::with_current(|context| {
context.add_change(FieldChange::new(field, before, after));
});
}
pub fn change(
field: impl Into<String>,
before: impl Into<serde_json::Value>,
after: impl Into<serde_json::Value>,
) {
RequestLogContext::with_current(|context| {
context.add_change(FieldChange::from_values(field, before, after));
});
}
pub fn attempted_change(field: impl Into<String>, before: impl Display, after: impl Display) {
RequestLogContext::with_current(|context| {
context.add_attempted_change(FieldChange::new(field, before, after));
});
}
pub fn json_field_change<T, U>(
field: impl Into<String>,
before: T,
after: U,
) -> Result<bool, serde_json::Error>
where
T: Serialize,
U: Serialize,
{
let Some(context) = RequestLogContext::try_current() else {
return Ok(false);
};
let change = FieldChange::from_json(field, before, after)?;
context.add_change(change);
Ok(true)
}
pub fn json_attempted_change<T, U>(
field: impl Into<String>,
before: T,
after: U,
) -> Result<bool, serde_json::Error>
where
T: Serialize,
U: Serialize,
{
let Some(context) = RequestLogContext::try_current() else {
return Ok(false);
};
context.add_attempted_change(FieldChange::from_json(field, before, after)?);
Ok(true)
}
pub fn diagnostic(diagnostic: Diagnostic) {
RequestLogContext::with_current(|context| context.record_diagnostic(diagnostic));
}
pub fn failure(kind: DiagnosticKind, name: impl Into<String>, error: impl Display) {
diagnostic(Diagnostic::new(kind, name, error));
}
pub fn sql_error(diagnostic: SqlDiagnostic) {
RequestLogContext::with_current(|context| context.record_sql_error(diagnostic));
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
use crate::observability::{OperationKind, context::scope_request_log};
#[tokio::test]
async fn helpers_collect_structured_request_audit_information() {
let context = RequestLogContext::new();
scope_request_log(context.clone(), async {
command("article.save", "保存文章", "article");
target("article", 1001);
field_change("title", "旧标题", "新标题");
assert!(
json_field_change("visibility", false, true).expect("JSON 字段变化应当可序列化")
);
})
.await;
let snapshot = context.structured_snapshot();
let operation = snapshot.operation.expect("应当记录当前操作");
assert_eq!(operation.name, "article.save");
assert_eq!(operation.kind, OperationKind::Command);
assert_eq!(snapshot.targets[0].id.as_deref(), Some("1001"));
assert_eq!(snapshot.changes[0].before, json!("旧标题"));
assert_eq!(snapshot.changes[1].after, json!(true));
}
#[tokio::test]
async fn helpers_are_noop_without_request_logging_scope() {
query("article.list", "查询文章", "article");
target("article", 1001);
field_change("title", "旧标题", "新标题");
assert!(
!json_field_change("visibility", false, true)
.expect("没有请求上下文时不应执行 JSON 序列化")
);
}
}