第 18 章：最佳实践

汇集代码规范、性能优化、安全建议和兼容性策略，帮助你写出高质量的插件。

18.1 代码规范

命名规范

类型	规范	示例
包名	全小写，逆域名	`com.example.myplugin`
类名	PascalCase	`PlayerManager`, `EconomyService`
方法名	camelCase	`getBalance()`, `sendTitle()`
常量	UPPER_SNAKE_CASE	`MAX_PLAYERS`, `DEFAULT_LANG`
变量	camelCase	`playerCount`, `isReady`
配置键	snake_case	`database.host`, `max-players`

项目结构

com.example.myplugin/
├── MyPlugin.java           # 主类
├── commands/                # 命令处理
│   ├── MainCommand.java
│   ├── HealCommand.java
│   └── WarpCommand.java
├── listeners/               # 事件监听
│   ├── PlayerListener.java
│   └── CombatListener.java
├── managers/                # 管理器
│   ├── EconomyManager.java
│   ├── WarpManager.java
│   └── ConfigManager.java
├── models/                  # 数据模型
│   ├── PlayerData.java
│   └── Warp.java
├── database/                # 数据层
│   ├── DatabaseManager.java
│   └── PlayerDataDAO.java
├── utils/                   # 工具类
│   ├── MessageUtil.java
│   └── ItemBuilder.java
└── tasks/                   # 任务
    ├── AutoSaveTask.java
    └── ScoreboardTask.java

设计模式

// 1. 单例模式（Singleton）
public class EconomyManager {
    private static EconomyManager instance;

    public static EconomyManager getInstance() {
        if (instance == null) {
            instance = new EconomyManager();
        }
        return instance;
    }
}

// 2. 建造者模式（Builder）
public class ItemBuilder {
    private final ItemStack item;
    private final ItemMeta meta;

    public ItemBuilder(Material material) {
        this.item = new ItemStack(material);
        this.meta = item.getItemMeta();
    }

    public ItemBuilder name(String name) {
        meta.displayName(Component.text(name));
        return this;
    }

    public ItemBuilder lore(String... lines) {
        meta.lore(Arrays.stream(lines)
            .map(Component::text)
            .collect(Collectors.toList()));
        return this;
    }

    public ItemStack build() {
        item.setItemMeta(meta);
        return item;
    }
}

// 使用
ItemStack sword = new ItemBuilder(Material.DIAMOND_SWORD)
    .name("§6传说之剑")
    .lore("§7攻击 +100", "§7速度 +20%")
    .build();

18.2 性能优化

高频事件优化

// 不好：每次移动都处理
@EventHandler
public void onMove(PlayerMoveEvent event) {
    checkRegion(event.getPlayer());
}

// 好：只在跨越区块时处理
@EventHandler(ignoreCancelled = true)
public void onMove(PlayerMoveEvent event) {
    Location from = event.getFrom();
    Location to = event.getTo();

    if (to == null) return;
    if (from.getBlockX() >> 4 == to.getBlockX() >> 4
        && from.getBlockZ() >> 4 == to.getBlockZ() >> 4) {
        return; // 同一区块，跳过
    }

    checkRegion(event.getPlayer());
}

数据结构选择

场景	推荐	避免
频繁查找	HashMap / HashSet	ArrayList.contains()
有序数据	TreeMap / TreeSet	手动排序
只读列表	List.of() / Set.of()	Collections.unmodifiableXxx()
大量数值	原生数组 (int[])	ArrayList<Integer>
并发访问	ConcurrentHashMap	synchronized HashMap

字符串拼接

// 不好：循环中拼接
String result = "";
for (String s : list) {
    result += s + ", "; // 每次创建新 String 对象
}

// 好：使用 StringBuilder
StringBuilder sb = new StringBuilder();
for (String s : list) {
    if (!sb.isEmpty()) sb.append(", ");
    sb.append(s);
}
String result = sb.toString();

// 更好：使用 Stream
String result = String.join(", ", list);

缓存策略

public class CacheManager<K, V> {

    private final Map<K, CacheEntry<V>> cache = new HashMap<>();
    private final long ttl; // 缓存过期时间（毫秒）

    public CacheManager(long ttlMillis) {
        this.ttl = ttlMillis;
    }

    public void put(K key, V value) {
        cache.put(key, new CacheEntry<>(value, System.currentTimeMillis()));
    }

    public V get(K key) {
        CacheEntry<V> entry = cache.get(key);
        if (entry == null) return null;

        if (System.currentTimeMillis() - entry.timestamp() > ttl) {
            cache.remove(key); // 过期移除
            return null;
        }

        return entry.value();
    }

