作者声明：创作过程中使用了AI辅助

平时写业务或者造框架的时候，反射肯定少不了。依赖注入、ORM、序列化这些底层全靠它撑着。但大家一直都在吐槽“反射慢”，它到底能有多慢？有救吗？

最近专门花时间跑了个微基准测试，把老熟人 Method.invoke 和稍微新一点的 MethodHandle 拉出来溜了溜。为了摸清底细，我不仅测了“直接调”和“加缓存”的性能差距，还把反射里的各个前置操作（比如查字段、查方法、读写属性）全拆开测了一遍。

测试场景

先简单交代下测试场景： 我搞了个很普通的 Target 类，里面有公共字段 value、私有字段 hidden 和一个普通的 add 方法。

测试参照组是我们平时手写的直接调用（比如直接 target.add(a,b) ）。 而反射组除了测最终的执行（Call/Read/Write），还把寻找元数据的过程（比如 Class.forName，或者 getMethod）也单独拿出来算了开销。

测试数据

咱们直接上最原始的跑分数据。这里分为四种情况，大家可以重点对比“反射平均耗时”和“直接平均耗时”这两列。

1. Method.invoke（非缓存）

这种情况就是平时最容易踩坑的写法，每次操作都重新去拿元数据。

2. Method.invoke（缓存）

只要把 Method 或者 Field 提前提出来，你看看底下读写和调用的耗时降了多少。

3. MethodHandle（非缓存）

新宠 MethodHandle 登场。如果在循环里现抓现用，不仅不快，反而更惨。

4. MethodHandle（缓存）

提前准备好 Handle 后，它的威力才真正发挥出来。

个人体会

看着上面的表格，不知道你有什么感觉？我个人的最大体会是下面这几点：

1. 缓不缓存，那就是天与地的差别 你看数据，只要把 Method 或者 MethodHandle 提前缓存下来，真正调用时的耗时直接掉到了 3~11ns！虽然比直接调用（0~2ns）还是慢一丢丢，但这几纳秒的差距在绝大多数业务代码里根本感受不到，基本等同于热点代码的性能。 如果不缓存，每次都要走一遍安全检查和查表，开销直接放大十几甚至上百倍。

2. MethodHandle 真的比 invoke 强吗？

• 缓存情况下：两者基本五五开，MethodHandle 确实略占上风（3~4ns vs 4~11ns）。
• 非缓存情况下：MethodHandle 反而吃瘪了。因为它在 unreflect 动态生成 LambdaForm 的时候，第一步的代价比老反射还要高。
• 顺带一提，我这里测试用的是带类型转换的 mh.invoke()，如果你的场景极其严苛，可以用 invokeExact，性能还能再榨出几滴来。

3. “内省”这玩意儿是真的重 仔细看表格里 Get Property 和 Read/Write Property 这几项，只要沾上 PropertyDescriptor 去走内省解析，反射耗时直接飙到 600~900ns。底层各种机制全套跑下来，开销极大，属于性能重灾区。

几条建议

根据这些数据，以后咱们写反射代码或者封装小框架时，可以参考下面这几套连招：

• 能缓存就绝对不现查。 拿到 Method 或 MethodHandle 后，赶紧扔进 ConcurrentHashMap 或者提升为静态常量。这一步做好了，性能问题就解决 90% 了。
• 避开 PropertyDescriptor 这种重武器。 如果是在高频调用的热路径里，别用内省去推断 getter/setter。老老实实拼接方法名，用 getMethod 查出来存好，会快得多。
• 热点路径优先上 MethodHandle。 配合 invokeExact 加上提前预绑定（bindTo 或者 asType），能让你获得极其接近原生代码的性能体验。

(最后叠个甲：测试是在 Windows + JDK 17 下跑的，没上 JMH，System.nanoTime 可能会有抖动。所以数值大家看看就好，主要是感受一下各个操作相对的量级差距。)

作者声明：创作过程中使用了AI辅助

上篇：Fabric 模组开发：怎么用反射搞定多版本兼容？

上篇聊了反射框架，但有个前置问题没解决：既然整个反射体系的前提是“不能引入任何MC依赖”，Forge包又和Minecraft强绑定，那主类上的@Mod注解怎么过编译？

答案就是Compile-Time Stub。

