日志服务 (LoggerAPI)

概述

EnderRealmServerCore 提供统一的日志服务 LoggerAPI，所有模块必须使用此服务输出日志，禁止使用 Bukkit 原生 Logger。

获取 LoggerAPI

主类（JavaPlugin 子类）

import cn.enderrealm.core.EnderRealmServerCore;
import cn.enderrealm.core.api.LoggerAPI;

public class MyPlugin extends JavaPlugin {
    private LoggerAPI logger;

    @Override
    public void onEnable() {
        logger = EnderRealmServerCore.getLoggerAPI().withPrefix("[MyPlugin]");
    }

    // 供其他类获取
    public LoggerAPI getLoggerAPI() {
        return logger;
    }
}

其他类

public class MyManager {
    private final LoggerAPI logger;

    public MyManager(MyPlugin plugin) {
        this.logger = plugin.getLoggerAPI();
    }
}

继承体系

基类持有 logger 字段，子类直接使用：

public abstract class Disaster {
    protected final LoggerAPI logger;

    public Disaster(disaster plugin, ...) {
        this.logger = plugin.getLoggerAPI();
    }
}

public class ZombieDisaster extends Disaster {
    public void start() {
        logger.info("僵尸灾难启动");
    }
}

日志方法

方法	说明	生产环境是否输出
error(String msg)	错误	✅
error(String msg, Throwable t)	错误 + 异常堆栈	✅
warn(String msg, Object... args)	警告	✅
info(String msg, Object... args)	普通信息	✅
debug(String msg, Object... args)	调试信息	❌
trace(String msg, Object... args)	追踪信息	❌

占位符格式

使用 {} 占位符，禁止字符串拼接：

// ❌ 错误
logger.info("玩家 " + name + " 传送到 " + x + ", " + y);
logger.info("加载了 " + count + " 个产矿机");

// ✅ 正确
logger.info("玩家 {} 传送到 {}, {}", name, x, y);
logger.info("加载了 {} 个产矿机", count);

日志级别选择

环境默认级别

环境	默认级别	说明
DEVELOPMENT	DEBUG	显示所有日志
STAGING	INFO	只显示 info 及以上
PRODUCTION	WARN	只显示警告和错误

级别判断标准

✅ 保留为 INFO 的日志

• 服务器启动/关闭
• 世界创建/删除成功
• 游戏开始/结束
• 配置文件加载完成
• 重要业务流程节点

logger.info("游戏开始，地图: {}", mapName);
logger.info("产矿机加载完成，共 {} 个", count);
logger.info("事件系统已启动，共 {} 个事件", events.size());

🔄 降级为 DEBUG 的日志

• 位置比较详情
• 坐标计算过程
• 保护区域检查步骤
• 方块放置/破坏详情
• 末影珍珠伤害处理
• 资源点/队伍位置加载详情

// ❌ 不应该在生产环境输出
logger.info("比较位置 - 位置1: x=" + x1 + ", y=" + y1);
logger.info("玩家 " + name + " 尝试放置方块: " + material);

// ✅ 正确降级为 DEBUG
logger.debug("比较位置 - 位置1: x={}, y={}", x1, y1);
logger.debug("玩家 {} 尝试放置方块: {}", name, material);

判断原则

如果一条日志在生产环境中没有诊断价值，或者输出频率极高（如每次玩家交互都触发），则应该降级为 DEBUG。

典型 DEBUG 场景：

• 位置检查："检查位置是否在保护区域内"
• 坐标加载："队伍 {} 出生点配置: x={}, y={}, z={}"
• 伤害处理："玩家 {} 受到伤害: 类型={}, 伤害值={}"
• 资源加载："资源点 {} 位置加载成功"

异常处理

// ❌ 错误
try {
    // ...
} catch (Exception e) {
    logger.error("出错了: " + e.getMessage());
    e.printStackTrace();
}

// ✅ 正确
try {
    // ...
} catch (Exception e) {
    logger.error("出错了: {}", e.getMessage(), e);
}

日志前缀规范

模块	前缀
EnderRealmServerCore	[EnderRealm]
BedWars	[BedWars]
Disaster	[Disaster]
BlockedInCombat	[BlockedInCombat]

子系统可追加前缀：

LoggerAPI logger = plugin.getLoggerAPI().withPrefix("[BedWars:Generator]");
// 输出: [BedWars:Generator] 产矿机已启动

注意：前缀会自动添加，不要在消息中重复：

// ❌ 错误
logger.info("[BedWars] 游戏开始");

// ✅ 正确
logger.info("游戏开始");
// 输出: [BedWars] 游戏开始