二十多个轮子,先交付最吃重的那个:Vane.NET 1.0.0-preview.1 发布

二十多个轮子,先交付最吃重的那个:Vane.NET 1.0.0-preview.1 发布

上一篇交代了二十多个轮子的来历。这一篇轮到 L1,把网络层落到一个能 dotnet add package 的 DLL。

预发布版本:1.0.0-preview.1

目标框架:net10.0 / net11.0

仓库:gitee.com/netcasewqs/vane.net

接着上一篇说

上一篇是《被第三方库坑了二十多年,我把二十多个 .NET 轮子全造了一遍》。

我在那篇里从 .NET 1.0 写到 Native AOT,把二十多个自研库的来路、Vane 的五层架构和四条设计公理都交代了一遍。文末说,新包会一个个补 README、示例、基准报告,再发 NuGet。

这篇就是来还这句账的:轮到 L1,Vane.NET。

Vane 的分层是 L0 基座、L1 网络、L2 Arrow/Parquet、L3 Flow、L4 ELinq/Voltcore/Vane.Sheet。L1 是顶着所有长连接的那一层,也是这次先拿出来交付的一层。

它是什么

Vane.NET 是 Vane 的 L1,一个协议无关的 .NET 网络内核。RPC 的方法名、MQTT 的主题、Redis 的命令字,它都不认识。它只干一件事:

把字节流变成帧,把帧送到业务,再把回包写回去。

八种传输、三种业务入口,一个 Host / ClientBuilder 模型,交付物是一个零第三方依赖的 Vane.NET.dll。

HTTP 服务器和开箱即用的 RPC 框架都不是它的活。它是个底座:自定义协议、RPC、MQTT、管理台、设备长连接,都可以挂到同一套连接、背压、超时、TLS 和观测面之上。

上一篇那几条设计公理,落到 L1 上就变成:不引第三方网络库;只认帧,不认协议;公开面尽量小;正常帧路径不复制、不排队、不造多余 Task。

一个 TCP 回显,Demo 二十行,上线两千行

网上随便找个 TCP 回显,核心代码二十行:Accept、读、写、循环。

真放到线上,二十行会变成两千行:

  • 粘包、半包、帧边界;
  • 连接断了之后的清理;
  • 空闲超时、心跳、优雅停机;
  • 对端不读数据时的背压;
  • TLS 握手和证书;
  • 每条连接的状态放在哪;
  • 出问题之后,日志、指标、事件在哪看;
  • 几十条命令之后,那个越来越长的 switch。

这些活没有一件是业务,但没有一件能省。少写一个清理,连接就漏;少处理一次背压,内存就涨;少记一个异常,半夜就得靠猜。

Vane.NET 想干的,就是把这些重复活从每个项目里抽出来,做成一个可以单独发 NuGet 的内核。业务还是写业务,网络层别再每次从 Socket 开始。

现成的不是不能用

Kestrel 是很好的 HTTP 服务器。但你要跑一条自定义二进制协议时,没必要把 HTTP 的语义也背过去。

DotNetty 能力很全,但它的 API 带着 Netty 的影子,依赖和抽象都比"一个 DLL"重。

SuperSocket 更接近命令式服务端,命令路由做得不错,但它不是冲着"协议无关 + 多传输 + 微内核"去的。

NetCoreServer / TouchSocket 起步快,但当你需要自己控制帧、背压和线程归属时,还是得往底层走。

这些都不是"不行",是站位不同。Vane.NET 没打算替它们,只想在更下面做一层更薄、更协议无关的连接底座。

我自己给这个底座定了几个限制:

  • 内核只认帧,不认协议;
  • 传输用 BCL 原语,不引第三方网络库;
  • 公开面尽量小,语法糖用扩展方法;
  • 装配期定稿,运行期不读可变配置;
  • 热路径不复制、不排队、不造多余 Task。

我知道这话听起来像"又一个轮子"。这次我认,轮子就轮子,能转就行。

这次先发三个包

包 作用 依赖
Vane.NET 纯托管网络内核,单 DLL 交付 零第三方依赖,仅 BCL
Vane.AspNetCore 把 Vane Host 接入 ASP.NET Core / Generic Host Microsoft.AspNetCore.App + Vane.NET
Vane.Mcp MCP 2025-11-25 legacy 服务端协议包,stdio + Vane WebSocket Vane.NET
bash 复制代码
dotnet add package Vane.NET --version 1.0.0-preview.1
dotnet add package Vane.AspNetCore --version 1.0.0-preview.1
dotnet add package Vane.Mcp --version 1.0.0-preview.1

