T2FGame.Protocol 1.0.9

T2FGame.Protocol

T2FGame 框架的协议层，提供命令路由定义和 Protobuf 消息协议。

功能特性

• 命令路由系统：类似 ioGame 的 CmdMerge 机制
• Protobuf 支持：高性能二进制序列化
• 命令工具类：路由合并、解析、格式化

安装

<PackageReference Include="T2FGame.Protocol" />

核心概念

命令路由 (CmdMerge)

T2FGame 使用两级命令路由系统：

• Cmd（主命令）：表示功能模块，如用户模块、战斗模块
• SubCmd（子命令）：表示具体操作，如登录、注册

CmdMerge = (Cmd << 16) | SubCmd

命令定义

/// <summary>
/// 命令模块定义
/// </summary>
public static class CmdModule
{
    public const int System = 0;      // 系统模块
    public const int User = 1;        // 用户模块
    public const int Battle = 2;      // 战斗模块
    public const int Room = 3;        // 房间模块
    public const int Chat = 4;        // 聊天模块
}

/// <summary>
/// 用户模块子命令
/// </summary>
public static class UserCmd
{
    public const int Login = 1;       // 登录
    public const int Logout = 2;      // 登出
    public const int GetInfo = 3;     // 获取信息
    public const int UpdateInfo = 4;  // 更新信息
}

核心组件

CmdKit 工具类

// 合并命令
int cmdMerge = CmdKit.GetMergeCmd(CmdModule.User, UserCmd.Login);
// 结果: 65537 (1 << 16 | 1)

// 获取主命令
int cmd = CmdKit.GetCmd(cmdMerge);
// cmd = 1

// 获取子命令
int subCmd = CmdKit.GetSubCmd(cmdMerge);
// subCmd = 1

// 安全合并（带范围检查）
if (CmdKit.TryGetMergeCmd(cmd, subCmd, out int merged))
{
    // 合并成功
}

// 格式化为字符串（用于日志）
string str = CmdKit.CmdToString(cmdMerge);
// 默认输出: "【路由:cmd:1 - subCmd:1 - cmdMerge:65537】"

自定义命令格式化

// 自定义格式化器（可选）
CmdKit.CurrentFormatter = (cmd, subCmd, mergedCmd) =>
{
    return $"[{cmd}-{subCmd}]";
};

// 日志输出时会使用自定义格式
_logger.LogInformation("处理命令: {Cmd}", CmdKit.CmdToString(cmdMerge));
// 输出: 处理命令: [1-1]

Protobuf 消息

T2FGame 使用 protobuf-net 进行 Protocol Buffers 序列化。通过 [ProtoContract] 和 [ProtoMember] 特性定义消息类型。

定义消息类

using ProtoBuf;

[ProtoContract]
public class LoginRequest
{
    [ProtoMember(1)]
    public string Username { get; set; }

    [ProtoMember(2)]
    public string Password { get; set; }

    [ProtoMember(3)]
    public string DeviceId { get; set; }
}

[ProtoContract]
public class LoginResponse
{
    [ProtoMember(1)]
    public long UserId { get; set; }

    [ProtoMember(2)]
    public string Token { get; set; }

    [ProtoMember(3)]
    public long ExpireTime { get; set; }
}

[ProtoContract]
public class UserInfo
{
    [ProtoMember(1)]
    public long UserId { get; set; }

    [ProtoMember(2)]
    public string Nickname { get; set; }

    [ProtoMember(3)]
    public int Level { get; set; }

    [ProtoMember(4)]
    public long Gold { get; set; }
}

使用消息

using ProtoBuf;

// 创建请求
var request = new LoginRequest
{
    Username = "player1",
    Password = "password123",
    DeviceId = "device-001"
};

// 序列化
using var ms = new MemoryStream();
Serializer.Serialize(ms, request);
byte[] data = ms.ToArray();

// 反序列化
using var readMs = new MemoryStream(data);
var parsed = Serializer.Deserialize<LoginRequest>(readMs);

项目配置

csproj 配置

<ItemGroup>
  <PackageReference Include="protobuf-net" />
</ItemGroup>

使用 Source Generator 自动生成 .proto 文件

配合 T2FGame.CodeGen.Protocol，可以从 [ProtoContract] 类型自动生成 .proto 文件：

<ItemGroup>
  <PackageReference Include="T2FGame.CodeGen.Protocol"
                    OutputItemType="Analyzer"
                    ReferenceOutputAssembly="false" />
</ItemGroup>

目录结构

T2FGame.Protocol/
├── Cmd/
│   ├── CmdKit.cs              # 命令工具类
│   └── CmdInfo.cs             # 命令信息结构
├── Codec/
│   ├── IProtoMessage.cs       # 协议消息接口
│   ├── ProtoSerializer.cs     # protobuf-net 序列化器
│   └── ProtobufCodec.cs       # 编解码器
├── Messages/
│   ├── ExternalMessage.cs     # 外部消息（客户端-服务器通信）
│   └── HeartbeatMessage.cs    # 心跳消息
├── Wrappers/
│   ├── ISimpleValueWrapper.cs # 简单值包装器接口
│   └── WrapperTypes.cs        # 包装类型（IntValue, StringValue 等）
├── Attributes/
│   └── ErrorCodeAttribute.cs  # 错误码特性
└── Extensions/
    └── IProtoMessageExtensions.cs # 扩展方法

最佳实践

1. 命令编号规划：预留足够的命令空间，避免后期冲突
2. 消息版本兼容：使用 [ProtoMember] 的字段编号，确保向后兼容
3. 自定义格式化：使用 CmdKit.CurrentFormatter 自定义日志格式
4. 使用包装类型：对于简单类型的响应，使用 IntValue、StringValue 等包装类型