    public void clear() {
        cache.clear();
    }

    private record CacheEntry<V>(V value, long timestamp) {}
}

实体管理

// 限制实体数量
public void spawnMobSafely(Location loc, EntityType type, int maxNearby) {
    long count = loc.getWorld().getNearbyEntities(loc, 32, 32, 32).stream()
        .filter(e -> e.getType() == type)
        .count();

    if (count < maxNearby) {
        loc.getWorld().spawnEntity(loc, type);
    }
}

// 定期清理
Bukkit.getScheduler().runTaskTimer(plugin, () -> {
    for (World world : Bukkit.getWorlds()) {
        int removed = cleanupEntities(world, EntityType.DROPPED_ITEM, 100);
        if (removed > 0) {
            plugin.getLogger().info("清理了 " + removed + " 个掉落物");
        }
    }
}, 6000L, 6000L); // 每 5 分钟

18.3 内存管理

防止内存泄漏

public class PlayerDataManager {

    // 不好：玩家退出后数据仍在内存
    private final Map<UUID, PlayerData> data = new HashMap<>();

    // 好：玩家退出时清理
    @EventHandler
    public void onQuit(PlayerQuitEvent event) {
        UUID uuid = event.getPlayer().getUniqueId();
        PlayerData playerData = data.remove(uuid); // 移除并获取
        if (playerData != null) {
            saveToDatabase(playerData); // 持久化
        }
    }
}

取消任务

public class MyPlugin extends JavaPlugin {

    private final List<BukkitTask> tasks = new ArrayList<>();

    @Override
    public void onDisable() {
        // 取消所有任务
        tasks.forEach(BukkitTask::cancel);
        tasks.clear();

        // 或者一次性取消所有
        Bukkit.getScheduler().cancelTasks(this);
    }

    private void startTask() {
        BukkitTask task = Bukkit.getScheduler().runTaskTimer(this, () -> {
            // 逻辑
        }, 0L, 20L);
        tasks.add(task);
    }
}

18.4 安全建议

验证用户输入

public class InputValidator {

    /**
     * 验证玩家名
     */
    public static boolean isValidPlayerName(String name) {
        return name != null
            && name.length() >= 3
            && name.length() <= 16
            && name.matches("[a-zA-Z0-9_]+");
    }

    /**
     * 验证数值范围
     */
    public static boolean isInRange(double value, double min, double max) {
        return value >= min && value <= max;
    }

    /**
     * 清理聊天消息（防注入）
     */
    public static String sanitize(String input) {
        if (input == null) return "";
        return input.replaceAll("[§&][0-9a-fk-or]", "") // 移除颜色代码
                    .trim();
    }

    /**
     * 验证配置文件路径（防路径遍历）
     */
    public static boolean isSafePath(String path) {
        return path != null
            && !path.contains("..")
            && !path.startsWith("/");
    }
}

权限检查

// 始终在执行操作前检查权限
public void handleCommand(CommandSender sender, String[] args) {
    // 不好：先执行后检查
    // executeAction();
    // if (!sender.hasPermission("perm")) { return; }

    // 好：先检查后执行
    if (!sender.hasPermission("myplugin.admin")) {
        sender.sendMessage("§c没有权限！");
        return;
    }
    executeAction();
}

数据保护

// 敏感数据加密
public class DataEncryptor {

    private static final String SECRET_KEY = getConfigSecretKey();

    public static String encrypt(String data) {
        try {
            Cipher cipher = Cipher.getInstance("AES");
            SecretKeySpec key = new SecretKeySpec(
                SECRET_KEY.getBytes(), "AES");
            cipher.init(Cipher.ENCRYPT_MODE, key);
            byte[] encrypted = cipher.doFinal(data.getBytes());
            return Base64.getEncoder().encodeToString(encrypted);
        } catch (Exception e) {
            throw new RuntimeException("加密失败", e);
        }
    }

    public static String decrypt(String encrypted) {
        try {
            Cipher cipher = Cipher.getInstance("AES");
            SecretKeySpec key = new SecretKeySpec(
                SECRET_KEY.getBytes(), "AES");
            cipher.init(Cipher.DECRYPT_MODE, key);
            byte[] decoded = Base64.getDecoder().decode(encrypted);
            return new String(cipher.doFinal(decoded));
        } catch (Exception e) {
            throw new RuntimeException("解密失败", e);
        }
    }
}

SQL 注入防护

