Table of Contents

写第一个 HTTP 插件

本页从零写一个可装载、可编排的 HTTP 插件步骤：鉴权令牌检查——缺头短路 401，有头放行。 示例代码按当前 SDK 契约编写，类型与方法名与 KernLab.Traffic.Contracts 程序集逐字一致。

1. 工程与引用

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="KernLab.Traffic.Contracts" Version="*" />
  </ItemGroup>
</Project>

SDK 契约零 MEDI、零 AspNetCore——引用 Contracts 即可编译，不引入宿主框架。

2. 写特性类

using KernLab.Traffic.Contracts.Plugins;

[PluginFeature("token-check", Domain = PluginFeatureDomain.Http,
               Description = "校验 X-Api-Token 请求头")]
public sealed class TokenCheckFeature : HttpFeatureBase
{
    protected override ValueTask<FeatureResult> ExecuteCoreAsync(
        PluginHttpContext context, CancellationToken ct)
    {
        var token = context.RequestHeader("X-Api-Token");
        if (string.IsNullOrEmpty(token))
            return ValueTask.FromResult(FeatureResult.ShortCircuit(401));

        // 与后续步骤/上游共享的值：写槽位（声明 produces 后可见）
        context.SetSlot("acme:token-checked", "1");
        return ValueTask.FromResult(FeatureResult.Continue);
    }
}

要点：

  • 继承 HttpFeatureBase，override ExecuteCoreAsync——强类型 PluginHttpContext 以参数传入，无强转、无接口成员动物园；
  • [PluginFeature("code")] 的 code＝编排单元标识（catalog 键末段 {ns}/{name}/{code}）；
  • FeatureResult.Continue 放行；FeatureResult.ShortCircuit(401) 短路——后续步骤 不执行，401 落给客户端；
  • 槽位键 {ns}:{slot} 两段 slug——acme 即本插件命名空间。

3. （可选）启动钩子与服务

轻量插件到此为止。需要自有服务（连接池/缓存客户端）的插件加启动钩子：

public sealed class Startup : IPluginStartup
{
    public void ConfigureServices(IPluginServiceRegistrar registrar)
        => registrar.AddSingleton(typeof(ITokenStore), typeof(TokenStore));
}

特性类构造器声明依赖即自动注入（SDK 六面服务与自有服务同池）。 Scoped 在插件容器语义下＝容器级单例（包即作用域）。

4. 清单

包根放 manifest.json（清单 v2——字段只增）：

{
  "specVersion": 2,
  "namespace": "acme",
  "name": "token-check",
  "version": "1.0.0",
  "mode": "Assembly",
  "entry": { "assembly": "Acme.TokenCheck.dll", "startup": "Startup" },
  "capabilities": []
}
字段 语义
namespace/name/version 插件身份三元组（ns 即隔离与协作域）
mode Assembly（ALC 内核——缺省）｜Wasm｜Grpc｜Script｜Subprocess
entry.startup 可选——缺省走内核模板化启动
capabilities 能力声明制授权（state.kv/events.pubsub/net.call/metrics.emit/trace.emit/http.headers/http.query）——未声明的能力注入面不注册（构造解析即失败），声明×内核矩阵另有 fail-fast 门

5. 安装与编排

# 安装：清单 v2 JSON 走 --body；按清单 distribution 分发（tenant 私有域／platform 平台公共面）
traffic-worker plugin install --body @manifest.json --admin http://127.0.0.1:7901

# 目录确认（catalog 出现即发现成功）
traffic-worker plugin catalog --admin http://127.0.0.1:7901

（包体上传/远端仓库/签名信任的完整流程见包仓库与信任。）

编进路由链——图节点用 step＋mode 双字段标识插件来源：

{ "id": "n1", "step": "token-check", "mode": "plugin:acme/1.0.0",
  "canvas": { "x": 120, "y": 80 } }

插件变更走 draft→publish——热切换不停机。

下一步

Edit this page