ionet 框架：Java 方法即 Action 的零学习成本之道

区别在哪里？

1. ionet 的 Action 同时支持 TCP、WebSocket、UDP，你的一套代码可以服务所有连接方式
2. ionet 不需要 HTTP 协议栈，通信延迟在纳秒 ~ 微秒级别
3. ionet 的路由是数字，比字符串路由更高效，也更适合游戏和实时系统

避免类爆炸

传统的网络框架（尤其是游戏服务器框架）通常要求你为每种消息类型创建一个 Handler 类。当你有 200 个业务接口时，就有 200 个 Handler 类。这就是类爆炸。

ionet 的做法完全不同。你可以在一个 Action 类中定义多个方法，每个方法处理一种业务：

@ActionController(1)
public class DemoAction {
    @ActionMethod(0)
    private HelloMessage here(HelloMessage helloMessage) {
        helloMessage.name = helloMessage.name + ", I'm here";
        return helloMessage;
    }

    @ActionMethod(1)
    private HelloMessage jackson(HelloMessage helloMessage) {
        ErrorCode.nameChecked.assertTrue("Jackson".equals(helloMessage.name));
        helloMessage.name = "Hello, " + helloMessage.name;
        return helloMessage;
    }

    @ActionMethod(2)
    private List<HelloMessage> list() {
        return IntStream.range(1, 5).mapToObj(id -> {
            HelloMessage msg = new HelloMessage();
            msg.name = "data:" + id;
            return msg;
        }).toList();
    }
}

3 个业务接口，1 个类，3 个方法。清晰、紧凑、易维护。

断言 + 异常机制 = 清晰简洁的代码

在传统开发中，业务校验代码通常长这样：

// 传统写法：if-else 地狱
public Result login(LoginRequest request) {
    if (request.getName() == null) {
        return Result.fail(400, "名字不能为空");
    }
    if (!"Jackson".equals(request.getName())) {
        return Result.fail(100, "名字必须是 Jackson");
    }
    // 终于开始写业务了...
    return Result.success(new UserMessage("Hello, " + request.getName()));
}

在 ionet 中，你只需要：

// ionet 写法：断言 + 异常机制
@ActionMethod(1)
private HelloMessage jackson(HelloMessage helloMessage) {
    ErrorCode.nameChecked.assertTrue("Jackson".equals(helloMessage.name));
    helloMessage.name = "Hello, " + helloMessage.name;
    return helloMessage;
}

如果断言失败，框架自动将错误码返回给客户端。 你不需要 try-catch，不需要封装 Result 对象，不需要写任何错误处理代码。

错误码通过枚举统一管理：

public enum ErrorCode implements ErrorInformation {
    nameChecked(100, "The name must be Jackson");
    final int code;
    final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    @Override
    public String getMessage() {
        return this.message;
    }

    @Override
    public int getCode() {
        return this.code;
    }
}

这套机制的好处是：

1. 业务代码中没有错误处理的干扰，逻辑一目了然
2. 错误码集中管理，不会散落在各个方法里
3. 客户端总能收到规范的错误响应，不会出现"500 Internal Error"的尴尬

JSR380：告别参数校验的 if-else

ionet 支持 JSR380（Bean Validation）规范。你可以在协议类上直接使用 @NotNull、@Min、@Max 等注解：

@ProtobufClass
public class LoginVerifyMessage {
    @NotNull(message = "jwt 不能为空")
    public String jwt;
}

当客户端发来的数据不符合校验规则时，框架会自动拦截并返回错误信息。你的业务方法里不需要写任何 if-else。

对比一下：

// 不用 JSR380
@ActionMethod(0)
private UserMessage login(LoginVerifyMessage message) {
    if (message.jwt == null) {
        throw new RuntimeException("jwt 不能为空");
    }
    if (message.jwt.length() > 200) {
        throw new RuntimeException("jwt 太长了");
    }
    // 真正的业务逻辑...
}

// 用 JSR380
@ActionMethod(0)
private UserMessage login(LoginVerifyMessage message) {
    // 直接写业务逻辑，参数已经验证通过了...
}

二者的区别就是：你的方法只包含业务逻辑，验证规则由注解声明。

开发神器：控制台代码导航

当你启动 ionet 服务器时，控制台会打印出所有注册的 Action 信息：

┌──────── action ──────────────────────────────────── │ cmd: 1 - DemoAction │ │ 1-0 here(HelloMessage) => HelloMessage │ DemoAction.java:12 │ │ 1-1 jackson(HelloMessage) => HelloMessage │ DemoAction.java:18 │ │ 1-2 list() => List<HelloMessage> │ DemoAction.java:25 └──────────────────────────────────────────────────── 

这段输出告诉你：

• 每个 Action 的路由（1-0、1-1、1-2）
• 对应的类名和方法名
• 参数类型和返回值类型
• 代码行数（点击可直接跳转到 IDE 中对应的代码）

在多人协作的项目中，你不需要搜索代码库就能知道所有 Action 在哪里。这个特性由 DebugInOut 插件提供。

一套代码，多种连接方式

ionet Action 的另一个强大之处在于协议无关性。同一段业务代码，无需任何修改就能支持：

• TCP 连接
• WebSocket 连接
• UDP 连接

这意味着，你不需要为不同的客户端写不同的接口。无论是用 Godot 开发的端游（TCP），还是用 React 开发的 Web 端（WebSocket），还是用 Unity 的移动端（UDP），它们都能调用同一个 Action。

未来如果 ionet 支持了 KCP 或 QUIC，你现有的业务代码也无需任何改变。

同样的原则也适用于数据协议

ionet 不仅让你一套代码支持多种连接方式，还能让你一行代码切换数据协议：

// 从 Protobuf 切换到 JSON —— 只需要改配置，业务代码不变

无论你用 Protobuf 还是 JSON，业务方法的写法完全相同。这在需要兼容多种客户端的项目中非常有用。

小结

ionet 的"零学习成本"不是一句空话，它体现在每一个设计决策中：

这些特性组合在一起，产生的效果是：你把精力集中在业务逻辑上，框架帮你处理其余的一切。

如果你是一个有 Spring MVC 经验的 Java 开发者，你可以在 10 分钟内开始用 ionet 写业务。如果你是一个完全没有网络编程经验的新手，你也只需要理解"方法参数是请求，返回值是响应"这一个概念。

这就是零学习成本。