// 不好：字符串拼接 SQL
String sql = "SELECT * FROM players WHERE name = '" + playerName + "'";

// 好：参数化查询
String sql = "SELECT * FROM players WHERE name = ?";
PreparedStatement pstmt = connection.prepareStatement(sql);
pstmt.setString(1, playerName);

18.5 兼容性策略

多版本兼容

public class VersionCompat {

    private static final int CURRENT_VERSION = getMinecraftVersion();

    private static int getMinecraftVersion() {
        String version = Bukkit.getBukkitVersion(); // "1.21.4-R0.1-SNAPSHOT"
        String[] parts = version.split("-")[0].split("\\.");
        return Integer.parseInt(parts[0]) * 100 + Integer.parseInt(parts[1]);
    }

    /**
     * 根据版本使用不同 API
     */
    public static void sendActionBar(Player player, String message) {
        if (CURRENT_VERSION >= 1210) {
            // Paper 1.21+ Adventure API
            player.sendActionBar(Component.text(message));
        } else {
            // 旧版兼容
            player.spigot().sendMessage(
                ChatMessageType.ACTION_BAR,
                TextComponent.fromLegacyText(message)
            );
        }
    }
}

优雅降级

public class FeatureManager {

    private boolean papiEnabled = false;
    private boolean vaultEnabled = false;

    public void initialize(MyPlugin plugin) {
        // PlaceholderAPI
        if (Bukkit.getPluginManager().getPlugin("PlaceholderAPI") != null) {
            papiEnabled = true;
            new MyPluginExpansion(plugin).register();
            plugin.getLogger().info("PlaceholderAPI 已集成");
        } else {
            plugin.getLogger().info("PlaceholderAPI 未安装，跳过集成");
        }

        // Vault
        if (Bukkit.getPluginManager().getPlugin("Vault") != null) {
            vaultEnabled = true;
            setupEconomy();
            plugin.getLogger().info("Vault 经济已集成");
        }
    }

    public boolean isPAPIEnabled() { return papiEnabled; }
    public boolean isVaultEnabled() { return vaultEnabled; }
}

18.6 日志与调试

分级日志

public class PluginLogger {

    private final Logger logger;
    private boolean debug = false;

    public void info(String message) {
        logger.info(message);
    }

    public void warning(String message) {
        logger.warning(message);
    }

    public void severe(String message) {
        logger.severe(message);
    }

    public void debug(String message) {
        if (debug) {
            logger.info("[DEBUG] " + message);
        }
    }

    public void setDebug(boolean debug) {
        this.debug = debug;
    }
}

性能监控

public class PerformanceMonitor {

    /**
     * 测量方法执行时间
     */
    public static <T> T measure(String name, Supplier<T> supplier) {
        long start = System.nanoTime();
        T result = supplier.get();
        long elapsed = (System.nanoTime() - start) / 1_000_000; // 毫秒

        if (elapsed > 50) { // 超过 50ms 警告
            Bukkit.getLogger().warning(String.format(
                "[Performance] %s 耗时 %dms", name, elapsed));
        }

        return result;
    }
}

18.7 错误处理

优雅的异常处理

public class SafeExecutor {

    /**
     * 安全执行任务（捕获异常不影响服务器）
     */
    public static void safeRun(Runnable task) {
        try {
            task.run();
        } catch (Exception e) {
            Bukkit.getLogger().severe("任务执行失败: " + e.getMessage());
            e.printStackTrace();
        }
    }

    /**
     * 带返回值的安全执行
     */
    public static <T> Optional<T> safeGet(Supplier<T> supplier) {
        try {
            return Optional.ofNullable(supplier.get());
        } catch (Exception e) {
            Bukkit.getLogger().warning("获取数据失败: " + e.getMessage());
            return Optional.empty();
        }
    }
}

用户友好的错误提示

@EventHandler
public void onCommand(PlayerCommandPreprocessEvent event) {
    try {
        // 处理命令
        handleCommand(event);
    } catch (Exception e) {
        event.setCancelled(true);
        event.getPlayer().sendMessage("§c执行命令时出错，请联系管理员。");
        plugin.getLogger().severe("命令执行失败: " + e.getMessage());
        e.printStackTrace();
    }
}

18.8 配置管理

配置热重载

public class ConfigManager {

    private FileConfiguration config;
    private final JavaPlugin plugin;

    public ConfigManager(JavaPlugin plugin) {
        this.plugin = plugin;
        reload();
    }

    public void reload() {
        plugin.saveDefaultConfig();
        plugin.reloadConfig();
        config = plugin.getConfig();
    }

