主要更新

#46 action 业务参数与返回值增加 List 支持

action 支持 List 参数与返回值，可以有效的减少协议碎片、减少工作量等。在没有支持 List 之前的代码，如果想要传输一个列表的数据，通常需要将 pb 对象包装到另一个 pb 响应对象中。

让我们先看一个示例，这个示例中 action 方法的的逻辑很简单，将查询到的数据列表给到请求端。由于之前不支持 List 返回值，开发者想要将列表中的数据给到请求端，还需要额外的定义一个与之对应的响应类，只有这样才能将列表数据给到请求端。

我们可以想象一下，如果你的系统中有很多固定的配置数据，比如装备、道具、活动信息、英雄人物介绍、敌人相关信息、地图信息、技能信息、宠物基本信息...等等，通常会有几十、上百个这样的响应对象。

为了将这些固定的配置数据给到请求端，而建立与之对应的响应对象，想想这是一件多么无聊的一件事情。这些多出来的响应对象，就是协议碎片，是一种可有可无的协议；此外还有如下缺点：

将会变成干扰项
增加维护成本
增加工作量（每次有新的配置表都要新建、在每个 action 中，都要创建这个响应对象）

 @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class Animal {     /** id */     int id; }  @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class AnimalResponse {     List<Animal> animals; }  @ActionController(3) public class HallAction {     @ActionMethod(10)     public AnimalResponse listAnimal1() {         // 查询出列表         var list = IntStream.range(1, 4).mapToObj(id -> {             Animal animal = new Animal();             animal.id = id;             return animal;         }).collect(Collectors.toList());          // 将列表存放到 Animal 的响应对象中         AnimalResponse animalResponse = new AnimalResponse();         animalResponse.animals = list;          return animalResponse;     } }

通过上面的介绍，知道协议碎片是多么恐怖的一件事了把。其实我们的需求也很简单，只是想把列表中的数据给到请求端就可以了。此时，我们可以利用 action 将列表数据通过 List 直接返回，这样可以避免上面所说的各种缺点。同时，还可以让我们的代码更加的简洁，这种方式可以使前端与后端都受益。

用更少的代码实现了同样的功能，减少了工作量，避免了协议碎片。这样，开发者就不在需要额外的建立一个与之对应的响应协议了；当使用了框架提供的 List 返回值后，可以帮助你的系统减少几十、上百个类似 xxxResponse 的协议。

来，让我们看看修改后的代码是有多么简洁的吧。这种编码方式，即使你是一个新手，也能快速的看懂；

 @ActionController(3) public class HallAction {     @ActionMethod(9)     public List<Animal> listAnimal() {         // 查询出列表         return IntStream.range(1, 4).mapToObj(id -> {             Animal animal = new Animal();             animal.id = id;             return animal;         }).collect(Collectors.toList());     } }

#74 action 返回值增加 byte[] 扩展

action byte[] 使用展示

 @ActionController(1) public class DemoAction {     static byte[] helloReqData;      static {         // 这里模拟缓存数据，不用每次序列化         HelloReq helloReq = new HelloReq();         helloReq.theIndex = 100;         helloReq.name = "to byte[]";         helloReqData = DataCodecKit.encode(helloReq);     }      @ActionMethod(4)     public byte[] testByte() {         return helloReqData;     } }

#79 light-jprotobuf 模块支持枚举

miaozhiyan 贡献的 #79

 // 动物 message Animal {   // id   int32 id = 1;   // 动物类型 - 枚举测试   AnimalType animalType = 2; }  // 动物类型 enum AnimalType {   // 鸟   BIRD = 0;   // 猫   CAT = 1; }

对应的 java 代码

 @ProtobufClass public enum AnimalType {     /** 鸟 */     BIRD,     /** 猫 */     CAT; }  @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class Animal {     /** id */     int id;     /** 动物类型 - 枚举测试 */     AnimalType animalType; }

#84 生成proto文件时,内容的顺序总是产生变化

hia 贡献的 #84

实际使用过程中发现一个问题如下:当协议没有任何变化时,生成的协议文件依然会产生顺序变化.

例如:当前的协议定义有 A,B,C 三个类。如果对协议进行多次生成,产生的proto文件内的定义顺序可能是:A,C,B 或者 B,C,A

其他更新

<netty.version>4.1.91.Final</netty.version>

ExternalMessage.proto 新增 message ByteValueList，用于接收与发送 List 类型的数据

 ... 省略部分代码 // pb 对象 list 包装类 message ByteValueList {   // pb 对象 List、pb 对象 Array   repeated bytes values = 1; }

注意事项

此版本在游戏对外服协议中新增了 message ByteValueList 来支持 action 返回 List 类型，因此需要前端同学同步一下协议文件。

对外服的协议说明： https://www.yuque.com/iohao/game/xeokui

标记废弃的

将 IoGameGlobalSetting.me() 方法标记为废弃的，将 IoGameGlobalSetting 内的方法改为静态的。

此版本有 2 位开发者参与贡献

miaozhiyan 贡献的 #79

hia 贡献的 #84

ioGame 使用趋势数据统计

关注 ioGame 的游戏服务器开发者持续增多，2022-09 ~ 2023-04 月统计数据；

这里的统计信息是关于开发者关注 ioGame 框架相关的，从统计数据中可以看出，由于 ioGame 上手简单，功能强大等优点，得到了众多开发者的关注。如果你想知道 ioGame 有没有人在使用，可以先到这里看下统计数据、开发者的评价与讨论。

https://www.yuque.com/iohao/game/gpxk93#TwVa8

这里展示了每月的统计数据，统计数据来源于语雀后台，这些数据都是真实的、客观存在的、活的。

因为成本的原因，某宝某多还没有出现能提供这种服务的商家，所以这样的统计数据也更具真实性。通过统计数据，我们可以看到每天会有很多开发者在访问 ioGame 的在线文档，并且这些统计数据不是来源于口嗨的，也不是主观创造的。

所以，还在犹豫要不要使用 ioGame 的开发者们，更应该讨论的是“为什么这些开发者会选择使用 ioGame”，而不是 ioGame 有没有人在使用的问题。

maven pom

ioGame 已经上传到中央仓库，如果无法下载最新的框架源码，建议开发者的 maven 仓库代理使用原生的或腾讯云的代理，目前不推荐阿里云的代理。腾讯云代理设置可参考这里。

ioGame 最新版本查看 https://www.yuque.com/iohao/game/ab15oe

ioGame 是轻量级的网络游戏服务器框架，ioGame 没有中间件的强依赖，即无需安装任何其他的中间件产品；此时，你只需一个依赖即可获得整个框架，并同时支持开头介绍的全部功能特性。

 <dependency>     <groupId>com.iohao.game</groupId>     <artifactId>bolt-run-one</artifactId>     <version>${ioGame.version}</version> </dependency>

ioGame 网络游戏服务器框架简介

无锁异步化、事件驱动的架构设计；轻量级，无需依赖任何第三方中间件或数据库就能支持集群、分布式
通过 ioGame 可以很容易的搭建出一个集群无中心节点、集群自动化、多进程的分步式游戏服务器
包体小、启动快、内存占用少、更加的节约、无需配置文件、提供了优雅的路由访问权限控制
让开发者用一套业务代码，无需任何改动，同时支持多种通信协议：WebSocket、TCP
让开发者用一套业务代码，能轻松切换和扩展不同的通信协议：Protobuf、JSON
近原生的性能；业务框架在单线程中平均每秒可以执行 1152 万次业务逻辑
代码即联调文档、JSR380 验证、断言 + 异常机制 = 更少的维护成本
在业务开发中，提供了业务逻辑的执行信息、代码定位与跳转等
架构部署灵活性与多样性：既可相互独立，又可相互融合
可同时与同类型的多个游戏逻辑服通信并得到数据
逻辑服之间可相互跨进程、跨机器进行通信
支持玩家对游戏逻辑服进行动态绑定
能与任何其他框架做融合共存
对 webMVC 开发者友好
无 spring 强依赖
零学习成本

你是否想要开发一个高性能、稳定、易用、自带负载均衡、避免类爆炸设计、可跨进程跨机器通信、集群无中心节点、集群自动化、有状态多进程的分步式的网络游戏服务器呢？如果是的话，这里向你推荐一个由 java 语言编写的网络游戏服务器框架 ioGame。下面将会从多个方面来对框架做一些简单的介绍。

ioGame 是一个 java 网络游戏服务器框架，有以下特点：

无锁异步化、事件驱动的架构设计

支持 websocket 和 socket 两种通信协议

支持 protobuf、json 等不同的通信协议

集群无中心节点、集群自动化、分布式的设计

轻量级，不依赖第三方中间件或数据库就能支持集群、分布式

提供多种通讯方式，且逻辑服之间可以相互跨机器通信

与 spring 和其他框架融合方便

学习成本低，开发体验好

支持多服单进程、多服多进程的启动和部署方式

提供游戏文档生成的辅助功能

包体小、启动快、内存占用少

提供优雅的路由访问权限控

提供了灵活的线程扩展与设置

ioGame 是一个专为网络游戏服务器设计的轻量级框架，它可以帮助你快速地搭建和运行自己的游戏服务器。它适用于各种类型和规模的网络游戏，无论是 H5、手游还是 PC 游戏，无论是简单的聊天室，还是复杂的全球同服、回合制游戏、策略游戏、放置休闲游戏、即时战斗、MMORPG 等，ioGame 都可以满足你的需求。

ioGame 在打包、内存占用、启动速度等方面也是优秀的。打 jar 包后大约 15MB，应用通常会在 0.x 秒内完成启动，内存占用小。详细请看快速从零编写服务器完整示例。

在生态融合方面，ioGame 可以很方便的与 spring 集成（5 行代码）；除了 spring 外，还能与任何其他的框架做融合，从而使用其他框架的相关生态。

在轻量级方面，ioGame 不依赖任何第三方中间件或数据库就能支持集群、分布式，只需要 java 环境就可以运行。这意味着在使用上简单了，在部署上也为企业减少了部署成本、维护难度。使用 ioGame 时，只需一个依赖即可获得整个框架，而无需在安装其他服务，如： Nginx、Redis、MQ、Mysql、ZooKeeper、Protobuf协议编译工具 ... ...等。

在通讯方式方面，大部分框架只能支持推送（广播）这一类型的通讯方式；而 ioGame 则提供了 3 种类型的通讯方式，分别是推送、单次请求处理、逻辑服之间相互通信。其中逻辑服之间相互通信，除了可以让我们跨机器通信外，还能与同类型多个游戏逻辑服同时通信并得到结果；

在通信方面，ioGame 让开发者用一套业务代码，同时支持 WebSocket 和 TCP 两种通信协议，无需做任何改动。这意味着一个游戏服务器可以同时接入 WebSocket 和 TCP 的游戏客户端。

在通信协议方面，ioGame 让开发者用一套业务代码，就能轻松切换和扩展不同的通信协议，如 Protobuf、JSON 等。只需一行代码，就可以从 Protobuf 切换到 JSON，无需改变业务方法。

在集群方面，ioGame 的 Broker （游戏网关）采用无中心节点、自动化的集群设计，所有节点平等且自治，不存在单点故障。集群能够自动管理和弹性扩缩，节点加入或退出时，能够自动保证负载均衡和数据一致性，不影响服务可用性。

在分布式方面，ioGame 的逻辑服使用了分布式设计思想，将服务器分为游戏对外服、游戏逻辑服等不同层次，并且每一层都有明确的职责和接口。这样可以提高代码可读性和可维护性，并且方便进行水平扩展。

在学习成本方面，ioGame 的学习成本非常低，可以说是零学习成本，即使没有游戏编程经验，也能轻松上手。开发者只需掌握普通的 java 方法或 webMVC 相关知识，就能用框架开发业务。框架不要求开发者改变编码习惯，而是自身适应开发者的需求。

在开发体验方面，ioGame 非常注重开发者的开发体验；框架提供了 JSR380验证、断言 + 异常机制、业务代码定位... ...等诸多丰富的功能，使得开发者的业务代码更加的清晰、简洁；

在业务的并发方面，框架为开发者解决了单个玩家的并发问题，也提供了解决同一房间或业务内多个玩家并发问题的解决方法；框架在线程的扩展性上提供了友好的支持，并不是只能提供呆板的线程数量设置；详细请看 ioGame 线程相关。

在分布式开发体验方面，通常在开发分布式应用时是需要启动多个进程的。这会让调试与排查问题变得非常困难，从而降低开发者的效率、增加工作量等，这也是很多框架都解决不了的问题，但 ioGame 做到了！ioGame 支持多服单进程的启动方式，这使得开发者在开发和调试分步式系统时更加简单。

与前端对接联调方面，ioGame 提供了游戏文档生成的辅助功能，可以做到代码即对接文档。简单地说，当业务代码编写完后，框架会自动生成最新的文档。如果没有游戏文档的生成，那么你将要抽出一些时间来编写、维护对接文档的工作，而且当团队人数多了之后，文档就会很乱、不同步、不是最新的、忘记更新等情况就会出现。

在部署方面，ioGame 支持多服单进程的方式部署，也支持多服多进程多机器的方式部署；在部署方式上可以随意的切换而不需要更改代码。日常中我们可以按照单体思维开发，到了生产可以选择使用多进程的方式部署。

开发者基于 ioGame 编写的项目模块，通常是条理清晰的，得益于框架对路由的合理设计，同时也为路由提供了优雅的访问权限控制。当我们整理好这些模块后，对于其他开发者接管项目或后续的维护中，会是一个不错的帮助（模块的整理与建议）。或许现阶段你感受不到这块的威力，随着你深入地使用实践就能体会到这么设计的诸多好处与优势。

开发者基于 ioGame 编写的项目，通常是语法简洁的、高性能的、低延迟的；框架最低要求使用 JDK17，这样即可以让项目享受到 ZGC 带来的改进，还能享受语法上的简洁。从 JDK17 开始 ZGC 远低于其亚毫秒级暂停时间的目标，可以在不影响游戏速度的情况下，清理掉多余的内存。这样就不会出现卡顿或者崩溃的问题了，相当于在项目中变相的引入了一位 JVM 调优大师，详细请看 JDK 17 垃圾回收 GC 性能飞跃提升。

综上所述，ioGame 是一个非常适合网络游戏开发的框架。可以让你轻松地创建高性能、低延迟、易扩展的游戏服务器，并且节省时间和资源。如果你想要快速地开发出令人惊艳的网络游戏，请不要犹豫，立即选择 ioGame 吧！框架屏蔽了很多复杂且重复性的工作，并可为项目中的功能模块结构、开发流程等进行清晰的组织定义，减少了后续的项目维护成本。

相信你已经对 ioGame 有了一个初步的了解，虽然还有很多丰富的功能与特性没有介绍到，但你可以通过后续的实践过程中来深入了解。感谢你的阅读，并期待你使用 ioGame 来打造自己的游戏服务器。

ioGame 是由 [网络通信框架] 和 [业务框架] 组成。

网络通信框架：职责是各服务器之间的网络通信
业务框架：职责是业务逻辑的处理方式和编写方式

网络通信框架

SOFABolt 是蚂蚁金融服务集团开发的一套基于 Netty 实现的网络通信框架。

为了让 Java 程序员能将更多的精力放在基于网络通信的业务逻辑实现上，而不是过多的纠结于网络底层 NIO 的实现以及处理难以调试的网络问题，Netty 应运而生。
为了让中间件开发者能将更多的精力放在产品功能特性实现上，而不是重复地一遍遍制造通信框架的轮子，SOFABolt 应运而生。

Bolt 名字取自迪士尼动画 - 闪电狗，是一个基于 Netty 最佳实践的轻量、易用、高性能、易扩展的通信框架。

业务框架

如果说 sofa-bolt 是为了让 Java 程序员能将更多的精力放在基于网络通信的业务逻辑实现上。而业务框架正是解决业务逻辑如何方便实现这一问题上。业务框架是游戏框架的一部分，职责是简化程序员的业务逻辑实现，业务框架使程序员能够快速的开始编写游戏业务。

业务框架对于每个 action （即业务的处理方法）都是通过 asm 与 Singleton、Flyweight 、Command 等设计模式结合，对 action 的获取上通过 array 来得到，是一种近原生的方式。

单线程中，业务框架平均每秒可以执行 1152 万次业务逻辑

架构简图

通过 ioGame 你可以很容易的搭建出一个集群无中心节点、集群自动化、分步式的网络游戏服务器

无锁异步化与事件驱动的架构设计、集群无中心节点、自带负载均衡、分布式支持、可动态增减机器、避免类爆炸的设计；

图中的每个游戏对外服、每个游戏逻辑服、每个 broker （游戏网关）都可以在单独的进程中部署，逻辑服之间可以跨进程通信（游戏对外服也是逻辑服的一种）。

游戏网关集群

broker （游戏网关）支持集群的方式部署，集群的使用是简单的，集群无中心节点、集群自动化、自带负载均衡。ioGame 本身就包含服务注册，你不需要外接一个服务注册中心，如 Eureka，ZooKeeper 等（变相的节约服务器成本）。

通过 broker （游戏网关）的介入，之前非常复杂的负载均衡设计，如服务注册、健康度检查（后续版本提供）、到服务端的连接维护等这些问题，在 ioGame 中都不需要了，结构也简单了很多。实际上单台 broker （游戏网关）性能已经能够满足了，因为游戏网关只做了转发。

逻辑服

逻辑服通常说的是游戏对外服和游戏逻辑服。逻辑服可以有很多个，逻辑服扩展数量的理论上限是 netty 的连接上限。

游戏对外服

对外服保持与用户（玩家）的长连接。先来个假设，假如我们的一台硬件支持我们建立用户连接的上限是 5000 人，当用户量达到 7000 人时，我们可以多加一个对外服务器来进行分流减压。由于游戏对外服扩展的简单性，意味着支持同时在线玩家可以轻松的达到百万、千万甚至更多。

即使我们启动了多个游戏对外服，开发者也不需要关心这些玩家连接到了哪个游戏对外服的问题，这些玩家总是能接收到广播（推送）消息的，因为框架已经把这些事情给做了；在玩家的角度我们只有 “一个” 服务器，同样的，在开发者的角度我们只有 “一个” 游戏对外服；

在结构组合上（部署多样性）

在部署上，支持多服单进程的方式部署（类似单体应用、在分步式开发时，调试更加方便）、也支持多服多进程多机器的方式部署。

架构由三部分组成：1. 游戏对外服、2.Broker（游戏网关）、3. 游戏逻辑服；三者既可相互独立，又可相互融合，如：

游戏对外服、Broker（游戏网关）、游戏逻辑服这三部分，在一个进程中；【单体应用；在开发分步式时，调试更加方便】
游戏对外服、Broker（游戏网关）、游戏逻辑服这三部分，在多个进程中；【分布式】
游戏对外服、Broker（游戏网关）这两部分在一个进程中；而游戏逻辑服在多个进程中；【类似之前游戏的传统架构】
甚至可以不需要游戏对外服，只使用 Broker（游戏网关）和游戏逻辑服这两部分，用于其他系统业务；

因为 ioGame 遵循面向对象的设计原则（单一职责原则、开闭原则、里式替换原则、依赖倒置原则、接口隔离原则、迪米特法则）等，所以使得架构的职责分明，可以灵活的进行组合；

游戏对外服是架构的三部分之一，默认的游戏对外服是基于 netty 实现的。如果有需要，将来我们还可以使用基于 mina、smart-socket 等通信框架编写，额外提供一个游戏对外服的实现；即使是使用 mina、smart-socket 提供的游戏对外服，也并不会影响现有的游戏逻辑服业务逻辑，因为游戏对外服满足单一职责原则，只维护用户（玩家）长连接相关的。

开发人员几乎都遇见过这么一种情况；在项目初期阶段，通常是以单体项目的方式进行开发，随着需求不断的增加与迭代，会演变成一个臃肿的项目；此时在对一个整体进行拆分是困难的，成本是极高的。甚至是不可完成的，最后导致完全的重新重构；

ioGame 提供了在结构组合上的部署多样性，通过组合的方式，在项目初期就可以避免这些拆分问题。在开发阶段中，我们可以使用单体应用开发思维，降低了开发成本。通过单体应用的开发方式，在开发分步式项目时，调试更加的方便；这既能兼顾分步式开发、项目模块的拆分，又能降低团队的开发成本；

架构优点

架构有很高程度的抽象，让设计者更加关注于业务，而无需考虑底层的实现、通信参数等问题。

逻辑服的位置透明性；同时，由于模块化、抽象化，使得整个架构各服务器之间耦合度很低，逻辑服注册即可用，大大增加了可伸缩性、可维护性，动态扩展变得简单而高效。由于逻辑服是注册到 Broker（游戏网关）上的，所以逻辑服可以动态的增加、删除、改变；由于逻辑服之间耦合度较小，调试和测试的工作也是可控的；

架构比较清晰的就是，游戏对外服负责维护客户端的接入（用户、玩家的连接），游戏逻辑服专心负责业务逻辑，他们之间的调度由 Broker（游戏网关）来负责；因为架构拆分的合理，所以特别方便用 k8s 来自由伸缩部署这三种服，哪个服水位高就扩容哪个，水位过去了又可以缩容。

通过 ioGame 可以使得游戏编程变得简单，下面是一个业务示例

协议文件定义

首先我们自定义一个协议文件，这个协议文件作为我们的业务载体描述。这个协议是纯 java 代码编写的，使用的是 jprotobuf，jprotobuf 是对 google protobuf 的简化使用，性能同等。

可以把这理解成 DTO、POJO、业务数据载体等，其主要目的是用于业务数据的传输；

 /** 请求 */ @ProtobufClass @FieldDefaults(level = AccessLevel.PUBLIC) public class HelloReq {     String name; }

Action

游戏服务器的编程，游戏服务器接收业务数据后，对业务数据进行处理

 @ActionController(1) public class DemoAction {     @ActionMethod(0)     public HelloReq here(HelloReq helloReq) {         HelloReq newHelloReq = new HelloReq();         newHelloReq.name = helloReq.name + ", I'm here ";         return newHelloReq;     } }

一个方法在业务框架中表示一个 Action（一个业务动作）。

方法声名的参数是用于接收前端传入的业务数据，在方法 return 时，数据就可以被游戏前端接收到。程序员可以不需要关心业务框架的内部细节。

从上面的示例可以看出，这和普通的 java 类并无区别，同时这种设计方式避免了类爆炸。如果只负责编写游戏业务，那么对于业务框架的学习可以到此为止了。

游戏编程就是如此简单！

问：我可以开始游戏服务器的编程了吗？

是的，你已经可以开始游戏服务器的编程了。

访问示例（控制台）

当我们访问 here 方法时（通常由游戏前端来请求），控制台将会打印

 ┏━━━━━ Debug. [(DemoAction.java:4).here] ━━━ [cmd:1 - subCmd:0 - cmdMerge:65536] ┣ userId : 888 ┣ 参数: helloReq : HelloReq(name=塔姆) ┣ 响应: HelloReq(name=塔姆, I'm here ) ┣ 时间: 0 ms (业务方法总耗时) ┗━━━━━ Debug [DemoAction.java] ━━━━━━━━━━━━━━[当前线程:RequestMessage-8-1]

控制台打印说明

 @ActionController(3) public class HallAction {     @ActionMethod(9)     public List<Animal> listAnimal() {         // 查询出列表         return IntStream.range(1, 4).mapToObj(id -> {             Animal animal = new Animal();             animal.id = id;             return animal;         }).collect(Collectors.toList());     } }0

有了以上信息，游戏开发者可以很快的定位问题。如果没有可视化的信息，开发中会浪费很多时间在前后端的沟通上。问题包括：

是否传参问题（游戏前端说传了）
是否响应问题（游戏后端说返回了）
业务执行时长问题（游戏前端说没收到响应，游戏后端说早就响应了）

其中代码导航可以让开发者快速的跳转到业务类对应代码中，在多人合作的项目中，可以快速的知道业务经过了哪些方法的执行，使得我们可以快速的进行阅读或修改；

框架内置功

内置多种可选模块，可按需选择，以方便应用开发：

领域事件（轻量级单机最快 MQ -- disruptor；通过领域事件模块，可为你的系统实现类似 Guava-EventBus、Spring 事件驱动模型 ApplicationEvent、业务解耦、规避并发、不阻塞主线程... 等，各种浪操作）
任务延时器（将来某个时间可对任务进行执行、暂停、取消等操作，并不是类似 Quartz 的任务调度）
多环境切换（不同运行环境下的配置支持）
light-jprotobuf （补足 jprotobuf 不能让多个对象在单个 .proto 源文件中生成的需求，并简化 jprotobuf 对源文件的注释）
分步式锁 (基于 Redisson 的简单实现)

内置的其他功能：