为什么必须用Stub？

在纯反射框架下，由于Forge包与Minecraft强绑定的特性，我们不能引入真的Forge包。

但Forge模组入口点是由@Mod注解定义的，这时候就要用到Stub。

Stub的本质是：给编译器一个假契约，运行时由Loader提供真类。

关键要点

@Retention(RetentionPolicy.RUNTIME) // 必须！否则Loader扫不到
@Target(ElementType.TYPE)
public @interface Mod {
    String value(); // 只保留Loader扫描必需的最小属性
}

三条铁律：

1. 包名精确匹配 net.minecraftforge.fml.common.Mod
2. 绝不打包进JAR —— Gradle里 jar { exclude 'net/minecraftforge/**' }
3. 不写default值、不加多余属性 —— 保持最小契约，防止误用

一句话总结

Stub不是“简化版Forge API”，而是编译期占位符。它让你在不触碰任何真实Forge类的情况下，依然能写出合法的@Mod标注类。配合上篇的反射体系，才算真正闭环。

该渲染由 Cyber API 生成，可能存在排版问题，最佳体验请前往：https://blog.star-dust.link/notes/3

OpenCode Go API request failed (HTTP 500) for qwen3.8-max: {"type":"Router.Unavailable","modelID":"qwen3.8-max"}

看完了？说点什么呢

作者声明：文章创作过程中使用了AI辅助

本文的正经风格版本：https://blog.star-dust.link/posts/note/fabric-mod-reflection-multi-version-compatibility

第一章：为什么要当邪修？

因为正道太累了啊！

你看那些名门正派的Fabric弟子，每天对着Mixin注解磕头拜佛，AccessWidener写得比情书还长，Gradle配置调得比炼丹炉还复杂。结果呢？MC一更新，全部白给！1.21写的模组到26.1直接原地飞升，连个全尸都不留。

而我们邪修不一样。我们没有信仰，没有底线，没有import net.minecraft.*。我们只有一样东西——

反射。

这玩意儿就像修仙界的"万能钥匙"，虽然脏、虽然慢、虽然随时可能炸膛，但它能用。编译期看不到MC的类？没关系，运行时硬抢！方法名改了？没关系，挨个试！参数类型不对？没关系，动态代理糊脸！

邪修的核心理念就八个字：活着就行，管他姿势。

第二章：邪修三件套

2.1 常量层：你的"通缉令"

把所有版本里变来变去的类名、方法名、字段名，全部写进一个巨大的常量表里。这张表就是你的"仇人名单"，上面记满了MC每次更新欠下的债。

// 邪修の仇人录
static final String C_LEVEL       = "net.minecraft.world.level.Level";
static final String C_COMPONENT   = "net.minecraft.network.chat.Component";
static final String M_GET_UUID    = im("Entity", "getUUID", "()Ljava/util/UUID;", "method_5667");
static final String M_LITERAL     = im("Component", "literal", "(Ljava/lang/String;)LComponent;", "method_43470");

记住：业务代码里绝对不能出现任何硬编码的MC类名。一旦出现，你就破了戒，离走火入魔不远了。

2.2 反射层：你的"作案工具"

这一层封装所有脏活累活。Class.forName、Method.invoke、Field.get……这些见不得光的操作全部藏在这里，对外只提供人话接口。

关键技巧：

缓存一切：反射调用一次就够了，第二次还用就是浪费生命。用ConcurrentHashMap存起来，找不到的也要存个NOT_FOUND哨兵，不然每次都重新扫描，JVM会骂你。

描述符必须带：找方法不带描述符等于裸奔。getUUID()混淆后可能是method5667也可能是method5845，一个返回UUID一个返回String，猜错了当场社死。

重载方法要遍历：别傻乎乎只缓存第一个匹配到的方法。把所有同名方法都捞出来，调用时用isInstance逐个验身，谁对得上就用谁。

2.3 业务层：你的"伪装身份"

这一层看起来和正常模组一模一样。getBlockState()、sendMessage()、checkPermission()……全是人话，干干净净。

但只有你自己知道，这些人话底下藏着多少反射。

第三章：邪修实战骚操作

3.1 环境探测：先搞清楚自己在哪

Fabric生产环境用intermediary名，MC 26+又改回named名。你得先知道自己身处哪个平行宇宙：