这是预发布,正式 1.0.0 还没发。预发布期间 API 和包边界都可能调整;正式版前会把公开 API 基线整体转入 Shipped,用门禁拦截破坏性变更。

Vane.Rpc、Vane.Mqtt、Vane.Dispatch 已经拆成独立仓库。内核不依赖它们,也不会把它们的协议类型塞进公开面。

先跑起来

一个 TCP 回显服务:

csharp 复制代码
using System.IO.Pipelines;
using Vane.Hosting;

await using Host host = Host.CreateDefault().ListenLocalhost(8080);

await host.StartAsync(async connection =>
{
    PipeReader input = connection.Transport.Input;
    PipeWriter output = connection.Transport.Output;

    while (true)
    {
        ReadResult result = await input.ReadAsync();

        foreach (ReadOnlyMemory<byte> segment in result.Buffer)
            await output.WriteAsync(segment);

        input.AdvanceTo(result.Buffer.End);

        if (result.IsCompleted || result.IsCanceled)
            break;
    }

    await output.CompleteAsync();
});

这段代码里没有 Socket、没有线程池、没有连接字典。Host.CreateDefault() 装八种内置传输工厂;ListenLocalhost(8080) 只是登记意图;监听、接受连接、连接归属和资源释放,由 StartAsync 和 await using 接管。

如果只想用一两种介质,可以 new Host().AddListenerFactory(...),不用把全部工厂带上。

客户端也不用另起一套:host.CreateClient() 返回 ClientBuilder,共享宿主已经建好的 EventLoopGroup,只借用,不释放。

八种传输,一套连接模型

介质 端点/入口 典型用途
TCP IPEndPoint 通用长连接、私有二进制协议
UDS UnixDomainSocketEndPoint 本机进程间通信
NamedPipe NamedPipeEndPoint Windows 本机服务
InProcess InProcessEndPoint 单元测试、同进程模块通信
HTTP HttpEndPoint HTTP 协议入口与升级场景
WebSocket WebSocketEndPoint 浏览器、跨端长连接
QUIC QuicEndPoint 多路复用与低延迟场景
UDP UdpEndPoint 数据报、游戏、指标采集

UDP 单独用 UdpServerBuilder,没有硬塞进面向连接的 Host。数据报本来就没有"连接生命周期",套连接模型只会让两边都别扭。

三种开发模式,同一套内核

Vane.NET 对外就三种挂法,底座是同一套。别把它当成三套网络库。

管线模式:自由归你,收尾也归你

前面的回显就是管线模式。你拿到 IConnection,直接操作一对 Pipe:

text 复制代码
客户端写 → 服务端 Input → 你的代码读
你的代码写 → 服务端 Output → 客户端读

它适合自定义握手、代理/隧道、流式协议、多路复用,或者你本来就想自己控制每一段字节。

自由归自由,AdvanceTo、CompleteAsync、EOF、异常、背压也全是你的。少一个,连接就可能卡住。

如果只是不想手写拆包,可以用 StartFramedAsync,把分帧交给 IFrameDecoder,业务只收完整的帧。

会话模式:每个连接一张档案卡

会话模式在管线之上加了一个每连接一份的 ConnectionSession。框架管生命周期,你管业务状态:

csharp 复制代码
sealed class CounterSession : ConnectionSession
{
    private int _count;

    protected override ValueTask OnConnectedAsync(CancellationToken ct)
        => SendAsync("welcome\n", ct);

    protected override ValueTask OnReceivedAsync(
        ReadOnlySequence<byte> frame, CancellationToken ct)
    {
        _count++;
        string text = Encoding.UTF8.GetString(frame.ToArray());
        return SendAsync($"{_count}: {text}\n", ct);
    }
}

await using Host host = Host.CreateDefault()
    .UseSession<CounterSession>(new LineCodec())
    .MapSession<CounterSession>(new IPEndPoint(IPAddress.Loopback, 0));

await host.StartAsync();

同一个会话的 OnReceivedAsync 默认在它所属的 loop 线程上串行执行,所以 _count 不用锁。不同会话之间可以并行,每个会话自己的状态是串行的。

