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 等包装类型