// 使用神识探查一下当前是不是 named 运行时
static final boolean IS_NAMED = tryLoad("net.minecraft.world.level.Level") != null;

然后查表回退：先试named名，不行就翻"仇人录"找intermediary名。intermediary名跨版本稳定，是你最后的保命符：

static Class<?> forName(String name) {
    // 1. 缓存命中直接返回（含 NOT_FOUND 哨兵）
    Object cached = CACHE.get(name);
    if (cached != null) return unwrap(cached);

    // 2. 先试 named 名，再试 intermediary 兜底
    Class<?> cls = tryLoad(name);
    if (cls == null) cls = tryLoad(Constants.toInter(name));

    // 3. 存结果，找不到也要存哨兵防无限重试
    CACHE.put(name, cls != null ? cls : NOT_FOUND);
    return cls;
}

3.2 事件监听：动态代理捏脸术

Fabric的事件回调接口里全是MC原生类，编译期根本import不了。怎么办？不implements了，直接捏！

用JDK动态代理在运行时现场造一个假对象塞进去。代理对象收到回调后，把参数打包成Object[]扔给业务层慢慢拆：

// 运行时捏个假监听器，彻底斩断编译期类型依赖
Object proxy = Proxy.newProxyInstance(loader, new Class[]{listenerIfc}, (p, m, args) ->
    m.equals(targetMethod) ? handler.handle(args) : handleObjectMethods(p, m, args)
);
registerMethod.invoke(eventObj, proxy);

这招的精髓在于：只要我不承认依赖存在，依赖就不存在。我们把它叫做薛定谔的类型安全。

3.3 多策略兜底：一条路走到黑不如多条路走到亮

获取方块ID为例：

static String getBlockId(Object state) {
    Object block = call(state, "getBlock");
    if (block == null) return "minecraft:air";

    // 策略1：toString 硬抠（全版本通用保底）
    String s = block.toString(); // Block{minecraft:diorite}
    int b = s.indexOf('{'), e = s.indexOf('}');
    if (b >= 0 && e > b) return s.substring(b + 1, e);

    // 策略2：反射查注册表（新旧API自动兼容）
    String id = getFromRegistry(block);
    return id != null ? id : "minecraft:air";
}

先试新API BuiltInRegistries，抛异常了？换老API Registries，又抛了？用toString()硬抠字符串（Block{minecraft:diorite} → minecraft:diorite），还不行？返回minecraft:air，假装什么都没发生。

邪修的信条：优雅地失败 > 粗暴地崩溃。

3.4 文本组件兼容：新旧两开花

老版本new TextComponent("hello")，新版本Component.literal("hello")。写个兼容方法：

// 新版 Component.literal() 失败就降级旧版 new TextComponent()
static Object text(String s) {
    try { return invokeStatic("Component", "literal", s); }
    catch (Exception e) { return newInstance("TextComponent", s); }
}

注意：这里Componentliteral和newTextComponent都是反射拿到的，编译期依然干干净净。邪修的代码，永远不能被编译器抓到把柄。

第四章：邪修禁忌

忌到处散落反射调用：不封装的反射就像没穿衣服上街，迟早出事。

忌信任单一API：MC的承诺比渣男的誓言还不靠谱，永远准备Plan BCD。

忌忽略性能：不做缓存的反射修士，活不过筑基期。

忌忘记哨兵：ConcurrentHashMap不能存null，不设NOT_FOUND占位符，你会陷入无限重试的地狱轮回。

忌跟正道修士争论：他们不懂你的苦，你也不必解释。默默写完兼容代码，看他们的模组在下个版本集体暴毙，然后微微一笑。

终章：邪修的归宿

这套体系搭完，你就能实现：

✅ 编译期零MC依赖

✅ 单JAR通吃1.18到26+

✅ 不用Mixin、不用AW、不看官方脸色

✅ 在别人模组集体阵亡时独自存活

代价是什么？

❌ 代码可读性约等于天书

❌ 调试时堆栈信息像乱码

❌ 新人接手时会诅咒你十八代祖宗

❌ 你永远无法理直气壮地说"我写的是正经模组"

但没关系。

邪修不需要认可，只需要运行。