    public String getString(String path, String def) {
        return config.getString(path, def);
    }

    public int getInt(String path, int def) {
        return config.getInt(path, def);
    }

    public boolean getBoolean(String path, boolean def) {
        return config.getBoolean(path, def);
    }

    public List<String> getStringList(String path) {
        return config.getStringList(path);
    }
}

18.9 更新检查

public class UpdateChecker {

    private final JavaPlugin plugin;
    private final String resourceId; // SpigotMC 资源 ID

    public UpdateChecker(JavaPlugin plugin, String resourceId) {
        this.plugin = plugin;
        this.resourceId = resourceId;
    }

    /**
     * 异步检查更新
     */
    public void check(Consumer<String> callback) {
        Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
            try {
                HttpClient client = HttpClient.newHttpClient();
                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(
                        "https://api.spigotmc.org/legacy/resource.php?"
                        + resourceId + "&command=getversion"))
                    .build();

                HttpResponse<String> response = client.send(
                    request, HttpResponse.BodyHandlers.ofString());

                String latest = response.body().trim();
                String current = plugin.getDescription().getVersion();

                if (!current.equals(latest)) {
                    Bukkit.getScheduler().runTask(plugin, () ->
                        callback.accept(latest));
                }
            } catch (Exception e) {
                plugin.getLogger().warning("检查更新失败: " + e.getMessage());
            }
        });
    }
}

18.10 代码审查清单

类别	检查项
功能	所有功能是否正常工作
权限	权限检查是否正确
输入验证	用户输入是否已验证
异常处理	异常是否被优雅处理
性能	是否有性能瓶颈
内存	是否有内存泄漏
线程安全	异步操作是否安全
配置	配置是否有默认值
文档	代码是否有注释
测试	关键功能是否有测试

18.11 推荐的库

库	用途	说明
Lombok	减少样板代码	@Getter, @Setter
HikariCP	数据库连接池	高性能连接池
Jedis	Redis 客户端	缓存和发布订阅
ProtocolLib	数据包操作	高级网络功能
Adventure	文本组件	现代化消息系统
CommandAPI	命令框架	Brigadier 封装
Configurate	配置管理	Paper 原生配置库

18.12 常见反模式

反模式	问题	改进
主线程 I/O	TPS 下降	异步处理
硬编码配置	不灵活	使用配置文件
魔法数字	难以维护	使用常量
God Class	过大的类	拆分为多个类
重复代码	维护困难	提取公共方法
忽略异常	隐藏问题	记录日志
不使用版本控制	无法回溯	使用 Git

18.13 扩展阅读

Effective Java — Java 最佳实践
Clean Code — 代码整洁之道
Bukkit Plugin Tutorial
PaperMC 开发文档

18.14 本章小结

要点	内容
代码规范	统一命名、合理结构、设计模式
性能优化	避免高频事件开销、合理缓存、限制实体
安全	验证输入、防注入、权限检查
兼容性	多版本适配、优雅降级
错误处理	捕获异常、记录日志、用户友好提示
持续改进	代码审查、自动化测试、定期重构

恭喜你完成了全部 18 章的学习！🎉

回顾学习路线：

入门 → 第 1-5 章（环境 + 基础 API）
进阶 → 第 6-10 章（物品/GUI/世界/实体/计分板）
深入 → 第 11-14 章（数据包/数据库/调度/占位符）
工程 → 第 15-18 章（Docker/测试/发布/最佳实践）

下一步行动建议：

🛠️ 动手写一个完整的插件项目
📖 阅读 PaperMC 官方文档获取最新 API
💬 加入 SpigotMC / PaperMC Discord 社区
🧪 为你的项目添加测试
🚀 发布到 SpigotMC 或 Hangar

祝你的插件开发之旅顺利！🚀

强曰为道

第 18 章：最佳实践

第 18 章：最佳实践

18.1 代码规范

命名规范

项目结构

设计模式

18.2 性能优化

高频事件优化

数据结构选择

字符串拼接

缓存策略

实体管理

18.3 内存管理

防止内存泄漏

取消任务

18.4 安全建议

验证用户输入

权限检查

数据保护

SQL 注入防护

18.5 兼容性策略

多版本兼容

优雅降级

18.6 日志与调试

分级日志

性能监控

18.7 错误处理

优雅的异常处理

用户友好的错误提示

18.8 配置管理

配置热重载

18.9 更新检查

18.10 代码审查清单

18.11 推荐的库

18.12 常见反模式

18.13 扩展阅读

18.14 本章小结