golang轻量级TCP服务器框架插件库easytcp的使用

EasyTCP简介

EasyTCP是一个基于Go标准net包实现的轻量级TCP服务器框架，具有以下特性：

• 非侵入式设计
• 支持路由处理器的管道式中间件
• 可自定义消息打包器、编解码器和日志器
• 提供便捷函数处理请求数据和发送响应
• 支持常用钩子函数

安装

使用以下命令安装EasyTCP：

$ go get -u github.com/DarthPestilane/easytcp

注意：EasyTCP使用Go Modules管理依赖。

快速开始

基础示例

package main

import (
    "fmt"
    "github.com/DarthPestilane/easytcp"
)

func main() {
    // 创建带选项的服务器
    s := easytcp.NewServer(&easytcp.ServerOption{
        Packer: easytcp.NewDefaultPacker(), // 使用默认打包器
        Codec:  nil,                       // 不使用编解码器
    })

    // 注册路由，使用消息ID
    // DefaultPacker将ID视为int类型
    s.AddRoute(1001, func(c easytcp.Context) {
        // 获取请求
        req := c.Request()

        // 处理逻辑...
        fmt.Printf("[server] request received | id: %d; size: %d; data: %s\n", req.ID(), len(req.Data()), req.Data())

        // 设置响应
        c.SetResponseMessage(easytcp.NewMessage(1002, []byte("copy that")))
    })

    // 设置自定义日志器（可选）
    easytcp.SetLogger(lg)

    // 添加全局中间件（可选）
    s.Use(recoverMiddleware)

    // 设置钩子函数（可选）
    s.OnSessionCreate = func(session easytcp.Session) {...}
    s.OnSessionClose = func(session easytcp.Session) {...}

    // 设置未找到路由处理器（可选）
    s.NotFoundHandler(handler)

    // 监听并服务
    if err := s.Run(":5896"); err != nil && err != server.ErrServerStopped {
        fmt.Println("serve error: ", err.Error())
    }
}

使用编解码器的示例

// 创建带编解码器的服务器
s := easytcp.NewServer(&easytcp.ServerOption{
    Packer: easytcp.NewDefaultPacker(), // 使用默认打包器
    Codec:  &easytcp.JsonCodec{},       // 使用JsonCodec
})

// 注册路由
s.AddRoute(1001, func(c easytcp.Context) {
    // 解码请求数据并绑定到reqData
    var reqData map[string]interface{}
    if err := c.Bind(&reqData); err != nil {
        // 处理错误
    }

    // 处理逻辑...
    respId := 1002
    respData := map[string]interface{}{
        "success": true,
        "feeling": "Great!",
    }

    // 编码响应数据并设置到上下文
    if err := c.SetResponse(respId, respData); err != nil {
        // 处理错误
    }
})

架构设计

接受连接:
+------------+    +-------------------+    +----------------+
|            |    |                   |    |                |
|            |    |                   |    |                |
| tcp server |--->| accept connection |--->| create session |
|            |    |                   |    |                |
|            |    |                   |    |                |
+------------+    +-------------------+    +----------------+

会话中:
+------------------+    +-----------------------+    +----------------------------------+
| read connection  |--->| unpack packet payload |--->|                                  |
+------------------+    +-----------------------+    |                                  |
                                                     | router (middlewares and handler) |
+------------------+    +-----------------------+    |                                  |
| write connection |<---| pack packet payload   |<---|                                  |
+------------------+    +-----------------------+    +----------------------------------+

路由处理器中:
+----------------------------+    +------------+
| codec decode request data  |--->|            |
+----------------------------+    |            |
                                  | user logic |
+----------------------------+    |            |
| codec encode response data |<---|            |
+----------------------------+    +------------+

核心概念

路由

EasyTCP通过消息ID区分不同消息，消息会根据其ID通过中间件路由到对应的处理器。

请求流程：

+----------+    +--------------+    +--------------+    +---------+
| request  |--->|              |--->|              |--->|         |
+----------+    |              |    |              |    |         |
                | middleware 1 |    | middleware 2 |    | handler |
+----------+    |              |    |              |    |         |
| response |<---|              |<---|              |<---|         |
+----------+    +--------------+    +--------------+    +---------+

注册路由

s.AddRoute(reqID, func(c easytcp.Context) {
    // 获取请求
    req := c.Request()

    // 处理逻辑...
    fmt.Printf("[server] request received | id: %d; size: %d; data: %s\n", req.ID(), len(req.Data()), req.Data())

    // 设置响应
    c.SetResponseMessage(easytcp.NewMessage(respID, []byte("copy that")))
})

使用中间件

// 注册全局中间件（优先级高于路由级中间件）
s.Use(recoverMiddleware, logMiddleware, ...)

// 为单个路由注册中间件
s.AddRoute(reqID, handler, middleware1, middleware2)

// 中间件示例
var exampleMiddleware easytcp.MiddlewareFunc = func(next easytcp.HandlerFunc) easytcp.HandlerFunc {
    return func(c easytcp.Context) {
        // 前置处理...
        next(c)
        // 后置处理...
    }
}

打包器(Packer)

打包器负责打包和解包消息负载。可以在创建服务器时设置自定义打包器。

s := easytcp.NewServer(&easytcp.ServerOption{
    Packer: new(MyPacker), // 可选，默认为DefaultPacker
})

