使用日志系统

GcExcel 提供日志功能，可用于追踪系统运行状态、诊断和排查问题。日志系统基于 Apache Commons Logging (JCL) 作为日志抽象层，无缝集成主流日志框架（例如 Log4j、Logback、SLF4J），在实际开发中，推荐优先使用 Log4j2 管理日志。

您可以设置日志系统的级别，从而控制输出日志的详细程度。常见的日志级别有 debug、info、warn 和 error，优先级关系为：debug < info < warn < error。

当您设置某一日志级别后，所有高于或等于该优先级的日志会被记录，低于该级别的日志则被忽略。例如，将日志级别设为 info 时，info、warn 和 error 级别的日志会被输出，而 debug 日志将不会被输出。

配置日志系统的流程如下图所示：

项目依赖

GcExcel 的日志功能依赖 JCL 作为日志抽象层，因此需要在 classpath 中添加 commons-logging.jar 。对于 Gradle 和 Maven 项目，该依赖会随 GcExcel 自动引入，无需手动添加。

GcExcel 的依赖如下所示，其中，x.x.x 表示您使用的 GcExcel 的版本号。

Gradle（build.gradle）

implementation 'com.grapecitysoft.documents:gcexcel:x.x.x'

Maven（pom.xml）

<dependency>
    <groupId>com.grapecitysoft.documents</groupId>
    <artifactId>gcexcel</artifactId>
    <version>x.x.x</version>
</dependency>

启用日志

GcExcel 的日志系统默认启用，日志级别默认为 info。控制台将自动输出日志信息，无需额外配置。

配置日志

如需进行更丰富的日志输出（如设置日志级别、日志打印到文件等），推荐您采用 log4j2 进行日志管理，操作步骤如下：

为 Gradle 工程或者 Maven 工程添加 log4j2 相关依赖。

Gradle（build.gradle）

implementation 'org.apache.logging.log4j:log4j-api:2.17.2'
implementation 'org.apache.logging.log4j:log4j-core:2.17.2'
implementation 'org.apache.logging.log4j:log4j-jcl:2.17.2'

Maven（pom.xml）

<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-api</artifactId>
    <version>2.17.2</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-core</artifactId>
    <version>2.17.2</version>
</dependency>
<dependency>
    <groupId>org.apache.logging.log4j</groupId>
    <artifactId>log4j-jcl</artifactId>
    <version>2.17.2</version>
</dependency>

在 Gradle 工程或者 Maven 工程的src/main/resources目录下添加日志配置文件log4j2.xml。

<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
    <Appenders>
        <!-- 控制台输出 --> 
        <Console name="STDOUT" target="SYSTEM_OUT">
            <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
        </Console>
        <!-- 文件输出 -->
        <File name="FILE" fileName="mylog.log">
            <PatternLayout pattern="%d %-5p [%t] %C{2} (%F:%L) - %m%n"/>
        </File>
    </Appenders>
    <Loggers>
        <Logger name="org.apache.fontbox" level="info"/>
        <Logger name="org.apache.pdfbox" level="info"/>
        <Logger name="org.apache.log4j.xml" level="info"/>
        <Root level="debug">
            <AppenderRef ref="STDOUT"/>
            <AppenderRef ref="FILE"/>
        </Root>
    </Loggers>
</Configuration>

配置参数说明：

Appender：定义日志输出的位置。Console 表示输出到控制台。File表示输出到文件，fileName 可自定义日志文件名和路径。
Logger：针对指定包或类设置日志级别。
Root Logger：全局默认日志配置，决定了默认日志级别和输出方式。

针对特定包或类设置的日志级别（Logger）优先级高于全局默认日志配置（Root Logger）。如果某个包或类配置了单独的日志级别，则以该级别为准；否则，将使用 Root Logger 的全局默认级别。

验证日志

完成上述日志配置后，可按照以下步骤验证日志系统是否工作正常：

执行以下代码，导出 PDF 文件。

// 初始化工作薄。
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getActiveSheet();
worksheet.getRange("A1").setValue("This is a test file");
// 保存 PDF 文件。
workbook.save("LoggingSystem.pdf");

在控制台和日志文件（例如 mylog.log）中查看日志。

...
2025-07-03 16:26:15,463 DEBUG [main] aX.o (null:-1) - Save pdf of the workbook.
2025-07-03 16:26:15,466 DEBUG [main] aX.o (null:-1) - Paginate Start(Workbook)
2025-07-03 16:26:15,538 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics for fontsFolderPath: null
2025-07-03 16:26:15,539 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics(Use cache): com.grapecity.documents.excel.bu@54504ecd
2025-07-03 16:26:15,542 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics for fontsFolderPath: null
2025-07-03 16:26:15,542 DEBUG [main] excel.bu (null:-1) - Get instance of MypdfGraphics(Use cache): com.grapecity.documents.excel.bu@54504ecd
2025-07-03 16:26:15,573 DEBUG [main] bn.dE (null:-1) - GetDigitWidthOfDefaultStyle GraphicsType: Pdf
...

说明：除了 Log4j 之外，GcExcel 还支持主流日志框架如 SLF4J、Logback，更多信息，请参考 SLF4J 和 Logback。