Leaf游戏服务器框架入门指南

框架概述

Leaf是一款基于Go语言开发的开源游戏服务器框架，其设计目标是提升游戏服务器的开发效率和运行时性能。Leaf框架遵循三个核心设计理念：

1. 简洁API：提供简单易用的接口设计
2. 自我修复：能够从运行时错误中恢复而非直接崩溃
3. 多核支持：充分利用多核CPU资源，同时避免潜在的副作用问题

核心架构

模块化设计

Leaf采用模块化架构，每个模块运行在独立的goroutine中，通过轻量级RPC通道(leaf/chanrpc)进行通信。这种设计既保证了模块间的解耦，又充分利用了Go语言的并发特性。

模块需要实现以下接口：

type Module interface {
    OnInit()
    OnDestroy()
    Run(closeSig chan bool)
}

模块生命周期管理流程：

1. 按注册顺序(FIFO)调用各模块的OnInit()
2. 为每个模块启动独立goroutine运行Run()
3. 关闭时按反向顺序调用各模块的OnDestroy()

核心组件

Leaf框架包含以下核心组件：

1. chanrpc：模块间通信的RPC通道
2. db：数据库工具，支持MongoDB
3. gate：客户端连接管理模块
4. go：可控的goroutine工厂
5. log：日志系统
6. network：网络通信组件，支持TCP/WebSocket
7. recordfile：游戏数据管理
8. timer：定时器
9. util：实用工具集

快速入门

基础示例：Hello Leaf

下面通过一个简单的"Hello Leaf"示例演示Leaf的基本使用流程：

1. 定义消息结构：

// 在msg/msg.go中定义消息处理器和消息结构
var Processor = json.NewProcessor()

func init() {
    Processor.Register(&Hello{})
}

type Hello struct {
    Name string
}

2. 配置消息路由：

// 在gate/router.go中配置消息路由
func init() {
    msg.Processor.SetRouter(&msg.Hello{}, game.ChanRPC)
}

3. 实现消息处理器：

// 在game/internal/handler.go中实现消息处理逻辑
func init() {
    handler(&msg.Hello{}, handleHello)
}

func handleHello(args []interface{}) {
    m := args[0].(*msg.Hello)
    a := args[1].(gate.Agent)
    
    log.Debug("hello %v", m.Name)
    a.WriteMsg(&msg.Hello{Name: "client"})
}

4. 编写测试客户端：

// TCP客户端示例
func main() {
    conn, _ := net.Dial("tcp", "127.0.0.1:3563")
    data := []byte(`{"Hello":{"Name":"leaf"}}`)
    m := make([]byte, 2+len(data))
    binary.BigEndian.PutUint16(m, uint16(len(data)))
    copy(m[2:], data)
    conn.Write(m)
}

WebSocket支持

Leaf同时支持TCP和WebSocket协议，配置方式如下：

1. 服务端配置：

// bin/conf/server.json
{
    "WSAddr": "127.0.0.1:3653"
}

2. WebSocket客户端：

<script>
var ws = new WebSocket('ws://127.0.0.1:3653')
ws.onopen = function() {
    ws.send(JSON.stringify({Hello: {Name: 'leaf'}}))
}
</script>

高级特性

ChanRPC通信机制

Leaf的模块间通信采用ChanRPC机制，支持三种调用模式：

1. 同步调用：等待调用完成
2. 异步调用：通过回调函数处理返回结果
3. Go模式：立即返回，不关心结果

示例：

// 注册ChanRPC
skeleton.RegisterChanRPC("NewAgent", rpcNewAgent)

// 调用ChanRPC
game.ChanRPC.Go("NewAgent", a)

可控的Goroutine

Leaf提供了自己的Go()实现，具有以下优势：

1. 错误处理能力
2. 等待所有goroutine执行完成
3. 更容易获取执行结果
4. 支持按顺序执行

示例：

var res string
skeleton.Go(
    func() { // 执行函数
        time.Sleep(1 * time.Second)
        res = "3"
    },
    func() { // 回调函数
        log.Debug(res)
    }
)

定时器系统

Leaf的定时器系统扩展了Go标准库的功能：

1. 支持在同一个goroutine中执行回调
2. 支持cron表达式实现复杂调度

示例：

skeleton.AfterFunc(5*time.Second, func() {
    // 定时任务逻辑
})

日志系统

Leaf日志系统提供多级别日志支持：

1. Debug：调试信息
2. Release：重要信息
3. Error：错误信息
4. Fatal：致命错误

配置示例：

// 设置日志标志，显示文件名和行号
LogFlag = log.Lshortfile

数据管理

Leaf的recordfile组件提供游戏配置数据管理功能，支持CSV格式：

1. 定义数据结构：

type Test struct {
    Id  int "index"
    Arr [4]int
    Str string
}

2. 加载数据文件：

var RfTest = readRf(Test{})

3. 查询数据：

row := RfTest.Index(1).(*Test)

最佳实践

1. 模块设计：

   • 每个模块放在独立目录
   • 内部实现在./internal子目录
   • 通过external.go暴露接口

2. 性能优化：

   • 合理使用goroutine而非创建过多模块
   • 模块主要用于业务解耦而非CPU利用

3. 错误处理：

   • 利用Leaf的自修复特性
   • 合理使用日志级别记录关键信息

Leaf框架通过简洁的设计和丰富的组件，为游戏服务器开发提供了高效可靠的解决方案。开发者可以基于其模块化架构快速构建高性能的游戏服务器。