Vane.Dispatch
1.1.0
dotnet add package Vane.Dispatch --version 1.1.0
NuGet\Install-Package Vane.Dispatch -Version 1.1.0
<PackageReference Include="Vane.Dispatch" Version="1.1.0" />
<PackageVersion Include="Vane.Dispatch" Version="1.1.0" />
<PackageReference Include="Vane.Dispatch" />
paket add Vane.Dispatch --version 1.1.0
#r "nuget: Vane.Dispatch, 1.1.0"
#:package Vane.Dispatch@1.1.0
#addin nuget:?package=Vane.Dispatch&version=1.1.0
#tool nuget:?package=Vane.Dispatch&version=1.1.0
Vane.Dispatch
一个容器无关、高性能、AOT 友好的 .NET 服务分发引擎。前身 Ndf 已在公司内部多个项目中长期生产验证,现正式开源。
Vane.Dispatch 是一个微内核:按特性(Attribute)将调用路由到控制器操作,绑定请求模型,执行过滤器管线,并基于接口生成代理。它只依赖一个最小的 ServiceResolver 委托,与任何 DI 容器、任何通信层都零耦合。你可以自己提供解析器(或任意 IServiceProvider)、自己的控制器、自己的线格式。
所有公开类型统一归属 Vane.Dispatch 命名空间;通过 GlobalUsings.cs 汇总全局 using,源码内不含散落的 using 指令。
特性
- 容器无关 —— 只依赖 BCL(双目标
net8.0/net10.0)。通过ServiceResolver委托解析控制器,或用任意IServiceProvider作为适配。 - 特性路由 —— 类级
[Route](声明可分发 + 组名 + 默认自动绑定)、方法级[Route](操作契约名 / 别名)、[NoAutoBind](关闭自动绑定推断),查表大小写不敏感,支持重复操作检测。 - 模型绑定 —— Body / Route / Header / Query / Services 值提供器与类型转换,支持
[FromBody]/[FromRoute]/[FromHeader]/[FromQuery]/[FromServices]。 - 过滤器管线 —— 全局与操作级过滤器;
OnExecuted对标 MVC 三态恒运行(成功 / 异常 / 取消均执行,上下文携带Exception/Canceled/ExceptionHandled);IExceptionFilter统一处理操作异常,可置ExceptionHandled免除失败判定。内置 DataAnnotations 校验(含IValidatableObject),用UseValidation()一键启用(对标 MVC 默认自动校验)。 - 格式化器 —— 内置 JSON 与原始字节,另提供扁平二进制
FlatBinaryFormatter(需手动注册),可插入自定义二进制协议(如 MessagePack)。 - 接口代理 ——
CreateProxy<T>()把任意接口变成进程内强类型客户端。 - 自由端点 —— 对标 Minimal API 的
Map/MapGet/MapPost/Handle,注册委托端点。 - 性能 —— 路由表预构建;热路径分发采用表达式编译调用器而非反射。
- AOT 友好 ——
IsAotCompatible/IsTrimmable已开启;反射相关公开 API 均有[RequiresUnreferencedCode]/[RequiresDynamicCode]/[DynamicallyAccessedMembers]标注,裁剪与 NATIVE AOT 场景可得到准确警告。
快速开始
从 NuGet 安装:
dotnet add package Vane.Dispatch
定义一个控制器(类级 [Route] 的模板即路由组名,缺省时取类型名去掉 Controller 后缀):
using Vane.Dispatch;
[Route("math")]
public class MathController
{
public int Add(int a, int b) => a + b;
public int Square(int x) => x * x;
}
用自己的解析器构建引擎(此处是一个基于 Activator 的极简解析器,仅作演示):
ServiceResolver resolver = serviceType =>
serviceType.GetConstructor(Type.EmptyTypes)?.Invoke(null)
?? throw new MissingMethodException(serviceType.FullName);
var engine = resolver
.BuildDispatchEngine()
.MapDispatchable<MathController>()
.Build();
// 强类型分发
int sum = engine.Dispatch<int>("math", "Add", new { a = 2, b = 3 }); // 5
// 强类型便捷调用
int sq = engine.Send<MathController, int>("Square", 6); // 36
// 接口代理
public interface IMath { int Square(int x); }
var proxy = engine.CreateProxy<IMath>();
int px = proxy.Square(9); // 81
如果你已有
IServiceProvider,直接调用services.BuildDispatchEngine()—— BCL 适配器会把你的 provider 包装成解析委托。无需引入Vane.Container。
批量注册与自由端点
// 扫描整个程序集中带 [Route] 的类型(需保留类型,见“AOT 兼容性”)
var engine = resolver.BuildDispatchEngine()
.MapDispatchablesFromAssembly(typeof(MathController).Assembly)
.Build();
// 注册自由函数端点(对标 Minimal API 的 MapGet/MapPost/Map)
var engine2 = resolver.BuildDispatchEngine()
.MapGet("/ping", () => "pong")
.MapPost("/echo", (string msg) => msg)
.Build();
目录结构
src/Vane.Dispatch 库本体(自包含,双目标 net8.0 / net10.0,全部类型归属 Vane.Dispatch 命名空间)
tests/ 自包含 NUnit 测试套件(不依赖容器或传输层)
examples/ 控制台示例
docs/ 开发者使用手册等文档
子目录(如 Annotations、ModelBinding)仅用于源码归类,不影响命名空间。
AOT 兼容性
Vane.Dispatch 以「兼容标注」方式支持裁剪与原生 AOT:
- 程序集已声明
<IsTrimmable>true</IsTrimmable>与<IsAotCompatible>true</IsAotCompatible>。 - 走反射的公开 API(如
MapDispatchablesFromAssembly、Dispatch<TResult>(object args)、CreateProxy<T>()、JSON 格式化与模型校验)均标注[RequiresUnreferencedCode]/[RequiresDynamicCode],并在目标类型上加[DynamicallyAccessedMembers]。
因此:
- 仅裁剪(Trim):直接可用;只会对确实依赖反射的路径给出可读警告。
- 原生 AOT(NativeAOT):避免
object匿名参数分发与程序集扫描,改用以下 AOT 友好形式,可显著减少警告。Build()自身带RequiresDynamicCode,Native AOT 下仍需为构建入口提供抑制或替换方案:- 用
DispatchRequest.Create(name, op, IDictionary<string, object> args)字典构造请求,而非匿名对象; - 显式
MapDispatchable<T>()注册,而非MapDispatchablesFromAssembly; - 二进制协议选用
RawBytesFormatter/ 自定义IInputFormatter,JSON 请配合JsonSerializerContext源生成或改用二进制。
- 用
异常处理(对标 MVC)
Vane.Dispatch 的异常语义对齐 MVC 的「三段式」:OnExecuted 恒运行 → 异常 / 取消分类 → 结构化错误体。下表给出逐项对标关系。
| MVC 语义 | Vane.Dispatch 对应 |
|---|---|
| 处理器未捕获异常 → 异常过滤器 → 500 | 捕获入 ActionExecutedContext.Exception → 500 |
IExceptionFilter / IAsyncExceptionFilter(可置 ExceptionHandled) |
IExceptionFilter(置 ExceptionHandled 免除 500 / 499) |
OnActionExecuted 在异常 / 取消仍触发 |
OnExecuted 三态恒运行,上下文携带 Exception / Canceled |
| 请求取消 → 抛取消异常(多为 400) | 令牌取消 → 499(RequestCanceled) |
400 + ModelState |
400 + 统一 ModelState(UseValidation() 一键启用) |
RFC 7807 ProblemDetails |
可选 ProblemDetails(成功零分配,失败惰性生成) |
与 MVC 的差异集中在「不绑 HTTP」:异常在分发内收口到响应对象——response.Exception 保留原始异常供进程内调用方查看,ProblemDetails 供跨进程序列化,二者共享同一失败判定,不依赖 HTTP 异常处理中间件。
设计取舍(同步快路径 + 按需异步)
- 默认全同步快路径:
Dispatch、模型绑定、同步过滤器、调用器全同步无Task,不含异步状态机开销。带参数绑定或输出序列化时仍会分配对象,「零分配」只对无参且无过滤器的窄路径成立。跨进程Send阻塞等待。 - 按需异步:
DispatchAsync复用同一同步内核(路由/模型绑定/同步过滤器原样同步),仅对 async 处理器(Task/ValueTask及其泛型)执行 await,并支持IAsyncFilter/AsyncActionFilterAttribute(方法级异步过滤器)。异步只落到真正有 I/O 的地方。 - 取舍:formatter / 路由 / 模型绑定 / 值提供器均为纯 CPU 内存操作,保持同步不套 async(无阻塞点可重叠,套了只加成本)。
- 何时用哪个:CPU 密集处理器用同步
Dispatch(零分配快路径);处理器确实要做 I/O 或需异步过滤器时,改用DispatchAsync。异步 invoker 为惰性编译,纯同步应用不产生常驻异步委托成本。
构建与测试
dotnet build Vane.Dispatch.slnx -c Release
dotnet test tests/Vane.Dispatch.Tests -c Release
库本体开启 XML 文档注释并未抑制 CS1591,构建保持 0 警告。
打包 / 发布
dotnet pack src/Vane.Dispatch -c Release # 产出 Vane.Dispatch.{version}.nupkg
在 src/Vane.Dispatch/Vane.Dispatch.csproj 中设置 Version(当前 1.1.0)。RepositoryUrl / PackageProjectUrl 已指向 https://gitee.com/netcasewqs/vane-dispatch,迁移仓库时同步更新。
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
-
net8.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.