它适合聊天室、游戏房间、设备会话、协同编辑这类"每条连接有状态"的业务。每连接一个对象,字段要克制,大缓存别塞会话里。

命令模式:会话 + 按"动词"派单

命令模式就是"会话模式 + 命令路由"。每个连接仍然有一个 CommandSession<TKey>,但 OnReceivedAsync 被框架固定成:

text 复制代码
解析 Key → 查注册表 → 前置 filter → handler / OnUnknown → 后置 filter → 写回

你不再写大 switch,而是把命令登记到注册表:

csharp 复制代码
sealed class CommandChatSession : CommandSession<string> { }

await using Host host = Host.CreateDefault()
    .UseCommandSession<CommandChatSession, string>(new LineCodec(), commands => commands
        .UseKeyResolver(CommandRegistry<string>.FirstTokenKey())
        .OnUnknown(ctx => ctx.Session.SendAsync("unknown: " + ctx.Key, ctx.CancellationToken))
        .Map("ECHO", ctx => ctx.Session.SendAsync(ctx.Frame.ToArray(), ctx.CancellationToken))
        .Map("QUIT", ctx =>
        {
            ctx.Session.Disconnect();
            return ValueTask.CompletedTask;
        }))
    .MapSession<CommandChatSession>(new IPEndPoint(IPAddress.Loopback, 0));

await host.StartAsync();

注册表在装配期冻结:重复 key、缺 OnUnknown、缺 UseKeyResolver、filter Order 冲突,都会在启动前报错。命令对象是无状态单例,连接状态别往命令字段里塞;放 CommandContext.Session 的字段。

要审计、鉴权、限流,就在 .Map 前挂 .UseFilter(...)。别在每个命令里抄一遍。

怎么选

你会怎么回答这个问题 选哪种
"我只想拿到字节,自己拆、自己写" 管线
"每条连接要记登录态、订阅列表、最后活跃时间" 会话
"协议有一堆动词,希望一条命令一个处理函数" 命令
"我要做代理、隧道、多路复用、极高帧率" 管线
"我要统一做鉴权、审计、限流" 命令的 filter

底座还是同一套:Host、传输、TLS、PROXY、Pipe、EventLoop、帧编解码、中间件、背压、异常收口和观测。差别只在业务入口放哪、谁持有每连接状态、谁做消息路由。

内核的骨架:两条 Pipe,不套娃

我不太喜欢在内核里再搭一套 HandlerPipeline,让用户往里面塞 decoder、encoder、业务 handler。Vane.NET 没这么干。

原因很实际:BCL 已经有一套 Pipe。再套一层,背压、游标推进、异常收口就会出现两套语义。两套语义放在同一个连接上,迟早要打架。

所以 Vane.NET 的"管道"只有两层:

  1. 连接级中间件:每条连接执行一次,顺序是 PROXY → TLS → 建点屏障 → 宿主中间件 → 终端。
  2. 帧级中间件 :每帧执行一次,IConnectionMiddleware.InvokeAsync(context, next)。

再往上,就是 Session / Command 或协议插件自己的世界。

几条硬约束:

  • 正常 TCP/UDS 帧路径不复制、不排队、不造 Task;帧是 ReadOnlySequence<byte> 的切片,跨帧或跨线程持有才复制。
  • 背压靠两条 BCL Pipe 的 pause/resume 水位,不另建帧队列。
  • 连接建立时固定到某个 EventLoop;业务回调、会话生命周期、出站写 Pipe 都归这个 loop。
  • 启动是一个事务:装配期只记录意图,StartAsync 逐步建点,任一步失败就回滚,不留下半开的监听器。
  • 装配期定稿,运行期不读可变配置。避免"新连接生效、老连接不生效"的隐性不一致。

这些约束听起来有点轴。可网络层最怕的就是"看起来能跑",实际上背压、关闭、异常三条路径各有一套逻辑。

role:一个 Host 里的多个业务角色

一个 Host 不一定只干一件事。

role 是服务端多业务、客户端多连接/重连的边界。一个 Host 可以同时挂 TCP 聊天、WebSocket 管理端,或者多个不同会话类型;每个 role 有自己的端点、会话类型或协议泵、业务代码,但共享同一个 Host 的资源、生命周期和观测面。

