Table of Contents

SDK 参考

插件开发面的完整契约参考。所有类型位于 KernLab.Traffic.Contracts.Plugins 命名空间 （KernLab.Traffic.Contracts 程序集）——契约零 MEDI、零 AspNetCore。

开发面基类（三选一）

基类 管线域 override 目标
HttpFeatureBase 仅 HTTP ExecuteCoreAsync(PluginHttpContext, ct)
L4FeatureBase 仅 L4 ExecuteCoreAsync(PluginL4Context, ct)
UniversalFeatureBase HTTP＋L4 通用 ExecuteCoreAsync ＋ ExecuteCoreL4Async（按上下文面分派）

返回 FeatureResult：

值 语义
FeatureResult.Continue 放行——后续步骤继续
FeatureResult.ShortCircuit(statusCode) 短路——后续步骤不执行，状态码落给客户端

基类的 ExecuteAsync 是桥接执行，勿 override——桥接层负责上下文租用（池化 FeatureContextAdapter）与短路状态码落位。

编排单元声明

[PluginFeature("my-step", Domain = PluginFeatureDomain.Http,
               Description = "目录展示描述")]
  • code 必填（slug）——catalog 键末段 {ns}/{name}/{code}；
  • Domain 与实现类的域标记接口（IHttpPipelineFeature/IL4PipelineFeature/ IUniversalPipelineFeature）交叉校验：不一致＝装载拒绝（权威＝接口）。

PluginHttpContext（HTTP 上下文）

成员组 成员
身份 TenantId / TraceId / RouteCode（未命中 null）/ Settings（编排期冻结参数）
请求 Method / Path / ClientIp / ContentLength（未知 -1）/ RequestHeader(name)（大小写不敏感）/ Query(name) / ReadBodyAsync(buffer)（读毕引擎回卷）
槽位（具名） SlotIndex(slot) / GetSlot(slot) / SetSlot(slot, value) / SlotKind(index)
槽位（强类型） GetString/GetNumber/GetInteger/GetBool/GetJson/GetBytes ＋ 对称 Set*（TryGetSlot<T> 兜底）
响应 ResponseStatus / SetResponseHeader(name, value) / WriteResponseBodyAsync(body)
步骤私有 InternalState（步骤实例内自由状态——非跨步骤通道）

跨步骤数据共享不用 InternalState——走槽位（声明制、可对齐、可跨内核）。

六面可注入服务（能力声明制）

服务 能力键 面
IPluginKv state.kv ns 域存储（TTL/CAS；ns 即协作域）
IPluginEvents events.pubsub {ns}/ 话题前缀发布订阅
IPluginHttp net.call 出站池化客户端
IPluginMetrics metrics.emit 指标
IPluginTracer trace.emit 子 span（自动挂 TraceId/父 span）
IPluginLogger （默认授予） 日志

声明制授权的落地在 DI 层：未声明能力→桥不注册→构造解析即失败——比运行期 if 检查更硬。headers/query 投影门（http.headers/http.query）作用于 WASM/gRPC 数据面投影。

启动与 DI

public sealed class Startup : IPluginStartup
{
    public void ConfigureServices(IPluginServiceRegistrar registrar)
        => registrar.AddSingleton(typeof(IMyStore), typeof(MyStore));
}
  • 可选钩子——缺省走内核模板化启动（SDK 桥照注入、特性发现照做）；
  • 三形态注册：Singleton / Transient / Scoped（插件容器语义＝容器级单例）；
  • 特性类构造器声明依赖即自动注入（SDK 六面与自有服务同池）。

后台任务（非管线托管单元）

[PluginBackgroundTask("session-sweep", Kind = PluginBackgroundTaskKind.Periodic,
                      Interval = "00:01:00")]
public sealed class SessionSweep : IPluginBackgroundTask
{
    public string TaskCode => "session-sweep";
    public PluginBackgroundTaskKind Kind => PluginBackgroundTaskKind.Periodic;
    public TimeSpan? Interval => TimeSpan.FromMinutes(1);
    public Task ExecuteAsync(IPluginContext ctx, CancellationToken ct) { … }
}
  • 与管线特性一样是 IPluginFeature 扫描锚点的次级分类——发现即入托管池 （共享线程多路复用，非独占线程）；
  • TaskCode/Kind/Interval 三级回落：特性标注 → 清单元数据 → 类名约定；
  • 清单 backgroundTasks[] 是元数据兜底级。

下一步

Edit this page