日志记录

内置现代化、高性能的日志记录框架，提供了统一的日志记录接口，支持多种输出目标、灵活的过滤机制和丰富的日志级别控制。

快速启动

只需要以下 3 个步骤即可开始使用日志系统：

import spire_extensions_logging.*

main() {
    // 1. 创建并配置日志系统
    let logging = LoggingBuilder()
        .addConsole()                    // 添加控制台输出
        .setMinimumLevel(LogLevel.Info)  // 设置最低日志级别
        .build()

    // 2. 创建日志器
    let logger = logging.createLogger("Application")

    // 3. 记录日志
    logger.info("Application Started!")
    logger.warn("This is a warning.")
    logger.error("This is an Error!")
}

日志级别

日志级别（LogLevel）定义了日志信息的重要性和详细程度：

public enum LogLevel <: Comparable<LogLevel> & ToString {
    Trace | Debug | Info | Warn | Error | Fatal | Off
}

级别	优先级	使用场景	典型内容
Trace	0 (最低)	非常详细的调试	方法进入/退出、变量值
Debug	1	开发调试	业务逻辑流程、中间结果
Info	2	一般信息	业务操作完成、状态变更
Warn	3	警告信息	潜在问题、性能问题
Error	4	错误信息	处理失败、异常情况
Fatal	5	致命错误	系统崩溃、无法恢复
Off	6 (最高)	关闭日志	不输出任何日志

注意：

如果产生了 Fatal 级别的日志错误提示，提示会造成系统崩溃，数据丢失等严重错误，需要迅速修复

日志过滤

日志过滤允许精确控制哪些日志应该被记录：

按级别过滤

let logging = LoggingBuilder()
    .addConsole()
    .setMinimumLevel(LogLevel.Warn)  // 全局最低级别为警告
    .build()

按提供者和类别过滤

let logging = LoggingBuilder()
    .addConsole()
    .addFilter("console", "Database", LogLevel.Error)    // 数据库相关只显示错误
    .addFilter("console", "Services.*", LogLevel.Info)      // 所有服务层模块
    .build()

匹配

支持通配符“*”匹配

支持自定义过滤器

// 定义过滤器类型
type LoggerFilter = (providerName: String, categoryName: String, level: LogLevel) -> Bool

let myFilter: LoggerFilter = {providerName, categoryName, logLevel =>
    // 你的日志级别比较逻辑，返回Bool
}

// 创建自定义日志系统
let logging = LoggingBuilder()
    .addConsole()
    .addFilter(myFilter)
    .build()

建议

.addFilter()并不接收 Bool 类型的参数，接收的是返回 Bool 值的函数

不要在过滤器中进行昂贵的计算操作，避免 I/O 操作

TIP

使用.addConsole()将输出日志到当前项目根目录/logs 下

最佳实践

性能考虑

• 避免在日志中进行复杂计算
• 避免在过滤器中执行 I/O 操作