当你看到自己的模组在数个大版本更新后依然顽强地加载成功，而隔壁正道修士还在Discord里哭诉Mixin冲突时——

那一刻，你就知道，这条路，走对了。

作者声明：创作过程中使用了AI辅助

搞 Fabric 开发的小伙伴可能都遇到过一个头疼的问题：Minecraft 每个大版本更新，底层代码就像重写了一样。如果你想弄一个一套代码兼容 1.18 到 26.1+ 的模组，还不能用 Mixin，甚至编译的时候连 Minecraft 的 jar 包都引用不了，还怎么玩？

今天咱就来聊聊，在这种极端约束下，怎么纯靠反射搭起一套稳健的多版本兼容体系。

一、为什么非得用反射？

MC 版本更新对底层类的重构可以说是毫不留情。举个例子，跨几个版本你会发现类名、包名全变了：

有时候我们的开发环境非常受限，比如：

1. 编译期压根没有 MC 的环境：你可能在写一个 Bukkit/Fabric 双端通用的插件，主项目是基于 Bukkit API 编译的，没法直接 import net.minecraft.*。
2. 没法用 Mixin：只能走 Fabric 暴露出来的公开 API 表面（比如事件、注册表、命令）。
3. 单 JAR 走天下：打出来的一个包，得在各种版本的服务器上都能跑。

遇到这种“戴着镣铐跳舞”的情况，反射就成了咱们唯一的救命稻草。

二、别乱写反射，分层是关键

几万行代码如果到处塞满 Class.forName 和 Method.invoke 绝对会让人抓狂。比较靠谱的做法是把代码拆成三层：

┌─────────────────────────────────────────────────────────┐
│  业务层  Platform / Listener / ...                       │
│         只管叫“人话”（如 getBlockState），不关心底层名字    │
├─────────────────────────────────────────────────────────┤
│  反射层  ReflectionUtils                                 │
│         提供 forName / call / findMethod / ...          │
│         内置缓存、父类回退、参数扫描                      │
├─────────────────────────────────────────────────────────┤
│  常量层  ReflectionConstants                             │
│         集中管理所有类名/方法名/字段名，负责不同映射间的转换  │
└─────────────────────────────────────────────────────────┘

这样分层最大的好处是：脏活累活全被常量层扛了。多版本的差异被死死锁在底层，业务代码看着依旧清爽。

三、找类：named 怎么转 intermediary？

Fabric 生产环境把类名改成了 intermediary，但到了 MC 26+，官方又给改回了 named/mojang 名。所以第一步，你得知道现在的运行环境到底用哪套名字。

我们去找一个只在 named 运行时才存在的类：

private static final boolean IS_NAMED_RUNTIME;
static {
    FabricLoader fl = FabricLoader.getInstance();
    boolean namedRt = false;
    try {
        // MC 26+ 上 named 类是运行时类；1.18–1.21 只有 intermediary 的 class_NNNN
        Class.forName("net.minecraft.world.level.Level");
        namedRt = true;
    } catch (ClassNotFoundException ignored) {}
    IS_NAMED_RUNTIME = namedRt;
}

拿到环境状态后，咱就可以弄个回退机制了。先试 named 名，不行就查表回退到 intermediary 名：

static Class<?> forName(String namedClassName) {
    Object cached = classCache.get(namedClassName);
    if (cached != null) return unwrap(cached);

    Class<?> cls = tryLoad(namedClassName);          // 1) 先试 named 名
    if (cls != null) { classCache.put(namedClassName, cls); return cls; }

    // NAMED_TO_INTER 是一张硬编码的表，记录了常用类的 intermediary 映射
    String inter = Constants.toIntermediaryClass(namedClassName);
    if (inter != null && !inter.equals(namedClassName)) {
        cls = tryLoad(inter);                        // 2) 不行就试 intermediary 名
        if (cls != null) { classCache.put(namedClassName, cls); return cls; }
    }
    classCache.put(namedClassName, NOT_FOUND);
    return null;
}

为啥要查表？因为 intermediary 名（class_NNNN）在所有大版本更新时是跨版本稳定的，用它做兜底最合适不过。

四、找方法：参数扫描与别名表

类名搞定了，方法和字段更恶心。同一个方法，在这叫 method_123，到另一个版本可能就换地方了，比如disconnect。解决这个得靠两步走战略。