它不是鼓励你多开业务。只有一个业务、一个端点时,单 StartAsync(application) 或单会话更短;role 是为"多业务/多端点/多连接管理"付的装配成本。

协议插件,不该住进内核

内核只认帧。拆仓就是按这条边界拆的。

  • Vane.Rpc 自己处理请求/响应、连接池、序列化;
  • Vane.Mqtt 自己处理主题、QoS、会话;
  • Vane.Dispatch 自己做服务分发;
  • Vane.NET 只把连接、帧、背压、超时、TLS 和观测面交给它们。

所以 Vane.NET 的包不依赖 RPC/MQTT,也不会因为某个协议新增字段就把内核公开面撑大。协议插件坏了换插件,内核坏了才动内核。

跟 Kestrel 一起干活

Vane.AspNetCore 不换掉 Kestrel。

它把 Vane Host 注册成 IHostedService,让 Kestrel 和 Vane 共享同一个 Generic Host 生命周期:app.StartAsync() 同时启动两者,app.StopAsync() 同时停止两者。

csharp 复制代码
builder.Services.AddVaneServer(options =>
{
    options.Host.ListenLocalhost(7000);

    options.UseApplication(async connection =>
    {
        await connection.Transport.Output.WriteAsync("hello from vane"u8.ToArray());
        await connection.Transport.Output.CompleteAsync();
    });
});

Kestrel 继续处理 HTTP;Vane 处理需要长连接、私有协议或自定义帧的流量。两者共享 DI:单例从根容器取,scoped 服务按连接创建 scope。

Vane.Mcp 是另一个可选包,提供 MCP 2025-11-25 legacy 服务端协议,支持 stdio 和 Vane WebSocket。它同样不把 MCP 类型塞进内核公开面;不用 MCP 的人,不会在 Vane.NET.dll 里看到它。

验证数字

发布前我跑了 Release 构建、三套测试、gate 和三包打包。

项目 结果
Release 构建 0 错误
Vane.NET.Tests 738 通过 / 0 失败
Vane.AspNetCore.Tests net10.0 19 通过;net11.0 19 通过
Vane.Mcp.Tests net10.0 66 通过;net11.0 66 通过
合计 908 通过 / 0 失败
公开 API 三包 1630 条,added=0 / removed=0
gate 22 项,Fail=0
长稳 10 万空闲连接 / 1800 秒,RSS 增量约 38 MB,Gen2 = 1 次

Vane.NET 单包公开面是 156 个类型、1089 个成员,1245 条 API 基线;Release net10.0 的 Vane.NET.dll 约 440 KB。

这些数不全面。gate 里还有 Partial / Unmeasured,正式 1.0.0 前还得补;预发布期间 API 也可能动。我没打算把这些藏起来,先原样摆在这儿。

适合谁

  • 要写自定义 TCP/UDP/QUIC/WebSocket 协议,但不想从 Socket 开始搭;
  • 希望同一套代码支持多种传输,测试用 InProcess,上线换 TCP 或 QUIC;
  • 想要零第三方依赖、单 DLL、可嵌入的边缘服务;
  • 需要每连接状态、命令路由、统一 filter,但不想引入 DI 容器和反射扫描;
  • 想把 RPC/MQTT 这类协议做成插件,而不是让内核替它做协议语义。

不适合:

  • 只提供 HTTP API。Kestrel 已经够好,看到这儿就可以关掉页面;
  • 想要开箱即用的 RPC/MQTT 框架。直接用 Vane.Rpc / Vane.Mqtt;
  • 习惯注解扫描、自动依赖注入、动态路由注册。Vane.NET 的装配是显式的,不走反射;
  • 需要内核直接理解业务协议。它只认帧,不认方法名和主题。

写到这儿

1.0.0-preview.1 离"功能都做完"还早。现在能说的是:传输、帧、连接治理、三种业务入口、观测面和可选集成包都跑通了,公开面也收到了可以被外部使用的程度。

后面先把预发布期间暴露的问题收掉,把 gate 里的 Partial / Unmeasured 补齐,再发正式 1.0.0。

如果你也写过那种"Demo 二十行、上线两千行"的网络服务,可以拿个最小示例跑跑,再把你的场景丢给它。它不一定合你的场景;要是你正好缺这层底座,拿去试试,能少熬几个夜就算没白写。