記錄與除錯

在 Java 中可以使用一些記錄框架。記錄比使用 System.out.println() 印出到標準輸出(stdout)或標準錯誤輸出(stderr)更好,有幾個理由:

  • 記錄訊息以來源名稱作為標籤,使得更容易找出記錄訊息來自何處。
  • 記錄訊息擁有一個能夠被簡單過濾的嚴重性等級(例如停用所有非嚴重警告)
  • 記錄器框架允許您啟用或停用某些來源的消息

Sponge 此用 org.slf4j.Logger,而非 java.util.logging.Logger

取得一個記錄器(Logger)

在插件初始化期間使用的 Guice 模組擁有插件作用域(plugin-scoped)的記錄器,這允許你使用 @Inject annotate 一個欄位、方法或建構子以取得你的插件的記錄器,而此記錄器已經被使用正確地插件 ID 預先設定了。

備註

參閱 主要插件類別 以取得關於設定你的插件 ID 的資訊。

範例 - Field

import com.google.inject.Inject;
import org.slf4j.Logger;

@Inject
private Logger logger;

範例 - Method

private Logger logger;

@Inject
private void setLogger(Logger logger) {
    this.logger = logger;
}

範例 - Constructor

// For the purpose of this example, "Banana" is the class name

private Logger logger;

@Inject
public Banana(Logger logger) {
    this.logger = logger;
}

建議你在你的插件的主要類別中設置 Logger。當插件被載入時,Guice 注入器會將其實例化。

儘管是可以的,在同一類別為你的 Logger 建立一個 Getter 方法也很理想。以下是一個 Getter 方法的範例。

public Logger getLogger() {
    return logger;
}

發送訊息

使用你的 Logger 發送訊息十分簡單。

備註

以下範例假設你的 Logger 的 Getter 方法名為 getLogger(),也就是前一章節所述。這可能會取決於你的 Getter 方法而有所不同。

getLogger().info("String");
getLogger().debug("String");
getLogger().warn("String");
getLogger().error("String");

這裡的 String 是你想要發送的訊息,例如:

getLogger().warn("This is a warning!");

Manipulating the Logging

備註

These techniques should only be used in very rare cases such as badly chosen logging defaults in libraries. Add a config option to disable those if you use them.

Some libraries use bad logging practices such as logging on too high a level. In these cases, you have three choices:

  1. Ask the author of that library to adjust their logging standards, as this fixes the problem at its source.

  2. Recommend your users to configure the logging using a log4j2.xml config file. Provide users with the recommended configuration additions.

  3. Configure the logging in your plugin yourself:

    ((org.apache.logging.log4j.core.Logger) LogManager.getLogger("FtpLoggingFilter")).setLevel(Level.WARN);
    

    This configures the log level of the FtpLoggingFilter logger to WARN. This will hide all messages that use a lower log level such as INFO and DEBUG.

    警告

    This solution assumes that log4j2 is used as logging framework by the server, however that might not be the case for all/future implementations of the SpongeAPI.

If you have any questions regarding logging you can always ask us on IRC, Discord or the Forums.