1. 必须带描述符（descriptor） 方法名解析如果不带描述符，很容易翻车。比如找个 getUUID()，混淆后谁知道返回的是 UUID 还是 String？必须精确匹配：

static final String M_GET_UUID = im("net.minecraft.world.entity.Entity", "getUUID",
    "()Ljava/util/UUID;", "method_5667"); // 5667 -> UUID, 5845 -> String

2. 搞个方法名重定向表 很多逻辑在不同版本不仅混淆名变了，连语义名都变了。我们可以在表里把它们都指到一个标准名上，这样业务层就不用操心了：

putM("getPlayerList",       M_GET_PLAYER_LIST);
putM("getPlayerManager",    M_GET_PLAYER_LIST);    // 1.18 的叫法
putM("getWorld",            M_GET_LEVEL);          // 1.18 的别名
putM("refreshPositionAfterTeleport", M_SET_POS);   // MC 26 的别名

五、事件监听怎么破？用动态代理

碰到 Fabric 的事件回调接口（比如 PlayerBlockBreakEvents$After），里面的方法参数全是 MC 原生类，编译期根本没法 import。怎么办？这里有个黑科技：JDK 动态代理。

咱们不直接 implements 这个接口，而是在运行时动态捏一个代理对象传进去：

private static void registerEvent(String eventClassName, String fieldName,
                                  String listenerInterfaceName, CallbackAdapter handler) {
    Class<?> eventCls = forName(eventClassName);
    Object eventObj = eventCls.getField(fieldName).get(null);

    Class<?> listenerInterface = forName(listenerInterfaceName);
    final Method abstractMethod = findAbstractMethod(listenerInterface); // 找到那个唯一的事件回调方法

    Object proxy = Proxy.newProxyInstance(
        eventCls.getClassLoader(),
        new Class<?>[]{listenerInterface},
        (proxyObj, method, args) -> {
            // equals, hashCode 那些不管，只管事件方法
            if (!method.equals(abstractMethod)) return handleObjectMethods(proxyObj, method, args);
            // 把原始参数 args 全打成 Object[] 丢给业务层自己用反射慢慢拆
            return handler.handle(args);   
        });

    registerMethod.invoke(eventObj, proxy);
}

这招直接斩断了编译期的类型依赖，完美绕过限制！当然，不同版本的参数个数可能不一样，业务层拆包的时候记得判断一下 args.length。

六、坑点：重载方法的匹配陷阱

很多插件或模组的 API 都有重载方法，比如权限检查：一个接 CommandSourceStack，一个接 Entity。

如果你傻乎乎地只缓存第一个拿到的 Method，等运行的时候，传了个 Entity 进去，人家实际上要的是 CommandSourceStack 的那个方法，当场就会给你糊一脸 IllegalArgumentException。

正确的玩法是：把所有重载全找出来缓存好，每次调用前，拿 param[0].isInstance(source) 挨个验一下身：

static boolean checkPermission(Object source, String node) {
    for (Method m : findAllCheckMethods()) {          // 取出所有 check() 的重载
        Class<?> sourceType = m.getParameterTypes()[0];
        if (!sourceType.isInstance(source)) continue; // 匹配当前 source 的真实类型
        try {
            return (Boolean) m.invoke(null, source, node);
        } catch (Throwable t) { ... }
    }
    return false;
}

谁匹配得上就用谁，这样就稳如老狗了。

七、多策略兜底：拿方块 ID 的玄学

在跨版本环境中做操作，最稳妥的方式永远是“多策略兜底”。以获取方块 ID 为例：

private static String getBlockId(Object blockState) {
    Object block = call(blockState, "getBlock");
    if (block == null) return "minecraft:air";
    
    // 策略 1：老老实实用 toString() 抠字符串。
    // Block.toString() 往往会吐出 "Block{minecraft:diorite}"，所有版本都通用且可靠！
    String s = block.toString();
    int brace = s.indexOf('{');
    int close = s.indexOf('}');
    if (brace >= 0 && close > brace) return s.substring(brace + 1, close);
    
    // 策略 2：反射注册表（这里还得兼容 BuiltInRegistries 和老版的 Registries）
    String id = getFromRegistry(block);
    if (id != null) return id;
    
    return "minecraft:air";
}

