依赖注入

警告

这些文档是为 SpongeAPI 7 编写的，可能已经过时。 如果你觉得你可以帮助更新它们，请提交一个 PR！

当创建你的插件类时，Sponge 使用了一种叫做依赖注入的技术来向你的插件主类提供 API 对象。 其中一些对象，如日志和配置加载器， 会指向你的插件，可以减少你必须写的代码来执行这些任务。

警告

Sponge 仅对你的插件主类进行注入，在其他类上使用 @Inject 将无法使用，除非你把一个 Injector 注入到你的主类中，然后用它来创建其他类。

简单注入

以下类型的字段或构造函数参数可以通过 @com.google.inject.Inject 进行注解，让 Sponge 提供简单的对象。

The following objects are the same, no matter which plugin requests the injection:

The following types return an appropriate instance for the plugin:

  • PluginContainer - returns the plugin container associated with the plugin it is being injected into

  • org.apache.logging.log4j.Logger - returns the logger associated with the plugin it is being injected into

Example: Injecting the Plugin Specific Logger and PluginContainer

We can signal to Sponge that you want to inject the logger in one of two ways, field or constructor injection. All simple injections work the same way in Sponge.

For field injection, you must annotate non-final fields with the @Inject annotation, as in the example below:

import com.google.inject.Inject;
import org.apache.logging.log4j.Logger;

@Inject
private Logger logger;

@Inject
private PluginContainer pluginContainer;

For constructor injection, you must create a constructor, annotate it with @Inject, and add the objects you want injecting as parameters, as in the example below:

import com.google.inject.Inject;
import org.apache.logging.log4j.Logger;

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

private final Logger logger;
private final PluginContainer pluginContainer;

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

In both of these examples, the logger field will contain a Sponge provided logger and the pluginContainer field will contain the plugin’s PluginContainer after the object is constructed.

Configurate Injections

小技巧

View 插件配置 for a guide to configuration, specifically using the @DefaultConfig annotation.

Sponge is also able to inject Configurate specific objects into your plugin class, set up with suggested locations for your plugin configuration. These injections require an additional annotation on your injected type, which will be either ConfigDir or DefaultConfig, dependent on your use case.

The DefaultConfig Annotation

The DefaultConfig annotation is used to resolve a file location. DefaultConfig has a parameter sharedRoot, which alters the file that it points to (where <pluginid> is your plugin’s ID):

  • If sharedRoot is false, the annotation will point to the file config/<pluginid>/<pluginid>.conf.

  • If sharedRoot is true, the annotation will point to the file config/<pluginid>.conf.

The DefaultConfig annotation can be applied on the following types:

  • ConfigurationLoader<CommentedConfigurationNode> - provides a configuration loader that will load and save a HOCON file from the resolved file location

  • ConfigurationReference<CommentedConfigurationNode> - provides a ConfigurationReference that will load and save a HOCON file from the resolved file location

  • Path - stores the path to the file location, useful if you wish to use a different file format for your configuration (such as YAML).

Example Injection

The following example injects the HOCON configuration loader and the path it is pointing to via field injection.

import com.google.inject.Inject;
import org.spongepowered.api.config.DefaultConfig
import org.spongepowered.configurate.CommentedConfigurationNode;
import org.spongepowered.configurate.loader.ConfigurationLoader;

@Inject
@DefaultConfig(sharedRoot = false)
private ConfigurationLoader<CommentedConfigurationNode> loader;

@Inject
@DefaultConfig(sharedRoot = false)
private Path configFilePath;

Most users will only require the provided loader, which can then be interacted with in the normal way.

The ConfigDir annotation

The ConfigDir annotation is used to resolve a folder. The sharedRoot parameter works as follows (where <pluginid> is your plugin’s ID):

  • If sharedRoot is false, the annotation will point to the file config/<pluginid>/.

  • If sharedRoot is true, the annotation will point to the file config/.

The ConfigDir annotation can only be applied on the Path type to retrive this directory. It is generally most useful for plugins that require multiple configuration files, providing the directory to place them rather than a single file.