refactor(all): 修改项目结构，为BungeeYAML支持注释。

项目结构修改，避免使用上的误解。同时为 Bungee(YAML) 支持了注释功能。 BREAKING CHANGE: 包名与入口类变更 1. 项目结构与包名修改 mineconfiguration-bukkit-general -> mineconfiguration-bukkit mineconfiguration-bukkit-native -> mineconfiguration-spigot 2. MineConfiguration入口类变更，现移动到各自平台的包下。
2026-06-04 13:55:03 +08:00 · 2022-06-09 00:18:14 +08:00
parent 616d24d885
commit f826014c09
16 changed files with 345 additions and 160 deletions
@@ -5,13 +5,13 @@
    <parent>
        <artifactId>mineconfiguration-parent</artifactId>
        <groupId>cc.carm.lib</groupId>
-        <version>1.4.3</version>
+        <version>2.0.0</version>
        <relativePath>../../pom.xml</relativePath>
    </parent>
    <modelVersion>4.0.0</modelVersion>
    <properties>
-        <maven.compiler.source>${java.version}</maven.compiler.source>
-        <maven.compiler.target>${java.version}</maven.compiler.target>
+        <maven.compiler.source>${project.jdk.version}</maven.compiler.source>
+        <maven.compiler.target>${project.jdk.version}</maven.compiler.target>
    </properties>
    <artifactId>mineconfiguration-bungee</artifactId>
    <packaging>jar</packaging>
@@ -54,18 +54,6 @@

    <build>
        <plugins>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-compiler-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-jar-plugin</artifactId>
-            </plugin>
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-source-plugin</artifactId>
-            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-javadoc-plugin</artifactId>
@@ -1,4 +1,4 @@
-package cc.carm.lib.mineconfiguration;
+package cc.carm.lib.mineconfiguration.bungee;

 import cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider;
 import net.md_5.bungee.api.plugin.Plugin;
@@ -4,25 +4,39 @@ import cc.carm.lib.configuration.core.ConfigInitializer;
 import cc.carm.lib.configuration.core.source.impl.FileConfigProvider;
 import net.md_5.bungee.config.Configuration;
 import net.md_5.bungee.config.ConfigurationProvider;
+import net.md_5.bungee.config.YamlConfiguration;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 import org.jetbrains.annotations.Unmodifiable;

+import java.io.BufferedWriter;
 import java.io.File;
 import java.io.IOException;