创建文本组件也是同理：老版本发消息用 new TextComponent()，新版本这玩意直接没了，变成了 Component.literal()。写兼容方法的时候，先试新 API，抛异常了再试旧 API，确保能在不同版本平滑过渡。

八、榨干性能：缓存与哨兵

都说反射慢，那是没做缓存。把找出来的 Class、Method、Field 全塞进 ConcurrentHashMap 里就行了。

不过要注意，ConcurrentHashMap 里不能存 null。如果某个版本确实没这个方法，每次查找都会失败，每次都会重新走一遍全量扫描。所以咱们得整个 NOT_FOUND 的哨兵对象当占位符：

private static final Object NOT_FOUND = new Object();
// 找不着就存它，下次看见它直接绕道走

总结

盘点一下，这套纯反射的兼容玩法其实就几个核心套路：

1. 把恶心的版本差异全关进常量层，业务代码该怎么写怎么写。
2. 多策略兜底，新 API 走不通走旧 API，旧 API 走不通走字符串硬抠。
3. 动态代理大法好，绕开编译期依赖全靠它。
4. 遇到重载方法，用 isInstance 动态匹配，别死磕一个。
5. 缓存 + 占位符，把反射的性能开销降到最低。

这套体系搭下来，哪怕编译期连一个 MC 的原生类都见不到，一样能把 Fabric 的多版本兼容拿捏得死死的。虽然前期写起来比直接用 Mixin 折腾点，但在特定场景下（比如单 JAR 双端通吃），这确实是最灵活的方案。

希望能帮大家少掉几根头发！

补充篇：Forge反射模组开发：用Stub绕过@Mod注解导入（补充篇）

收到可疑邮件

最近，我收到了来自renvolve.biz的这样一封看似专业的邮件：

Hi [我的名字],

Your work weaving GLSL and TypeScript feels both precise and creatively flexible, 
a rare combo for a developer balancing raw graphics with clean logic.

What's the most stubborn technical hurdle you're currently facing in that stack, 
whether it's a missing tool or a backlog item you keep manually patching?

We are the engineers behind renvolve, and if there's a way we could build something 
or take a load off your plate, our CEO would love to grab a quick chat.

Thanks,
Sarah

乍一看，这封邮件似乎很专业：

• 提到了我在Github开源仓库使用的具体技术栈（GLSL + TypeScript）
• 使用了个性化的恭维
• 语气友好且专业
• 提出了一个看似合理的"合作"请求

但这一切很可能都是精心设计的陷阱。

深入调查

出于好奇和警惕，我对这个域名进行了调查，结果令人担忧：

危险信号 #1：极低的信任评分

• ScamAdviser 评分：23/100
• 被多个安全网站标记为"可疑网站"

危险信号 #2：新注册的域名

• 域名注册时间仅约 28 天
• 这是诈骗网站的典型特征——使用新域名来避免负面历史记录

危险信号 #3：匿名运营

• 很难确定谁真正运营该网站
• 缺乏透明的公司信息或团队介绍

危险信号 #4：无实际业务痕迹

• 网站上没有真实的产品或服务展示
• 没有可验证的客户案例或合作伙伴

这些都表明这很可能是一场诈骗活动。

如何防范

收到类似邮件时，请执行以下检查：

□ 检查发件人域名的信誉评分
□ 搜索公司名称 + "scam" 或 "fraud"
□ 在 LinkedIn 上查找声称的联系人
□ 查看公司网站是否有真实业务内容
□ 检查域名注册日期（使用 whois 查询）
□ 不要点击任何链接，先独立搜索公司信息

作者声明：创作过程中使用了AI辅助

以下提及的项目全部是 Minecraft 模组或插件项目。

引言

把一套 Bukkit 命令系统搬到 Fabric 时，最劝退的不是 Brigadier 本身，而是要为了一个平台把所有命令逻辑全部重写一遍的痛苦。

由于之前有给一个其他项目写多平台的经历，因为那个项目代码少所以各平台的逻辑全部重复写了很多遍，造成更新时需要修改所有平台的代码，非常痛苦，因此这次给项目做多平台兼容没有使用这种方法，而是构建了 core 和 common 桥接接口。

