use std::{
collections::BTreeMap,
fmt::{self, Display, Write as _},
};
use serde::Serialize;
use serde_json::Value;
use crate::{
observability::bounded_json::{BoundedJsonValue, to_bounded_json_value},
web::response::ApiError,
};
pub(super) const MAX_NAME_BYTES: usize = 256;
pub(super) const MAX_ERROR_BYTES: usize = 8 * 1024;
pub(super) const MAX_DETAIL_FIELDS: usize = 32;
pub(super) const MAX_DETAIL_STRING_BYTES: usize = 4 * 1024;
pub(super) const MAX_DETAIL_JSON_BYTES: usize = 16 * 1024;
const MAX_DETAIL_COLLECTION_ITEMS: usize = 32;
const MAX_DETAIL_DEPTH: usize = 8;
pub(super) const MAX_STATEMENT_BYTES: usize = 16 * 1024;
const TRUNCATED_SUFFIX: &str = "…(已截断)";
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum DiagnosticKind {
Sql,
Cache,
ExternalService,
Internal,
}
#[derive(Clone, Debug, Serialize)]
#[non_exhaustive]
#[must_use = "诊断需要写入错误或请求日志上下文才会生效"]
pub struct Diagnostic {
pub kind: DiagnosticKind,
pub name: String,
pub error: String,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub details: BTreeMap<String, Value>,
}
impl Diagnostic {
pub fn new(kind: DiagnosticKind, name: impl Into<String>, error: impl Display) -> Self {
Self {
kind,
name: truncate_owned(name.into(), MAX_NAME_BYTES),
error: bounded_display(&error, MAX_ERROR_BYTES),
details: BTreeMap::new(),
}
}
pub fn with_detail(mut self, key: impl Into<String>, value: impl Display) -> Self {
let key = truncate_owned(key.into(), MAX_NAME_BYTES);
if !self.details.contains_key(&key) && self.details.len() >= MAX_DETAIL_FIELDS {
return self;
}
self.details.insert(
key,
Value::String(bounded_display(&value, MAX_DETAIL_STRING_BYTES)),
);
self
}
pub fn with_json_detail<T>(
mut self,
key: impl Into<String>,
value: T,
) -> Result<Self, serde_json::Error>
where
T: Serialize,
{
let key = truncate_owned(key.into(), MAX_NAME_BYTES);
if !self.details.contains_key(&key) && self.details.len() >= MAX_DETAIL_FIELDS {
return Ok(self);
}
let value = match to_bounded_json_value(&value, MAX_DETAIL_JSON_BYTES)? {
BoundedJsonValue::Value(mut value) => {
bound_json_value(&mut value, 0);
value
}
BoundedJsonValue::TooLarge => Value::String("内容过大,已省略".into()),
};
self.details.insert(key, value);
Ok(self)
}
pub(crate) fn bounded_for_log(mut self) -> Self {
self.name = truncate_owned(self.name, MAX_NAME_BYTES);
self.error = truncate_owned(self.error, MAX_ERROR_BYTES);
if self.details.len() > MAX_DETAIL_FIELDS {
self.details = self.details.into_iter().take(MAX_DETAIL_FIELDS).collect();
}
for value in self.details.values_mut() {
bound_json_value(value, 0);
}
self
}
}
pub(super) fn bound_json_value(value: &mut Value, depth: usize) {
if depth >= MAX_DETAIL_DEPTH {
*value = Value::String("…(嵌套层级已截断)".to_owned());
return;
}
match value {
Value::String(value) => {
*value = truncate_owned(std::mem::take(value), MAX_DETAIL_STRING_BYTES);
}
Value::Array(values) => {
values.truncate(MAX_DETAIL_COLLECTION_ITEMS);
for value in values {
bound_json_value(value, depth + 1);
}
}
Value::Object(values) => {
if values.len() > MAX_DETAIL_COLLECTION_ITEMS {
*values = std::mem::take(values)
.into_iter()
.take(MAX_DETAIL_COLLECTION_ITEMS)
.collect();
}
for value in values.values_mut() {
bound_json_value(value, depth + 1);
}
}
Value::Null | Value::Bool(_) | Value::Number(_) => {}
}
}
pub(super) fn truncate_owned(mut value: String, max_bytes: usize) -> String {
if value.len() <= max_bytes {
return value;
}
let mut boundary = max_bytes.saturating_sub(TRUNCATED_SUFFIX.len());
while boundary > 0 && !value.is_char_boundary(boundary) {
boundary -= 1;
}
value.truncate(boundary);
value.push_str(TRUNCATED_SUFFIX);
value
}
pub(super) fn bounded_display<T>(value: &T, max_bytes: usize) -> String
where
T: Display + ?Sized,
{
let mut writer = LimitedStringWriter {
output: String::with_capacity(max_bytes.min(256)),
max_bytes,
truncated: false,
};
let _ = write!(&mut writer, "{value}");
if writer.truncated {
let keep = max_bytes.saturating_sub(TRUNCATED_SUFFIX.len());
let mut boundary = keep.min(writer.output.len());
while boundary > 0 && !writer.output.is_char_boundary(boundary) {
boundary -= 1;
}
writer.output.truncate(boundary);
if max_bytes >= TRUNCATED_SUFFIX.len() {
writer.output.push_str(TRUNCATED_SUFFIX);
}
}
writer.output
}
struct LimitedStringWriter {
output: String,
max_bytes: usize,
truncated: bool,
}
impl fmt::Write for LimitedStringWriter {
fn write_str(&mut self, value: &str) -> fmt::Result {
let remaining = self.max_bytes.saturating_sub(self.output.len());
if value.len() <= remaining {
self.output.push_str(value);
return Ok(());
}
let mut boundary = remaining;
while boundary > 0 && !value.is_char_boundary(boundary) {
boundary -= 1;
}
self.output.push_str(&value[..boundary]);
self.truncated = true;
Err(fmt::Error)
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum SqlOperation {
Select,
Insert,
Update,
Delete,
Other,
}
#[derive(Clone, Debug, Serialize)]
#[non_exhaustive]
#[must_use = "SQL 诊断需要写入错误或请求日志上下文才会生效"]
pub struct SqlDiagnostic {
pub query_name: String,
pub operation: SqlOperation,
pub statement: String,
pub error: String,
#[serde(skip_serializing_if = "BTreeMap::is_empty")]
pub safe_parameters: BTreeMap<String, Value>,
#[serde(skip_serializing_if = "Option::is_none")]
pub error_code: Option<String>,
#[serde(skip_serializing_if = "Option::is_none")]
pub constraint: Option<String>,
}
impl SqlDiagnostic {
pub fn new(
query_name: impl Into<String>,
operation: SqlOperation,
statement: impl Into<String>,
error: impl Display,
) -> Self {
Self {
query_name: truncate_owned(query_name.into(), MAX_NAME_BYTES),
operation,
statement: truncate_owned(statement.into(), MAX_STATEMENT_BYTES),
error: bounded_display(&error, MAX_ERROR_BYTES),
safe_parameters: BTreeMap::new(),
error_code: None,
constraint: None,
}
}
pub fn with_safe_parameter(mut self, key: impl Into<String>, value: impl Display) -> Self {
let key = truncate_owned(key.into(), MAX_NAME_BYTES);
if !self.safe_parameters.contains_key(&key)
&& self.safe_parameters.len() >= MAX_DETAIL_FIELDS
{
return self;
}
self.safe_parameters.insert(
key,
Value::String(bounded_display(&value, MAX_DETAIL_STRING_BYTES)),
);
self
}
pub fn with_safe_json_parameter<T>(
mut self,
key: impl Into<String>,
value: T,
) -> Result<Self, serde_json::Error>
where
T: Serialize,
{
let key = truncate_owned(key.into(), MAX_NAME_BYTES);
if !self.safe_parameters.contains_key(&key)
&& self.safe_parameters.len() >= MAX_DETAIL_FIELDS
{
return Ok(self);
}
let value = match to_bounded_json_value(&value, MAX_DETAIL_JSON_BYTES)? {
BoundedJsonValue::Value(mut value) => {
bound_json_value(&mut value, 0);
value
}
BoundedJsonValue::TooLarge => Value::String("内容过大,已省略".into()),
};
self.safe_parameters.insert(key, value);
Ok(self)
}
pub fn with_error_code(mut self, code: impl Into<String>) -> Self {
self.error_code = Some(truncate_owned(code.into(), MAX_NAME_BYTES));
self
}
pub fn with_constraint(mut self, constraint: impl Into<String>) -> Self {
self.constraint = Some(truncate_owned(constraint.into(), MAX_NAME_BYTES));
self
}
}
impl From<SqlDiagnostic> for Diagnostic {
fn from(sql: SqlDiagnostic) -> Self {
let mut details = BTreeMap::new();
details.insert(
"operation".into(),
serde_json::to_value(sql.operation).expect("SQL 操作枚举始终可以序列化"),
);
details.insert("statement".into(), Value::String(sql.statement));
if !sql.safe_parameters.is_empty() {
details.insert(
"safe_parameters".into(),
Value::Object(sql.safe_parameters.into_iter().collect()),
);
}
if let Some(error_code) = sql.error_code {
details.insert("error_code".into(), Value::String(error_code));
}
if let Some(constraint) = sql.constraint {
details.insert("constraint".into(), Value::String(constraint));
}
Self {
kind: DiagnosticKind::Sql,
name: sql.query_name,
error: sql.error,
details,
}
}
}
pub trait ResultApiErrorExt<T, E> {
fn map_api_error(self, error: ApiError) -> Result<T, ApiError>
where
E: std::error::Error;
fn map_sql_error<F>(self, error: ApiError, diagnostic: F) -> Result<T, ApiError>
where
E: std::error::Error,
F: FnOnce(&E) -> SqlDiagnostic;
}
impl<T, E> ResultApiErrorExt<T, E> for Result<T, E> {
fn map_api_error(self, error: ApiError) -> Result<T, ApiError>
where
E: std::error::Error,
{
self.map_err(|source| error.with_source(&source))
}
fn map_sql_error<F>(self, error: ApiError, diagnostic: F) -> Result<T, ApiError>
where
E: std::error::Error,
F: FnOnce(&E) -> SqlDiagnostic,
{
self.map_err(|source| {
let diagnostic = diagnostic(&source);
error.with_source(&source).with_sql_error(diagnostic)
})
}
}
#[cfg(test)]
mod tests {
use std::{error::Error, fmt};
use super::*;
#[derive(Debug)]
struct TestError;
impl fmt::Display for TestError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("数据库拒绝执行")
}
}
impl Error for TestError {}
#[test]
fn sql_result_extension_keeps_private_diagnostic() {
let result: Result<(), TestError> = Err(TestError);
let error = result
.map_sql_error(
ApiError::err_database("保存失败,请稍后重试"),
|source| {
SqlDiagnostic::new(
"create_user",
SqlOperation::Insert,
"INSERT INTO users(name) VALUES (?)",
source,
)
.with_safe_parameter("user_id", 1001)
},
)
.unwrap_err();
assert_eq!(error.msg, "保存失败,请稍后重试");
assert_eq!(error.internal_error(), Some("数据库拒绝执行"));
assert_eq!(error.diagnostics().unwrap().len(), 1);
}
#[test]
fn diagnostic_bounds_json_and_sql_fields_during_construction() {
let diagnostic = Diagnostic::new(
DiagnosticKind::Internal,
"n".repeat(MAX_NAME_BYTES * 2),
"错误",
)
.with_json_detail("payload", "x".repeat(MAX_DETAIL_JSON_BYTES * 2))
.unwrap();
assert!(diagnostic.name.len() <= MAX_NAME_BYTES);
assert_eq!(diagnostic.details["payload"], "内容过大,已省略");
let sql = SqlDiagnostic::new(
"query",
SqlOperation::Select,
"S".repeat(MAX_STATEMENT_BYTES * 2),
"错误",
);
assert!(sql.statement.len() <= MAX_STATEMENT_BYTES);
}
}