chenyh/vRp.CD2g_test
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: 优化 README.md 函数签名

Browse Source
This commit is contained in:
kercylan98
2024-01-15 10:37:51 +08:00
parent 8c80c4b00c
commit bd7a3fee6b
58 changed files with 608 additions and 596 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
server/README.md
View File

@@ -80,7 +80,7 @@ server 提供了包含多种网络类型的服务器实现
***
## 详情信息
#### func NewBot(srv *Server, options ...BotOption) *Bot
#### func NewBot(srv *Server, options ...BotOption) *Bot
<span id="NewBot"></span>
> 创建一个机器人，目前仅支持 Socket 服务器
@@ -122,151 +122,151 @@ func TestNewBot(t *testing.T) {
***
#### func WithBotNetworkDelay(delay time.Duration, fluctuation time.Duration) BotOption
#### func WithBotNetworkDelay(delay time.Duration, fluctuation time.Duration) BotOption
<span id="WithBotNetworkDelay"></span>
> 设置机器人网络延迟及波动范围
> - delay 延迟
> - fluctuation 波动范围
***
#### func WithBotWriter(construction func (bot *Bot) io.Writer) BotOption
#### func WithBotWriter(construction func (bot *Bot) io.Writer) BotOption
<span id="WithBotWriter"></span>
> 设置机器人写入器，默认为 os.Stdout
***
#### func DefaultWebsocketUpgrader() *websocket.Upgrader
#### func DefaultWebsocketUpgrader() *websocket.Upgrader
<span id="DefaultWebsocketUpgrader"></span>
***
#### func NewHttpHandleWrapper(srv *Server, packer ContextPacker[Context]) *Http[Context]
#### func NewHttpHandleWrapper(srv *Server, packer ContextPacker[Context]) *Http[Context]
<span id="NewHttpHandleWrapper"></span>
> 创建一个新的 http 处理程序包装器
> - 默认使用 server.HttpContext 作为上下文，如果需要依赖其作为新的上下文，可以通过 NewHttpContext 创建
***
#### func NewHttpContext(ctx *gin.Context) *HttpContext
#### func NewHttpContext(ctx *gin.Context) *HttpContext
<span id="NewHttpContext"></span>
> 基于 gin.Context 创建一个新的 HttpContext
***
#### func NewGinWrapper(server *gin.Engine, pack func (ctx *gin.Context) CTX) *HttpWrapper[CTX]
#### func NewGinWrapper(server *gin.Engine, pack func (ctx *gin.Context) CTX) *HttpWrapper[CTX]
<span id="NewGinWrapper"></span>
> 创建 gin 包装器，用于对 NewHttpWrapper 函数的替代
***
#### func HasMessageType(mt MessageType) bool
#### func HasMessageType(mt MessageType) bool
<span id="HasMessageType"></span>
> 检查是否存在指定的消息类型
***
#### func NewMultipleServer(serverHandle ...func () ((addr string, srv *Server))) *MultipleServer
#### func NewMultipleServer(serverHandle ...func () ((addr string, srv *Server))) *MultipleServer
<span id="NewMultipleServer"></span>
***
#### func GetNetworks() []Network
#### func GetNetworks() []Network
<span id="GetNetworks"></span>
> 获取所有支持的网络模式
***
#### func WithLowMessageDuration(duration time.Duration) Option
#### func WithLowMessageDuration(duration time.Duration) Option
<span id="WithLowMessageDuration"></span>
> 通过指定慢消息时长的方式创建服务器，当消息处理时间超过指定时长时，将会输出 WARN 类型的日志
> - 默认值为 DefaultLowMessageDuration
> - 当 duration <= 0 时，表示关闭慢消息检测
***
#### func WithAsyncLowMessageDuration(duration time.Duration) Option
#### func WithAsyncLowMessageDuration(duration time.Duration) Option
<span id="WithAsyncLowMessageDuration"></span>
> 通过指定异步消息的慢消息时长的方式创建服务器，当消息处理时间超过指定时长时，将会输出 WARN 类型的日志
> - 默认值为 DefaultAsyncLowMessageDuration
> - 当 duration <= 0 时，表示关闭慢消息检测
***
#### func WithWebsocketConnInitializer(initializer func (writer http.ResponseWriter, request *http.Request, conn *websocket.Conn) error) Option
#### func WithWebsocketConnInitializer(initializer func (writer http.ResponseWriter, request *http.Request, conn *websocket.Conn) error) Option
<span id="WithWebsocketConnInitializer"></span>
> 通过 websocket 连接初始化的方式创建服务器，当 initializer 返回错误时，服务器将不会处理该连接的后续逻辑
> - 该选项仅在创建 NetworkWebsocket 服务器时有效
***
#### func WithWebsocketUpgrade(upgrader *websocket.Upgrader) Option
#### func WithWebsocketUpgrade(upgrader *websocket.Upgrader) Option
<span id="WithWebsocketUpgrade"></span>
> 通过指定 websocket.Upgrader 的方式创建服务器
> - 默认值为 DefaultWebsocketUpgrader
> - 该选项仅在创建 NetworkWebsocket 服务器时有效
***
#### func WithConnWriteBufferSize(size int) Option
#### func WithConnWriteBufferSize(size int) Option
<span id="WithConnWriteBufferSize"></span>
> 通过连接写入缓冲区大小的方式创建服务器
> - 默认值为 DefaultConnWriteBufferSize
> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存
***
#### func WithDispatcherBufferSize(size int) Option
#### func WithDispatcherBufferSize(size int) Option
<span id="WithDispatcherBufferSize"></span>
> 通过消息分发器缓冲区大小的方式创建服务器
> - 默认值为 DefaultDispatcherBufferSize
> - 设置合适的缓冲区大小可以提高服务器性能，但是会占用更多的内存
***
#### func WithMessageStatistics(duration time.Duration, limit int) Option
#### func WithMessageStatistics(duration time.Duration, limit int) Option
<span id="WithMessageStatistics"></span>
> 通过消息统计的方式创建服务器
> - 默认不开启，当 duration 和 limit 均大于 0 的时候，服务器将记录每 duration 期间的消息数量，并保留最多 limit 条
***
#### func WithPacketWarnSize(size int) Option
#### func WithPacketWarnSize(size int) Option
<span id="WithPacketWarnSize"></span>
> 通过数据包大小警告的方式创建服务器，当数据包大小超过指定大小时，将会输出 WARN 类型的日志
> - 默认值为 DefaultPacketWarnSize
> - 当 size <= 0 时，表示不设置警告
***
#### func WithLimitLife(t time.Duration) Option
#### func WithLimitLife(t time.Duration) Option
<span id="WithLimitLife"></span>
> 通过限制最大生命周期的方式创建服务器
> - 通常用于测试服务器，服务器将在到达最大生命周期时自动关闭
***
#### func WithWebsocketWriteCompression() Option
#### func WithWebsocketWriteCompression() Option
<span id="WithWebsocketWriteCompression"></span>
> 通过数据写入压缩的方式创建Websocket服务器
> - 默认不开启数据压缩
***
#### func WithWebsocketCompression(level int) Option
#### func WithWebsocketCompression(level int) Option
<span id="WithWebsocketCompression"></span>
> 通过数据压缩的方式创建Websocket服务器
> - 默认不开启数据压缩
***
#### func WithDeadlockDetect(t time.Duration) Option
#### func WithDeadlockDetect(t time.Duration) Option
<span id="WithDeadlockDetect"></span>
> 通过死锁、死循环、永久阻塞检测的方式创建服务器
> - 当检测到死锁、死循环、永久阻塞时，服务器将会生成 WARN 类型的日志，关键字为 "SuspectedDeadlock"
> - 默认不开启死锁检测
***
#### func WithDisableAsyncMessage() Option
#### func WithDisableAsyncMessage() Option
<span id="WithDisableAsyncMessage"></span>
> 通过禁用异步消息的方式创建服务器
***
#### func WithAsyncPoolSize(size int) Option
#### func WithAsyncPoolSize(size int) Option
<span id="WithAsyncPoolSize"></span>
> 通过指定异步消息池大小的方式创建服务器
> - 当通过 WithDisableAsyncMessage 禁用异步消息时，此选项无效
> - 默认值为 DefaultAsyncPoolSize
***
#### func WithWebsocketReadDeadline(t time.Duration) Option
#### func WithWebsocketReadDeadline(t time.Duration) Option
<span id="WithWebsocketReadDeadline"></span>
> 设置 Websocket 读取超时时间
> - 默认： DefaultWebsocketReadDeadline
> - 当 t <= 0 时，表示不设置超时时间
***
#### func WithTicker(poolSize int, size int, connSize int, autonomy bool) Option
#### func WithTicker(poolSize int, size int, connSize int, autonomy bool) Option
<span id="WithTicker"></span>
> 通过定时器创建服务器，为服务器添加定时器功能
> - poolSize：指定服务器定时器池大小，当池子内的定时器数量超出该值后，多余的定时器在释放时将被回收，该值小于等于 0 时将使用 timer.DefaultTickerPoolSize
@@ -275,28 +275,28 @@ func TestNewBot(t *testing.T) {
> - autonomy：定时器是否独立运行（独立运行的情况下不会作为服务器消息运行，会导致并发问题）
***
#### func WithTLS(certFile string, keyFile string) Option
#### func WithTLS(certFile string, keyFile string) Option
<span id="WithTLS"></span>
> 通过安全传输层协议TLS创建服务器
> - 支持：Http、Websocket
***
#### func WithGRPCServerOptions(options ...grpc.ServerOption) Option
#### func WithGRPCServerOptions(options ...grpc.ServerOption) Option
<span id="WithGRPCServerOptions"></span>
> 通过GRPC的可选项创建GRPC服务器
***
#### func WithWebsocketMessageType(messageTypes ...int) Option
#### func WithWebsocketMessageType(messageTypes ...int) Option
<span id="WithWebsocketMessageType"></span>
> 设置仅支持特定类型的Websocket消息
***
#### func WithPProf(pattern ...string) Option
#### func WithPProf(pattern ...string) Option
<span id="WithPProf"></span>
> 通过性能分析工具PProf创建服务器
***
#### func New(network Network, options ...Option) *Server
#### func New(network Network, options ...Option) *Server
<span id="New"></span>
> 根据特定网络类型创建一个服务器
@@ -866,7 +866,7 @@ func ExampleServer_Run() {
#### func (*Server) Context() context.Context
> 获取服务器上下文
***
#### func (*Server) TimeoutContext(timeout time.Duration) context.Context, context.CancelFunc
#### func (*Server) TimeoutContext(timeout time.Duration) ( context.Context, context.CancelFunc)
> 获取服务器超时上下文，context.WithTimeout 的简写
***
#### func (*Server) Ticker() *timer.Ticker

10
server/client/README.md
View File

@@ -40,25 +40,25 @@
***
## 详情信息
#### func NewClient(core Core) *Client
#### func NewClient(core Core) *Client
<span id="NewClient"></span>
> 创建客户端
***
#### func CloneClient(client *Client) *Client
#### func CloneClient(client *Client) *Client
<span id="CloneClient"></span>
> 克隆客户端
***
#### func NewTCP(addr string) *Client
#### func NewTCP(addr string) *Client
<span id="NewTCP"></span>
***
#### func NewUnixDomainSocket(addr string) *Client
#### func NewUnixDomainSocket(addr string) *Client
<span id="NewUnixDomainSocket"></span>
***
#### func NewWebsocket(addr string) *Client
#### func NewWebsocket(addr string) *Client
<span id="NewWebsocket"></span>
> 创建 websocket 客户端

22
server/gateway/README.md
View File

@@ -45,17 +45,17 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消
***
## 详情信息
#### func NewEndpoint(name string, cli *client.Client, options ...EndpointOption) *Endpoint
#### func NewEndpoint(name string, cli *client.Client, options ...EndpointOption) *Endpoint
<span id="NewEndpoint"></span>
> 创建网关端点
***
#### func WithEndpointStateEvaluator(evaluator func (costUnixNano float64) float64) EndpointOption
#### func WithEndpointStateEvaluator(evaluator func (costUnixNano float64) float64) EndpointOption
<span id="WithEndpointStateEvaluator"></span>
> 设置端点健康值评估函数
***
#### func WithEndpointConnectionPoolSize(size int) EndpointOption
#### func WithEndpointConnectionPoolSize(size int) EndpointOption
<span id="WithEndpointConnectionPoolSize"></span>
> 设置端点连接池大小
> - 默认为 DefaultEndpointConnectionPoolSize
@@ -63,25 +63,25 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消
> - 在网关服务器中，多个客户端在发送消息到端点服务器时，会共用一个连接，适当的增大连接池大小可以提高网关服务器的承载能力
***
#### func WithEndpointReconnectInterval(interval time.Duration) EndpointOption
#### func WithEndpointReconnectInterval(interval time.Duration) EndpointOption
<span id="WithEndpointReconnectInterval"></span>
> 设置端点重连间隔
> - 默认为 DefaultEndpointReconnectInterval
> - 端点在连接失败后会在该间隔后重连，如果 <= 0 则不会重连
***
#### func NewGateway(srv *server.Server, scanner Scanner, options ...Option) *Gateway
#### func NewGateway(srv *server.Server, scanner Scanner, options ...Option) *Gateway
<span id="NewGateway"></span>
> 基于 server.Server 创建 Gateway 网关服务器
***
#### func WithEndpointSelector(selector EndpointSelector) Option
#### func WithEndpointSelector(selector EndpointSelector) Option
<span id="WithEndpointSelector"></span>
> 设置端点选择器
> - 默认情况下，网关会随机选择一个端点作为目标，如果需要自定义端点选择器，可以通过该选项设置
***
#### func MarshalGatewayOutPacket(addr string, packet []byte) []byte, error
#### func MarshalGatewayOutPacket(addr string, packet []byte) ([]byte, error)
<span id="MarshalGatewayOutPacket"></span>
> 将数据包转换为网关出网数据包
> - | identifier(4) | ipv4(4) | port(2) | packet |
@@ -93,7 +93,7 @@ gateway 是用于处理服务器消息的网关模块，适用于对客户端消
> - | identifier(4) | ipv4(4) | port(2) | packet |
***
#### func MarshalGatewayInPacket(addr string, currentTime int64, packet []byte) []byte, error
#### func MarshalGatewayInPacket(addr string, currentTime int64, packet []byte) ([]byte, error)
<span id="MarshalGatewayInPacket"></span>
> 将数据包转换为网关入网数据包
> - | ipv4(4) | port(2) | cost(4) | packet |
@@ -218,11 +218,11 @@ func TestGateway_Run(t *testing.T) {
#### func (*Gateway) Server() *server.Server
> 获取网关服务器核心
***
#### func (*Gateway) GetEndpoint(name string) *Endpoint, error
#### func (*Gateway) GetEndpoint(name string) ( *Endpoint, error)
> 获取一个可用的端点
> - name: 端点名称
***
#### func (*Gateway) GetConnEndpoint(name string, conn *server.Conn) *Endpoint, error
#### func (*Gateway) GetConnEndpoint(name string, conn *server.Conn) ( *Endpoint, error)
> 获取一个可用的端点，如果客户端已经连接到了某个端点，将优先返回该端点
> - 当连接到的端点不可用或没有连接记录时，效果同 GetEndpoint 相同
> - 当连接行为为有状态时，推荐使用该方法
@@ -243,7 +243,7 @@ type Scanner interface {
GetInterval() time.Duration
}
```
#### func (*Scanner) GetEndpoints() []*gateway.Endpoint, error
#### func (*Scanner) GetEndpoints() ( []*gateway.Endpoint, error)
***
#### func (*Scanner) GetInterval() time.Duration
***

4
server/internal/dispatcher/README.md
View File

@@ -36,7 +36,7 @@
***
## 详情信息
#### func NewDispatcher(bufferSize int, name string, handler Handler[P, M]) *Dispatcher[P, M]
#### func NewDispatcher(bufferSize int, name string, handler Handler[P, M]) *Dispatcher[P, M]
<span id="NewDispatcher"></span>
> 创建一个新的消息分发器 Dispatcher 实例
@@ -107,7 +107,7 @@ func TestNewDispatcher(t *testing.T) {
***
#### func NewManager(bufferSize int, handler Handler[P, M]) *Manager[P, M]
#### func NewManager(bufferSize int, handler Handler[P, M]) *Manager[P, M]
<span id="NewManager"></span>
> 生成消息分发器管理器

10
server/lockstep/README.md
View File

@@ -37,7 +37,7 @@
***
## 详情信息
#### func NewLockstep(options ...Option[ClientID, Command]) *Lockstep[ClientID, Command]
#### func NewLockstep(options ...Option[ClientID, Command]) *Lockstep[ClientID, Command]
<span id="NewLockstep"></span>
> 创建一个锁步（帧）同步默认实现的组件(Lockstep)进行返回
@@ -78,19 +78,19 @@ func TestNewLockstep(t *testing.T) {
***
#### func WithFrameLimit(frameLimit int64) Option[ClientID, Command]
#### func WithFrameLimit(frameLimit int64) Option[ClientID, Command]
<span id="WithFrameLimit"></span>
> 通过特定逻辑帧上限创建锁步（帧）同步组件
> - 当达到上限时将停止广播
***
#### func WithFrameRate(frameRate int64) Option[ClientID, Command]
#### func WithFrameRate(frameRate int64) Option[ClientID, Command]
<span id="WithFrameRate"></span>
> 通过特定逻辑帧率创建锁步（帧）同步组件
> - 默认情况下为 15/s
***
#### func WithSerialization(handle func (frame int64, commands []Command) []byte) Option[ClientID, Command]
#### func WithSerialization(handle func (frame int64, commands []Command) []byte) Option[ClientID, Command]
<span id="WithSerialization"></span>
> 通过特定的序列化方式将每一帧的数据进行序列化
>
@@ -102,7 +102,7 @@ func TestNewLockstep(t *testing.T) {
> }
***
#### func WithInitFrame(initFrame int64) Option[ClientID, Command]
#### func WithInitFrame(initFrame int64) Option[ClientID, Command]
<span id="WithInitFrame"></span>
> 通过特定的初始帧创建锁步（帧）同步组件
> - 默认情况下为 0，即第一帧索引为 0

4
server/router/README.md
View File

@@ -33,7 +33,7 @@
***
## 详情信息
#### func NewMultistage(options ...MultistageOption[HandleFunc]) *Multistage[HandleFunc]
#### func NewMultistage(options ...MultistageOption[HandleFunc]) *Multistage[HandleFunc]
<span id="NewMultistage"></span>
> 创建一个支持多级分类的路由器
@@ -47,7 +47,7 @@ func ExampleNewMultistage() {
```
***
#### func WithRouteTrim(handle func (route any) any) MultistageOption[HandleFunc]
#### func WithRouteTrim(handle func (route any) any) MultistageOption[HandleFunc]
<span id="WithRouteTrim"></span>
> 路由修剪选项
> - 将在路由注册前对路由进行对应处理

4
server/writeloop/README.md
View File

@@ -33,7 +33,7 @@
***
## 详情信息
#### func NewChannel(pool *hub.ObjectPool[Message], channelSize int, writeHandler func (message Message) error, errorHandler func (err any)) *Channel[Message]
#### func NewChannel(pool *hub.ObjectPool[Message], channelSize int, writeHandler func (message Message) error, errorHandler func (err any)) *Channel[Message]
<span id="NewChannel"></span>
> 创建基于 Channel 的写循环
> - pool 用于管理 Message 对象的缓冲池，在创建 Message 对象时也应该使用该缓冲池，以便复用 Message 对象。 Channel 会在写入完成后将 Message 对象放回缓冲池
@@ -44,7 +44,7 @@
> 传入 writeHandler 的消息对象是从 Channel 中获取的，因此 writeHandler 不应该持有消息对象的引用，同时也不应该主动释放消息对象
***
#### func NewUnbounded(pool *hub.ObjectPool[Message], writeHandler func (message Message) error, errorHandler func (err any)) *Unbounded[Message]
#### func NewUnbounded(pool *hub.ObjectPool[Message], writeHandler func (message Message) error, errorHandler func (err any)) *Unbounded[Message]
<span id="NewUnbounded"></span>
> 创建写循环
> - pool 用于管理 Message 对象的缓冲池，在创建 Message 对象时也应该使用该缓冲池，以便复用 Message 对象。 Unbounded 会在写入完成后将 Message 对象放回缓冲池