但在编写 Fabric 平台逻辑的时候又遇到了 Brigadier 给每个命令建节点的问题，那不又回到了痛苦的重复工作吗？这事我当然不想干。

项目的 core 层早就定型了，权限校验、参数解析、补全逻辑全在那儿。如果按 Brigadier 原生写法给每个子命令建节点，等于把同样的业务用另一种范式再表达一次，以后改命令还得同步维护两套代码。这不是技术问题，是体力活。

因此我选择了让 Brigadier 当个收口，其他的事还是交给 core 管。

开发

用 greedyString 当万能容器

别为每个子命令建 LiteralArgumentBuilder。用一个 greedyString() 把用户输入的所有东西原样吞下来，再丢给 core 切分：

RequiredArgumentBuilder arg = RequiredArgumentBuilder
    .argument("args", StringArgumentType.greedyString());

arg.executes(ctx -> {
    String raw = StringArgumentType.getString(ctx, "args");
    return commandExecutor.onCommand(ctx.getSource(), parseArgs(raw)) ? 1 : 0;
});

选 greedyString() 而不是普通 string()，是因为它遇到空格不会停。/<command> kick player reason with spaces 这种带空格的参数才不会被截断。

空参数兜底

上面那段代码有个盲区。只敲 /<command> 不带参数时，greedyString 节点不会被匹配，arg.executes 根本不会触发。

必须在根节点单独挂一个 executes：

literal.then(arg);
// 处理 /<command> 后面没跟参数的情况
literal.executes(ctx -> 
    commandExecutor.onCommand(ctx.getSource(), new String[0]) ? 1 : 0
);

防御性解析

既然要手动切字符串，就别信 split(" ")。在聊天框多敲两个空格是常事，直接 split 会产生空字符串元素，下游分分钟数组越界。

static String[] parseArgs(String input) {
    if (input == null || input.trim().isEmpty()) return new String[0];
    List<String> tokens = new ArrayList<>();
    for (String s : input.trim().split("\\s+")) {
        if (!s.isEmpty()) tokens.add(s);
    }
    return tokens.toArray(new String[0]);
}

\s+ 处理连续空白，trim() 干掉首尾。

命令补全

Brigadier 的 suggests 是异步的，但返回值本质就是字符串列表。我项目 core 层的 onTabComplete 返回的也是 List<String>，两者可以直接对接：

arg.suggests((ctx, builder) -> {
    List<String> completions = commandExecutor.onTabComplete(
        ctx.getSource(), 
        parseArgs(builder.getInput())
    );
    if (completions != null) completions.forEach(builder::suggest);
    return builder.buildFuture();
});

代价是客户端没有语法高亮，因为服务端没下发完整语法树。但补全内容是对的，对于后台管理工具来说够用了。

总结

什么时候该这么干

说清楚边界比假装万能更重要。

适合的场景：有现成的跨平台 Core、从 Bukkit 迁移、命令体系已经稳定且数量较多。

不适合的场景：纯 Fabric 新项目、命令结构简单、需要客户端语法高亮和自动帮助生成。

Brigadier 原生 API 在设计上确实更优雅。但工程决策不是选最优雅的，是选最省事的。当你的约束条件决定了重写成本远高于兼容成本时，“不够优雅”就是当下最合理的方案。

测试Cyber主题Lexical功能兼容性。

NOTE

这是Note

print("Hello Lexical")

Tag 1

::: note

:::

最近发现了一个很喜欢的博客框架Mx Space，于是准备把之前的框架换掉，由于官方文档实际上过时，中间踩了很多坑。

坑1：Docker Ccompose中健康检查调用的API版本不对 在Mx Space Core v13中，API已由v2升级为v3，但官方文档给出的命令拉到的docker-compose.yml中仍为v2，导致容器状态一直为starting。

解决方法：在docker-compose.yml中将http://127.0.0.1:2333/api/v2/ping中的v2改为v3

坑2：配置与云函数已改名 在老版本的Mx Space的「配置与云函数」已改名为「代码片段」，导致我一开始一直没找到添加前端所需云函数的页面。

坑3: 需要发表一篇笔记api/v3/aggregate才能正常工作 如果不发布笔记, api/v3/aggregate的返回为NOT_FOUND。