Merge branch 'develop'

README.md

@@ -1,11 +1,53 @@
 # Minotaur
 
+Minotaur 是一个用于服务端开发的支持库，其中采用了大量泛型设计，主要被用于游戏服务器开发，但由于拥有大量通用的功能，也常被用于 WEB 开发。
+***
+
 [![Go doc](https://img.shields.io/badge/go.dev-reference-brightgreen?logo=go&logoColor=white&style=flat)](https://pkg.go.dev/github.com/kercylan98/minotaur)
-![](https://img.shields.io/badge/Email-kercylan@gmail.com-green.svg?style=flat)
-![](https://komarev.com/ghpvc/?username=kercylan98)
+![license](https://img.shields.io/github/license/kercylan98/minotaur)
 <a target="_blank" href="https://goreportcard.com/report/github.com/kercylan98/minotaur"><img src="https://goreportcard.com/badge/github.com/kercylan98/minotaur?style=flat-square" /></a>
 
-Minotaur 是一个基于 Golang 1.20 编写的服务端开发支持库，其中采用了大量泛型设计，主要被用于游戏服务器开发，但由于拥有大量通用的功能，也常被用于 WEB 开发。
+![go version](https://img.shields.io/github/go-mod/go-version/kercylan98/minotaur?logo=go&style=flat)
+![tag](https://img.shields.io/github/v/tag/kercylan98/minotaur?logo=github&style=flat)
+![views](https://komarev.com/ghpvc/?username=kercylan98&color=blue&style=flat)
+
+![email](https://img.shields.io/badge/Email-kercylan@gmail.com-green.svg?style=flat&logo=gmail&link=mailto:kercylan@gmail.com)
+![qq-group](https://img.shields.io/badge/QQ%20Group-758219443-green.svg?style=flat&logo=tencent-qq&link=https://qm.qq.com/cgi-bin/qm/qr?k=WzRWJIDLzuJbH6-VjdFiTCd1_qA_Ug-D&jump_from=webapi&authKey=ktLEw3XyY9yO+i9rPbI6Fk0UA0uEhACcUidOFdblaiToZtbHcXyU7sFb31FEc9JJ&noverify=0)
+![telegram](https://img.shields.io/badge/Telegram-ziv__siren-green.svg?style=flat&logo=telegram&link=https://telegram.me/ziv_siren)
+
+> - 这是支持快速搭建多功能游戏服务器及 HTTP 服务器的 `Golang` 服务端框架；
+> - 网络传输基于 [`gorilla/websocket`](https://github.com/gorilla/websocket)、[`gin-gonic/gin`](https://github.com/gin-gonic/gin)、[`grpc/grpc-go`](https://github.com/grpc/grpc-go)、[`panjf2000/gnet`](https://github.com/panjf2000/gnet)、[`xtaci/kcp-go`](https://github.com/xtaci/kcp-go) 构建；
+> - 该项目的目标是提供一个简单、高效、可扩展的游戏服务器框架，让开发者可以专注于游戏逻辑的开发，而不用花费大量时间在网络传输、配置导表、日志、监控等基础功能的开发上；
+
+***
+在 Minotaur 中不包括任何跨服实现，但支持基于多级路由器快速实现跨服功能。推荐使用 [`NATS.io`](https://nats.io/) 作为跨服消息中间件。
+  - 目前已实践的弹幕游戏项目以 `NATS.io` 作为消息队列，实现了跨服、埋点日志收集等功能，部署在 `Kubernetes` 集群中；
+  - 该项目客户端与服务端采用 `WebSocket` 进行通讯，服务端暴露 `HTTP` 接口接收互动数据消息回调，通过负载均衡器进入 `Kubernetes` 集群中的 `Minotaur` 服务，最终通过 `NATS.io` 消息队列转发至对应所在的 `Pod` 中进行处理；
+
+<details>
+<summary>关于 Pod 配置参数及非极限压测数据</summary>
+
+> 本次压测 `Pod` 扩容数量为 1，但由于压测连接是最开始就建立好的，所以该扩容的 `Pod` 并没有接受到压力。
+> 理论上来说该 `Pod` 也应该接受 `HTTP` 回调压力，实测过程中，这个扩容的 `Pod` 没有接受到任何压力
+
+**Pod 配置参数**
+
+![pod](.github/images/pod.png)
+
+**压测结果**
+
+![压测数据](.github/images/yc1.png)
+![压测数据](.github/images/yc2.png)
+
+**监控数据**
+
+![事件](./.github/images/yc-event.png)
+![CPU](./.github/images/yc-cpu.png)
+![内存](./.github/images/yc-memory.png)
+
+</details>
+
+***
 
 ## 特色内容
 ```mermaid

configuration/README.md

@@ -29,8 +29,8 @@ configuration 基于配置导表功能实现的配置加载及刷新功能
 
 |类型|名称|描述
 |:--|:--|:--
-|`STRUCT`|[RefreshEventHandle](#refresheventhandle)|配置刷新事件处理函数
-|`INTERFACE`|[Loader](#loader)|配置加载器
+|`STRUCT`|[RefreshEventHandle](#struct_RefreshEventHandle)|配置刷新事件处理函数
+|`INTERFACE`|[Loader](#struct_Loader)|配置加载器
 
 </details>
 
@@ -75,11 +75,13 @@ configuration 基于配置导表功能实现的配置加载及刷新功能
 <span id="OnConfigRefreshEvent"></span>
 
 ***
+<span id="struct_RefreshEventHandle"></span>
 ### RefreshEventHandle `STRUCT`
 配置刷新事件处理函数
 ```go
 type RefreshEventHandle func()
 ```
+<span id="struct_Loader"></span>
 ### Loader `INTERFACE`
 配置加载器
 ```go

game/activity/README.md

@@ -43,17 +43,17 @@ activity 活动状态管理
 
 |类型|名称|描述
 |:--|:--|:--
-|`STRUCT`|[Activity](#activity)|活动描述
-|`STRUCT`|[Controller](#controller)|活动控制器
-|`INTERFACE`|[BasicActivityController](#basicactivitycontroller)|暂无描述...
-|`INTERFACE`|[NoneDataActivityController](#nonedataactivitycontroller)|无数据活动控制器
-|`INTERFACE`|[GlobalDataActivityController](#globaldataactivitycontroller)|全局数据活动控制器
-|`INTERFACE`|[EntityDataActivityController](#entitydataactivitycontroller)|实体数据活动控制器
-|`INTERFACE`|[GlobalAndEntityDataActivityController](#globalandentitydataactivitycontroller)|全局数据和实体数据活动控制器
-|`STRUCT`|[DataMeta](#datameta)|全局活动数据
-|`STRUCT`|[EntityDataMeta](#entitydatameta)|活动实体数据
-|`STRUCT`|[UpcomingEventHandler](#upcomingeventhandler)|暂无描述...
-|`STRUCT`|[Options](#options)|活动选项
+|`STRUCT`|[Activity](#struct_Activity)|活动描述
+|`STRUCT`|[Controller](#struct_Controller)|活动控制器
+|`INTERFACE`|[BasicActivityController](#struct_BasicActivityController)|暂无描述...
+|`INTERFACE`|[NoneDataActivityController](#struct_NoneDataActivityController)|无数据活动控制器
+|`INTERFACE`|[GlobalDataActivityController](#struct_GlobalDataActivityController)|全局数据活动控制器
+|`INTERFACE`|[EntityDataActivityController](#struct_EntityDataActivityController)|实体数据活动控制器
+|`INTERFACE`|[GlobalAndEntityDataActivityController](#struct_GlobalAndEntityDataActivityController)|全局数据和实体数据活动控制器
+|`STRUCT`|[DataMeta](#struct_DataMeta)|全局活动数据
+|`STRUCT`|[EntityDataMeta](#struct_EntityDataMeta)|活动实体数据
+|`STRUCT`|[UpcomingEventHandler](#struct_UpcomingEventHandler)|暂无描述...
+|`STRUCT`|[Options](#struct_Options)|活动选项
 
 </details>
 
@@ -75,97 +75,98 @@ activity 活动状态管理
 > 加载所有活动实体数据
 
 ***
-#### func LoadOrRefreshActivity(activityType Type, activityId ID, options ...*Options)  error
+#### func LoadOrRefreshActivity\[Type generic.Basic, ID generic.Basic\](activityType Type, activityId ID, options ...*Options) error
 <span id="LoadOrRefreshActivity"></span>
 > 加载或刷新活动
 >   - 通常在活动配置刷新时候将活动通过该方法注册或刷新
 
 ***
-#### func DefineNoneDataActivity(activityType Type)  NoneDataActivityController[Type, ID, *none, none, *none]
+#### func DefineNoneDataActivity\[Type generic.Basic, ID generic.Basic\](activityType Type) NoneDataActivityController[Type, ID, *none, none, *none]
 <span id="DefineNoneDataActivity"></span>
 > 声明无数据的活动类型
 
 ***
-#### func DefineGlobalDataActivity(activityType Type)  GlobalDataActivityController[Type, ID, Data, none, *none]
+#### func DefineGlobalDataActivity\[Type generic.Basic, ID generic.Basic, Data any\](activityType Type) GlobalDataActivityController[Type, ID, Data, none, *none]
 <span id="DefineGlobalDataActivity"></span>
 > 声明拥有全局数据的活动类型
 
 ***
-#### func DefineEntityDataActivity(activityType Type)  EntityDataActivityController[Type, ID, *none, EntityID, EntityData]
+#### func DefineEntityDataActivity\[Type generic.Basic, ID generic.Basic, EntityID generic.Basic, EntityData any\](activityType Type) EntityDataActivityController[Type, ID, *none, EntityID, EntityData]
 <span id="DefineEntityDataActivity"></span>
 > 声明拥有实体数据的活动类型
 
 ***
-#### func DefineGlobalAndEntityDataActivity(activityType Type)  GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData]
+#### func DefineGlobalAndEntityDataActivity\[Type generic.Basic, ID generic.Basic, Data any, EntityID generic.Basic, EntityData any\](activityType Type) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData]
 <span id="DefineGlobalAndEntityDataActivity"></span>
 > 声明拥有全局数据和实体数据的活动类型
 
 ***
-#### func RegUpcomingEvent(activityType Type, handler UpcomingEventHandler[ID], priority ...int)
+#### func RegUpcomingEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler UpcomingEventHandler[ID], priority ...int)
 <span id="RegUpcomingEvent"></span>
 > 注册即将开始的活动事件处理器
 
 ***
-#### func OnUpcomingEvent(activity *Activity[Type, ID])
+#### func OnUpcomingEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnUpcomingEvent"></span>
 > 即将开始的活动事件
 
 ***
-#### func RegStartedEvent(activityType Type, handler StartedEventHandler[ID], priority ...int)
+#### func RegStartedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler StartedEventHandler[ID], priority ...int)
 <span id="RegStartedEvent"></span>
 > 注册活动开始事件处理器
 
 ***
-#### func OnStartedEvent(activity *Activity[Type, ID])
+#### func OnStartedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnStartedEvent"></span>
 > 活动开始事件
 
 ***
-#### func RegEndedEvent(activityType Type, handler EndedEventHandler[ID], priority ...int)
+#### func RegEndedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler EndedEventHandler[ID], priority ...int)
 <span id="RegEndedEvent"></span>
 > 注册活动结束事件处理器
 
 ***
-#### func OnEndedEvent(activity *Activity[Type, ID])
+#### func OnEndedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnEndedEvent"></span>
 > 活动结束事件
 
 ***
-#### func RegExtendedShowStartedEvent(activityType Type, handler ExtendedShowStartedEventHandler[ID], priority ...int)
+#### func RegExtendedShowStartedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler ExtendedShowStartedEventHandler[ID], priority ...int)
 <span id="RegExtendedShowStartedEvent"></span>
 > 注册活动结束后延长展示开始事件处理器
 
 ***
-#### func OnExtendedShowStartedEvent(activity *Activity[Type, ID])
+#### func OnExtendedShowStartedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnExtendedShowStartedEvent"></span>
 > 活动结束后延长展示开始事件
 
 ***
-#### func RegExtendedShowEndedEvent(activityType Type, handler ExtendedShowEndedEventHandler[ID], priority ...int)
+#### func RegExtendedShowEndedEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler ExtendedShowEndedEventHandler[ID], priority ...int)
 <span id="RegExtendedShowEndedEvent"></span>
 > 注册活动结束后延长展示结束事件处理器
 
 ***
-#### func OnExtendedShowEndedEvent(activity *Activity[Type, ID])
+#### func OnExtendedShowEndedEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnExtendedShowEndedEvent"></span>
 > 活动结束后延长展示结束事件
 
 ***
-#### func RegNewDayEvent(activityType Type, handler NewDayEventHandler[ID], priority ...int)
+#### func RegNewDayEvent\[Type generic.Basic, ID generic.Basic\](activityType Type, handler NewDayEventHandler[ID], priority ...int)
 <span id="RegNewDayEvent"></span>
 > 注册新的一天事件处理器
 
 ***
-#### func OnNewDayEvent(activity *Activity[Type, ID])
+#### func OnNewDayEvent\[Type generic.Basic, ID generic.Basic\](activity *Activity[Type, ID])
 <span id="OnNewDayEvent"></span>
 > 新的一天事件
 
 ***
-#### func NewOptions()  *Options
+#### func NewOptions() *Options
 <span id="NewOptions"></span>
 > 创建活动选项
 
 ***
+<span id="struct_Activity"></span>
 ### Activity `STRUCT`
 活动描述
 ```go
@@ -185,6 +186,7 @@ type Activity[Type generic.Basic, ID generic.Basic] struct {
 	initializeData    func()
 }
 ```
+<span id="struct_Controller"></span>
 ### Controller `STRUCT`
 活动控制器
 ```go
@@ -199,6 +201,63 @@ type Controller[Type generic.Basic, ID generic.Basic, Data any, EntityID generic
 	mutex      sync.RWMutex
 }
 ```
+<span id="struct_Controller_GetGlobalData"></span>
+
+#### func (*Controller) GetGlobalData(activityId ID)  Data
+> 获取特定活动全局数据
+
+***
+<span id="struct_Controller_GetEntityData"></span>
+
+#### func (*Controller) GetEntityData(activityId ID, entityId EntityID)  EntityData
+> 获取特定活动实体数据
+
+***
+<span id="struct_Controller_IsOpen"></span>
+
+#### func (*Controller) IsOpen(activityId ID)  bool
+> 活动是否开启
+
+***
+<span id="struct_Controller_IsShow"></span>
+
+#### func (*Controller) IsShow(activityId ID)  bool
+> 活动是否展示
+
+***
+<span id="struct_Controller_IsOpenOrShow"></span>
+
+#### func (*Controller) IsOpenOrShow(activityId ID)  bool
+> 活动是否开启或展示
+
+***
+<span id="struct_Controller_Refresh"></span>
+
+#### func (*Controller) Refresh(activityId ID)
+> 刷新活动
+
+***
+<span id="struct_Controller_InitializeNoneData"></span>
+
+#### func (*Controller) InitializeNoneData(handler func (activityId ID, data *DataMeta[Data]))  NoneDataActivityController[Type, ID, Data, EntityID, EntityData]
+
+***
+<span id="struct_Controller_InitializeGlobalData"></span>
+
+#### func (*Controller) InitializeGlobalData(handler func (activityId ID, data *DataMeta[Data]))  GlobalDataActivityController[Type, ID, Data, EntityID, EntityData]
+
+***
+<span id="struct_Controller_InitializeEntityData"></span>
+
+#### func (*Controller) InitializeEntityData(handler func (activityId ID, entityId EntityID, data *EntityDataMeta[EntityData]))  EntityDataActivityController[Type, ID, Data, EntityID, EntityData]
+
+***
+<span id="struct_Controller_InitializeGlobalAndEntityData"></span>
+
+#### func (*Controller) InitializeGlobalAndEntityData(handler func (activityId ID, data *DataMeta[Data]), entityHandler func (activityId ID, entityId EntityID, data *EntityDataMeta[EntityData]))  GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData]
+
+***
+<span id="struct_BasicActivityController"></span>
 ### BasicActivityController `INTERFACE`
 
 ```go
@@ -209,6 +268,7 @@ type BasicActivityController[Type generic.Basic, ID generic.Basic, Data any, Ent
 	Refresh(activityId ID)
 }
 ```
+<span id="struct_NoneDataActivityController"></span>
 ### NoneDataActivityController `INTERFACE`
 无数据活动控制器
 ```go
@@ -217,6 +277,7 @@ type NoneDataActivityController[Type generic.Basic, ID generic.Basic, Data any,
 	InitializeNoneData(handler func(activityId ID, data *DataMeta[Data])) NoneDataActivityController[Type, ID, Data, EntityID, EntityData]
 }
 ```
+<span id="struct_GlobalDataActivityController"></span>
 ### GlobalDataActivityController `INTERFACE`
 全局数据活动控制器
 ```go
@@ -226,6 +287,7 @@ type GlobalDataActivityController[Type generic.Basic, ID generic.Basic, Data any
 	InitializeGlobalData(handler func(activityId ID, data *DataMeta[Data])) GlobalDataActivityController[Type, ID, Data, EntityID, EntityData]
 }
 ```
+<span id="struct_EntityDataActivityController"></span>
 ### EntityDataActivityController `INTERFACE`
 实体数据活动控制器
 ```go
@@ -235,6 +297,7 @@ type EntityDataActivityController[Type generic.Basic, ID generic.Basic, Data any
 	InitializeEntityData(handler func(activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) EntityDataActivityController[Type, ID, Data, EntityID, EntityData]
 }
 ```
+<span id="struct_GlobalAndEntityDataActivityController"></span>
 ### GlobalAndEntityDataActivityController `INTERFACE`
 全局数据和实体数据活动控制器
 ```go
@@ -245,6 +308,7 @@ type GlobalAndEntityDataActivityController[Type generic.Basic, ID generic.Basic,
 	InitializeGlobalAndEntityData(handler func(activityId ID, data *DataMeta[Data]), entityHandler func(activityId ID, entityId EntityID, data *EntityDataMeta[EntityData])) GlobalAndEntityDataActivityController[Type, ID, Data, EntityID, EntityData]
 }
 ```
+<span id="struct_DataMeta"></span>
 ### DataMeta `STRUCT`
 全局活动数据
 ```go
@@ -254,6 +318,7 @@ type DataMeta[Data any] struct {
 	LastNewDay time.Time
 }
 ```
+<span id="struct_EntityDataMeta"></span>
 ### EntityDataMeta `STRUCT`
 活动实体数据
 ```go
@@ -263,11 +328,13 @@ type EntityDataMeta[Data any] struct {
 	LastNewDay time.Time
 }
 ```
+<span id="struct_UpcomingEventHandler"></span>
 ### UpcomingEventHandler `STRUCT`
 
 ```go
 type UpcomingEventHandler[ID generic.Basic] func(activityId ID)
 ```
+<span id="struct_Options"></span>
 ### Options `STRUCT`
 活动选项
 ```go
@@ -276,19 +343,34 @@ type Options struct {
 	Loop time.Duration
 }
 ```
+<span id="struct_Options_WithUpcomingTime"></span>
+
 #### func (*Options) WithUpcomingTime(t time.Time)  *Options
 > 设置活动预告时间
+
 ***
+<span id="struct_Options_WithStartTime"></span>
+
 #### func (*Options) WithStartTime(t time.Time)  *Options
 > 设置活动开始时间
+
 ***
+<span id="struct_Options_WithEndTime"></span>
+
 #### func (*Options) WithEndTime(t time.Time)  *Options
 > 设置活动结束时间
+
 ***
+<span id="struct_Options_WithExtendedShowTime"></span>
+
 #### func (*Options) WithExtendedShowTime(t time.Time)  *Options
 > 设置延长展示时间
+
 ***
+<span id="struct_Options_WithLoop"></span>
+
 #### func (*Options) WithLoop(interval time.Duration)  *Options
 > 设置活动循环，时间间隔小于等于 0 表示不循环
 >   - 当活动状态展示结束后，会根据该选项设置的时间间隔重新开始
+
 ***