LuminNet

LuminNet 是一个面向 .NET 的高性能网络与 RPC 框架。它使用 Roslyn 源生成器生成消息分发、序列化调用和 RPC 辅助方法，减少运行时反射与重复分配，适合游戏服务器、实时服务和网关场景。

项目仍在持续开发中，API 和线协议可能发生变化。生产环境使用前请先完成自己的压力测试与兼容性验证。

主要特性

• TCP、WebSocket 和 KCP 传输。
• 单向消息、请求/响应 RPC，以及 Gate 网关转发。
• 基于 Roslyn incremental generator 的强类型代码生成。
• 基于 LuminPack 的二进制序列化，支持多目标框架。
• 异步 API、连接生命周期事件、心跳检测和 RPC 超时控制。
• 最大帧长度、转发 key 长度和 KCP 会话数限制，降低恶意输入造成的内存风险。
• 支持 .NET 8、.NET 9、.NET 10 和 .NET Standard 2.1。

项目结构

src/
  LuminNet/              # 网络运行库
  LuminNet.Generator/    # Roslyn 源生成器
samples/
  LuminNet.Samples.Shared/ # Client/Server/Gate 共享协议源文件
  LuminNet.Client/       # 客户端示例
  LuminNet.Server/       # 服务端示例
  LuminNet.Gate/         # 网关转发示例

构建所需的 LuminKcp.Core.dll 位于 src/LuminNet/libs/。它来自同一作者的 LuminKcp 项目，并使用 MIT License。

环境要求

• .NET 10 SDK（用于构建完整解决方案）。
• Windows、Linux 或 macOS；WebSocket 服务端使用 .NET 的 HttpListener，具体平台行为请自行验证。

从源码构建

dotnet restore LuminNet.sln
dotnet build LuminNet.sln -c Release

运行示例：

dotnet run --project samples/LuminNet.Server/LuminNet.Server.csproj
dotnet run --project samples/LuminNet.Gate/LuminNet.Gate.csproj
dotnet run --project samples/LuminNet.Client/LuminNet.Client.csproj

示例默认使用本机 KCP 端口。启动顺序和端口配置请以各示例的 Program.cs 为准。

快速开始

定义消息和 RPC

消息类型使用 LuminPackable，客户端消息使用 LuminNetMessage 或 LuminNetRpc 标记：

using LuminNet.Attribute;
using LuminPack.Attribute;

[LuminPackable]
[LuminNetMessage]
[LuminNetRpc(typeof(Pong))]
public class Ping
{
    public int Id;
}

[LuminPackable]
public class Pong
{
    public int Id;
}

编写服务端处理器

源生成器会根据 LuminProtocol 生成分发代码，并注册对应的协议处理器：

using LuminNet;
using LuminNet.Attribute;
using LuminThread;

public static class ProtocolHandlers
{
    [LuminProtocol(typeof(Ping), typeof(Pong))]
    public static async LuminTask Handle(
        Session session, Ping request, Pong response)
    {
        response.Id = request.Id + 1;
        await LuminTask.CompletedTask();
    }
}

连接并发送

生成器会为消息生成类似 SendPing、SendPingForPong 的扩展方法：

using LuminNet;
using LuminNet.Enum;
using LuminNet.Generated;

LuminNetRuntime.Initialize();

var session = await LuminNetwork.ConnectAsync(
    NetworkProtocol.Tcp, "127.0.0.1", 9000);

await session.SendPing(new Ping { Id = 42 });
var response = await session.SendPingForPong(new Ping { Id = 42 });

session.Disconnect();

如果 LuminNetMessage 或 LuminNetRpc 指定了目标 key，例如 [LuminNetRpc(typeof(Pong), "Server")]，生成的方法会发送转发帧，Gate 可以根据该 key 将请求转发到后端会话。

网络配置

LuminNetwork.HeartbeatInterval = TimeSpan.FromSeconds(15);
LuminNetwork.HeartbeatTimeout = TimeSpan.FromSeconds(60);
LuminNetwork.RpcTimeout = TimeSpan.FromSeconds(10);
LuminNetwork.MaxPayloadLength = 4 * 1024 * 1024;

LuminNetwork.SetLog(new ConsoleLog());
LuminNetwork.Listen(NetworkProtocol.Tcp, "0.0.0.0", 9000);
LuminNetwork.KeepAlive();

可通过 LuminNetwork.OnConnected、OnDisconnected 和 OnError 订阅连接事件。服务关闭时调用 LuminNetwork.Shutdown()。

依赖

运行库使用以下组件：

• LuminPack：二进制序列化。
• LuminTask：异步任务抽象。
• LuminDelegate。
• LuminObjectPool。
• LuminKcp：KCP 核心实现。

贡献

欢迎提交 Issue 和 Pull Request。提交代码前请确保：

1. dotnet build LuminNet.sln -c Release 构建成功。
2. 不提交 bin/、obj/、IDE 配置和本地压缩包。
3. 协议或公共 API 发生变化时同步更新 README 和示例。

License

本项目基于 MIT License 开源。