自定义打包器示例

// CustomPacker 实现Packer接口，格式为 size(2)id(2)data(n)
type CustomPacker struct{}

func (p *CustomPacker) bytesOrder() binary.ByteOrder {
    return binary.BigEndian
}

func (p *CustomPacker) Pack(msg *easytcp.Message) ([]byte, error) {
    size := len(msg.Data()) // 仅数据部分大小
    buffer := make([]byte, 2+2+size)
    p.bytesOrder().PutUint16(buffer[:2], uint16(size))
    p.bytesOrder().PutUint16(buffer[2:4], msg.ID().(uint16))
    copy(buffer[4:], msg.Data())
    return buffer, nil
}

func (p *CustomPacker) Unpack(reader io.Reader) (*easytcp.Message, error) {
    headerBuffer := make([]byte, 2+2)
    if _, err := io.ReadFull(reader, headerBuffer); err != nil {
        return nil, fmt.Errorf("read size and id err: %s", err)
    }
    size := p.bytesOrder().Uint16(headerBuffer[:2])
    id := p.bytesOrder().Uint16(headerBuffer[2:])

    data := make([]byte, size)
    if _, err := io.ReadFull(reader, data); err != nil {
        return nil, fmt.Errorf("read data err: %s", err)
    }

    // 由于msg.ID是uint16类型，添加路由时也需使用uint16
    msg := easytcp.NewMessage(id, data)
    msg.Set("theWholeLength", 2+2+size) // 可设置自定义KV数据
    return msg, nil
}

编解码器(Codec)

编解码器负责编码和解码消息数据。Codec是可选的，如果不设置，EasyTCP不会对消息数据进行编解码。

s := easytcp.NewServer(&easytcp.ServerOption{
    Codec: &easytcp.JsonCodec{}, // 可选，JsonCodec是内置编解码器
})

使用编解码器的路由处理器示例：

s.AddRoute(reqID, func(c easytcp.Context) {
    var reqData map[string]interface{}
    if err := c.Bind(&reqData); err != nil { // 解码消息数据并绑定到reqData
        // 处理错误...
    }
    req := c.Request()
    fmt.Printf("[server] request received | id: %d; size: %d; data-decoded: %+v\n", req.ID(), len(req.Data()), reqData())
    respData := map[string]string{"key": "value"}
    if err := c.SetResponse(respID, respData); err != nil {
        // 处理错误...
    }
})

内置编解码器

1. JsonCodec：使用encoding/json作为默认实现，可通过构建标签切换为jsoniter：

   go build -tags=jsoniter .
   

2. ProtobufCodec：使用google.golang.org/protobuf实现

3. MsgpackCodec：使用github.com/vmihailenco/msgpack实现

完整示例

以下是一个完整的EasyTCP服务器示例，包含中间件和自定义处理逻辑：

package main

import (
	"fmt"
	"github.com/DarthPestilane/easytcp"
	"log"
)

func main() {
	// 创建服务器
	s := easytcp.NewServer(&easytcp.ServerOption{
		Packer: easytcp.NewDefaultPacker(),
		Codec:  &easytcp.JsonCodec{},
	})

	// 添加全局中间件
	s.Use(loggingMiddleware)

	// 注册路由
	s.AddRoute(1001, handleEcho, authMiddleware)

	// 设置会话钩子
	s.OnSessionCreate = func(session easytcp.Session) {
		log.Printf("session created: %s", session.ID())
	}
	s.OnSessionClose = func(session easytcp.Session) {
		log.Printf("session closed: %s", session.ID())
	}

	// 启动服务器
	if err := s.Run(":5896"); err != nil {
		log.Fatalf("serve error: %v", err)
	}
}

// 处理函数
func handleEcho(c easytcp.Context) {
	var reqData map[string]interface{}
	if err := c.Bind(&reqData); err != nil {
		c.SetResponse(500, map[string]string{"error": "invalid request"})
		return
	}

	// 处理请求
	respData := map[string]interface{}{
		"code":    200,
		"message": "success",
		"data":    reqData,
	}

	// 设置响应
	if err := c.SetResponse(1002, respData); err != nil {
		fmt.Printf("set response error: %v\n", err)
	}
}

// 日志中间件
var loggingMiddleware easytcp.MiddlewareFunc = func(next easytcp.HandlerFunc) easytcp.HandlerFunc {
	return func(c easytcp.Context) {
		req := c.Request()
		log.Printf("request received | id: %d | size: %d", req.ID(), len(req.Data()))
		next(c)
		resp := c.Response()
		log.Printf("response sent | id: %d | size: %d", resp.ID(), len(resp.Data()))
	}
}

// 认证中间件
var authMiddleware easytcp.MiddlewareFunc = func(next easytcp.HandlerFunc) easytcp.HandlerFunc {
	return func(c easytcp.Context) {
		// 这里可以添加认证逻辑
		// 例如检查请求头或token等
		next(c)
	}
}

这个示例展示了：

1. 创建带有JSON编解码器的服务器
2. 添加全局日志中间件
3. 注册带有认证中间件的路由处理器
4. 设置会话生命周期钩子
5. 完整的请求处理流程，包括请求解码和响应编码

EasyTCP提供了灵活的方式来构建TCP服务器，可以根据需要自定义打包器、编解码器和中间件，满足各种业务场景需求。