+import java.io.StringWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
 import java.util.List;

 public class BungeeConfigProvider extends FileConfigProvider<BungeeSectionWrapper> {

+    protected static final char SEPARATOR = '.';
+
    protected ConfigurationProvider loader;
    protected Configuration configuration;
    protected ConfigInitializer<BungeeConfigProvider> initializer;

-    public BungeeConfigProvider(@NotNull File file, ConfigurationProvider loader) {
+    protected BungeeYAMLComments comments = new BungeeYAMLComments();
+
+    public BungeeConfigProvider(@NotNull File file, @NotNull ConfigurationProvider loader) {
        super(file);
        this.loader = loader;
    }

+    public BungeeConfigProvider(@NotNull File file, @NotNull Class<? extends ConfigurationProvider> providerClass) {
+        this(file, ConfigurationProvider.getProvider(providerClass));
+    }
+
    public void initializeConfig() throws IOException {
        this.configuration = getLoader().load(file);
        this.initializer = new ConfigInitializer<>(this);
@@ -41,26 +55,36 @@ public class BungeeConfigProvider extends FileConfigProvider<BungeeSectionWrappe
    @Override
    public void save() throws Exception {
        getLoader().save(configuration, file);
+        if (getLoader() instanceof YamlConfiguration) {
+            StringWriter writer = new StringWriter();
+            this.comments.writeComments(configuration, new BufferedWriter(writer));
+            String value = writer.toString(); // config contents
+
+            Path toUpdatePath = getFile().toPath();
+            if (!value.equals(new String(Files.readAllBytes(toUpdatePath), StandardCharsets.UTF_8))) {
+                Files.write(toUpdatePath, value.getBytes(StandardCharsets.UTF_8));
+            }
+        }
    }

    @Override
    public void setHeaderComment(@Nullable String path, @Nullable List<String> comments) {
-
+        this.comments.setHeaderComments(path, comments);
    }

    @Override
    public void setInlineComment(@NotNull String path, @Nullable String comment) {
-
+        this.comments.setInlineComment(path, comment);
    }

    @Override
    public @Nullable @Unmodifiable List<String> getHeaderComment(@Nullable String path) {
-        return null;
+        return this.comments.getHeaderComment(path);
    }

    @Override
    public @Nullable String getInlineComment(@NotNull String path) {
-        return null;
+        return this.comments.getInlineComment(path);
    }

    @Override
@@ -9,6 +9,8 @@ import org.jetbrains.annotations.Nullable;
 import java.util.*;
 import java.util.stream.Collectors;

+import static cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider.SEPARATOR;
+
 public class BungeeSectionWrapper implements ConfigurationWrapper {

    private final Configuration section;
@@ -22,14 +24,31 @@ public class BungeeSectionWrapper implements ConfigurationWrapper {
        return section == null ? null : new BungeeSectionWrapper(section);
    }

+    protected static Set<String> getAllKeys(@NotNull Configuration config) {
+        Set<String> keys = new LinkedHashSet<>();
+        for (String key : config.getKeys()) {
+            keys.add(key);
+            Object value = config.get(key);
+            if (value instanceof Configuration) {
+                getAllKeys((Configuration) value).stream()
+                        .map(subKey -> key + SEPARATOR + subKey).forEach(keys::add);
+            }
+        }
+        return keys;
+    }
+
    @Override
    public @NotNull Set<String> getKeys(boolean deep) {
-        return new LinkedHashSet<>(section.getKeys());
+        if (deep) {
+            return new LinkedHashSet<>(getAllKeys(section));
+        } else {
+            return new LinkedHashSet<>(section.getKeys());
+        }
    }

    @Override
    public @NotNull Map<String, Object> getValues(boolean deep) {
-        return section.getKeys().stream()
+        return getKeys(deep).stream()
                .collect(Collectors.toMap(key -> key, section::get, (a, b) -> b, LinkedHashMap::new));
    }

@@ -0,0 +1,152 @@
+package cc.carm.lib.mineconfiguration.bungee.source;
+
+import net.md_5.bungee.config.Configuration;
+import net.md_5.bungee.config.ConfigurationProvider;
+import net.md_5.bungee.config.YamlConfiguration;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.Unmodifiable;
+
+import java.io.BufferedWriter;
+import java.io.IOException;
+import java.io.StringWriter;
+import java.util.*;
+import java.util.stream.Collectors;
+import java.util.stream.IntStream;
+
+import static cc.carm.lib.mineconfiguration.bungee.source.BungeeConfigProvider.SEPARATOR;
+
+public class BungeeYAMLComments {
+
+    protected final @NotNull Map<String, List<String>> headerComments = new HashMap<>();
+    protected final @NotNull Map<String, String> inlineComments = new HashMap<>();
+
+    protected @NotNull Map<String, List<String>> getHeaderComments() {
+        return headerComments;
+    }
+
+    protected @NotNull Map<String, String> getInlineComments() {
+        return inlineComments;
+    }
+
+    public void setHeaderComments(@Nullable String path, @Nullable List<String> comments) {
+        if (comments == null) {
+            getHeaderComments().remove(path);
+        } else {
+            getHeaderComments().put(path, comments);
+        }
+    }
+
+
+    public void setInlineComment(@NotNull String path, @Nullable String comment) {
+        if (comment == null) {
+            getInlineComments().remove(path);
+        } else {
+            getInlineComments().put(path, comment);
+        }
+    }
+
+    @Nullable
+    @Unmodifiable
+    public List<String> getHeaderComment(@Nullable String path) {
+        return Optional.ofNullable(getHeaderComments().get(path)).map(Collections::unmodifiableList).orElse(null);
+    }
+
+    public @Nullable String getInlineComment(@NotNull String path) {
+        return getInlineComments().get(path);
+    }
+
+    public @Nullable String buildHeaderComments(@Nullable String path, @NotNull String indents) {
+        List<String> comments = getHeaderComment(path);
+        if (comments == null || comments.size() == 0) return null;
+
+        StringJoiner joiner = new StringJoiner("\n");
+        for (String comment : comments) {
+            if (comment.length() == 0) joiner.add(" ");
+            else joiner.add(indents + "# " + comment);
+        }
+        return joiner + "\n";
+    }
+
+    /**
+     * 从一个文件读取配置并写入注释到某个写入器中。
+     * 该方法的部分源代码借鉴自 tchristofferson/ConfigUpdater 项目。
+     *
+     * @param source 源配置文件
+     * @param writer 配置写入器
+     * @throws IOException 当写入发生错误时抛出
+     */
+    public void writeComments(@NotNull Configuration source, @NotNull BufferedWriter writer) throws IOException {
+        ConfigurationProvider provider = ConfigurationProvider.getProvider(YamlConfiguration.class);
+        Configuration tmp = new Configuration();// 该对象用于临时记录配置内容
+
+        String configHeader = buildHeaderComments(null, "");
+        if (configHeader != null) writer.write(configHeader);
+
+        for (String fullKey : BungeeSectionWrapper.getAllKeys(source)) {
+            Object currentValue = source.get(fullKey);
+
+            String indents = getIndents(fullKey);
+            String headerComments = buildHeaderComments(fullKey, indents);
+            String inlineComment = getInlineComment(fullKey);
+
+            if (headerComments != null) writer.write(headerComments);
+
+            String[] splitFullKey = fullKey.split("[" + SEPARATOR + "]");
+            String trailingKey = splitFullKey[splitFullKey.length - 1];
+
+            if (currentValue instanceof Configuration) {
+                Configuration section = (Configuration) currentValue;
+                writer.write(indents + trailingKey + ":");
+                if (inlineComment != null && inlineComment.length() > 0) {
+                    writer.write(" # " + inlineComment);
+                }
+                if (!section.getKeys().isEmpty()) {
+                    writer.write("\n");
+                } else {
+                    writer.write(" {}\n");
+                    if (indents.length() == 0) writer.write("\n");
+                }
+                continue;
+            }
+
+            tmp.set(trailingKey, currentValue);
+            StringWriter tmpStr = new StringWriter();
+            provider.save(tmp, tmpStr);
+            String yaml = tmpStr.toString();
+            tmpStr.close();
+            tmp.set(trailingKey, null);
+
+            yaml = yaml.substring(0, yaml.length() - 1);
+
+            if (inlineComment != null && inlineComment.length() > 0) {
+                if (yaml.contains("\n")) {
+                    // section为多行内容，需要 InlineComment 加在首行末尾
+                    String[] splitLine = yaml.split("\n", 2);
+                    yaml = splitLine[0] + " # " + inlineComment + "\n" + splitLine[1];
+                } else {
+                    // 其他情况下就直接加载后面就好。
+                    yaml += " # " + inlineComment;
+                }
+            }
+
+            writer.write(indents + yaml.replace("\n", "\n" + indents) + "\n");
+            if (indents.length() == 0) writer.write("\n");
+        }
+
+        writer.close();
+    }
+
+    /**
+     * 得到一个键的缩进。
+     * 该方法的源代码来自 tchristofferson/ConfigUpdater 项目。
+     *
+     * @param key 键
+     * @return 该键的缩进文本
+     */
+    protected static String getIndents(String key) {
+        String[] splitKey = key.split("[" + SEPARATOR + "]");
+        return IntStream.range(1, splitKey.length).mapToObj(i -> "  ").collect(Collectors.joining());
+    }
+
+}
@@ -0,0 +1,51 @@
+import cc.carm.lib.configuration.core.ConfigurationRoot;
+import cc.carm.lib.configuration.core.annotation.HeaderComment;
+import cc.carm.lib.configuration.core.annotation.InlineComment;
+import cc.carm.lib.configuration.core.source.ConfigurationProvider;
+import cc.carm.lib.configuration.core.value.ConfigValue;
+import cc.carm.lib.configuration.core.value.type.ConfiguredList;
+import cc.carm.lib.configuration.core.value.type.ConfiguredValue;
+import cc.carm.lib.mineconfiguration.bungee.MineConfiguration;
+import org.junit.Test;
+
+import java.io.File;
+import java.util.List;
+
+public class ConfigTest {
+
+
+    @Test
+    public void test() {
+        ConfigurationProvider<?> config = MineConfiguration.from(new File("target/config.yml"));
+        config.initialize(Configuration.class);
+    }
+
+
+    @HeaderComment({
+            "MineConfiguration for BungeeCord",
+            "测试实例配置文件", ""
+    })
+    public static class Configuration extends ConfigurationRoot {
+
+        @InlineComment("是否显示DEBUG消息")
+        public static final ConfigValue<Boolean> DEBUG = ConfiguredValue.of(Boolean.class, false);
+
+        @HeaderComment("启动时执行的命令")
+        public static final class START_UP {
+
+            @HeaderComment("延迟执行的时间(单位:秒)")
+            public static final ConfigValue<Integer> DELAY = ConfiguredValue.of(Integer.class, 30);
+
+            @HeaderComment("循环执行的间隔(单位:秒)")
+            public static final ConfigValue<Integer> PERIOD = ConfiguredValue.of(Integer.class, 10);
+
+            @HeaderComment("执行的指令列表")
+            @InlineComment("建议以\"\"包裹")
+            public static final ConfigValue<List<String>> COMMANDS = ConfiguredList.builder(String.class)
+                    .fromString().defaults("alert Commands here!").build();
+        }
+
+    }
+
+
+}