Go SDK
framework-sdk-go 是 XiHan Spec 的 Go 实现:原语层、清单、调用上下文、管道、操作契约与进程外插件运行时,以及 caching.distributed@1 远程 Provider 的插件侧。用它可以写在 .NET 宿主(XiHan.Framework)里运行的 Go 插件,也可以把同一套原语用在 Go 应用里。规范以 submodule 放在 SDK 仓库的 spec/,一致性由规范仓库的向量与黑盒运行器验证;.NET 是参考实现,SDK 的行为与它一致。宿主一侧怎样加载、配置插件与处理失败见进程外插件。
安装
go get github.com/xihanfun/framework-sdk-go需要的 Go 版本见 SDK 仓库的 go.mod。验证插件用的黑盒运行器在规范仓库:
go install github.com/xihanfun/framework-spec/conformance/cmd/xihan-conformance@latest模块
| 包 | 内容 | 规范 |
|---|---|---|
primitives | Error / 错误码、Result[T]、Maybe[T]、ID[Tag, V]、LifecycleState、PipelineStage、Stability、Baggage 键、消息键与模板、FrameworkError | RFC-0001、RFC-0010、conventions/ |
manifest | xihan.manifest.json 的模型、读取、规范化输出与校验,能力声明与依赖文本 | RFC-0002、manifest/manifest.schema.json |
invocation | Context:取消与截止时间(嵌入 context.Context)、W3C 追踪、已登记的 Baggage、对象袋;超时与取消翻译为 KERNEL_TIMEOUT_001 / KERNEL_CANCELLED_001 | RFC-0003 |
pipeline | 十一阶段的 Builder:Use / UseAt / UseNamedInstance、Before / After、Describe / Dump、Build;排序规则与错误码 KERNEL_PIPELINE_00x | RFC-0004 |
operation | Contract、Schema、Handler[Req, Res]、Registry、经完整管道执行的 Invoker(XGI:JSON 请求与响应) | RFC-0011 |
plugin | 进程外插件运行时 Serve:启动前的清单核对、环境变量、监听(unix 套接字在私有目录里 / 127.0.0.1 的 tcp / 只允许当前用户的 npipe)、握手行、xihan.plugin.v1 服务端(每次调用先核对宿主的会话令牌,再按调用次序表)、生命周期状态机与健康推送、事件投递、停止与收尾的时限、宿主回调客户端 Host(选回调端点、发出前本地核对权限与租户)、宿主可解析的 JSON 日志、消息目录与运行时自己的目录 | RFC-0017、plugin/ |
plugin/v1 | 由 spec/plugin/plugin.proto 生成的协议代码(buf generate) | plugin/plugin.proto |
caching | caching.distributed@1 远程 Provider 的插件侧:Store 是 RFC-0006 的六个原子存储操作加三个批量操作(conventions/batch-first.md),MemoryStore 是有界的进程内实现,RegisterOperations 把任何 Store 暴露成操作集,让 .NET 宿主的 Caching.Remote 适配器把这个插件当作分布式缓存 Provider | RFC-0019、RFC-0006、provider/caching-distributed.md |
examples/echo | 回声插件:操作、订阅、健康、配置、宿主回调;cmd/echo-go 是可执行入口 | — |
examples/cache | 远程缓存 Provider 示例插件:用 caching.MemoryStore 实现操作集,配置节 XiHan:Cache;cmd/cache-go 是可执行入口 | — |
快速开始
一个最小的插件:一份清单 xihan.manifest.json、一个操作,交给 plugin.Serve。
package main
import (
"context"
_ "embed"
"os"
"github.com/xihanfun/framework-sdk-go/invocation"
"github.com/xihanfun/framework-sdk-go/operation"
"github.com/xihanfun/framework-sdk-go/plugin"
"github.com/xihanfun/framework-sdk-go/primitives"
)
//go:embed xihan.manifest.json
var manifest []byte
type CreateRequest struct{ Text string `json:"text"` }
type CreateResponse struct{ Text, Tenant string }
func main() {
registry := operation.NewRegistry()
_ = operation.Add(registry, operation.Contract{ID: "echoes.create", Stability: primitives.Experimental, Expose: []string{operation.ExposeHTTP}},
operation.HandlerFunc[CreateRequest, CreateResponse](func(ctx *invocation.Context, request CreateRequest) primitives.Result[CreateResponse] {
return primitives.Ok(CreateResponse{Text: request.Text, Tenant: ctx.Tenant()})
}), nil, "")
if err := plugin.Serve(context.Background(), plugin.Options{Manifest: manifest, Operations: registry}); err != nil {
os.Exit(1)
}
}清单、操作、订阅、日志与退出的写法逐条见下一节写一个插件。
在 Go 应用里用原语
ctx := invocation.Background(invocation.WithTimeout(2*time.Second), invocation.WithBaggage(map[string]string{primitives.BaggageTenant: "t1"}))
builder := pipeline.NewBuilder().UseAt(observe, primitives.Observe, pipeline.End, "app")
invoker, _ := operation.NewInvoker(registry, builder)
response := invoker.Invoke(ctx, operation.Request{ID: "orders.create", Payload: []byte(`{"quantity":2}`)})Result[T]、Error、Maybe[T] 的 JSON 编码与 .NET 参考实现一致({"ok":true,"value":…} / {"ok":false,"error":{…}}),生命周期迁移表、管道阶段顺序、错误码与 Baggage 键文法都由 spec/conformance/vectors 验证。
写一个插件
快速开始里的插件按这几条写成:
- 清单
xihan.manifest.json:kind: plugin、isolation: out-of-process、contributes.operations列出全部操作、entry是可执行文件名;不写contributes.pipeline(只有 Wasm 插件能贡献中间件,plugin.Serve读到非空即拒绝,与宿主发现插件时一致;manifest.Read照 .NET 的ManifestReader不查这一条);构建产物目录里放同一份文件,宿主读它、运行时握手时原样发送。 - 操作用
operation.Add登记,请求与响应是普通的 JSON 结构;可恢复失败返回primitives.Fail,错误码按<领域大写>_<KIND>_<NNN>,文案用消息键 +plugin.LoadCatalog加载的Localization/<区域>.json。 - 订阅、生命周期回调、健康项经
plugin.Options接入;Configure回调里用configuration.Decode(&settings)读配置节(宿主以字符串下发数字与布尔,按字段类型转换,见下文插件运行时);操作里用plugin.HostOf(ctx)回调宿主(Invoke经宿主完整管道,Publish经宿主消息代理),权限由清单permissions声明、宿主授予,发出之前在本地核对。订阅的Mode选订阅方式(RFC-0009「订阅方式」):空或plugin.SubscriptionModeCompeting是竞争消费,订阅了主题的宿主实例里只有一个把消息交给插件;plugin.SubscriptionModeBroadcast是广播,每个在线的宿主实例都交给自己的插件实例,尽力而为、不进死信,适合清本地缓存这类每个实例都要做的事。同一(主题,类型)对只能声明一次,不能以两种方式各声明一次,Serve启动时即拒绝;同一主题的不同类型可以各用一种方式,宿主投递时带上这次的方式,运行时只交给以这种方式声明的处理器。 - 日志写 stderr:
slog.New(plugin.NewLogHandler(os.Stderr, slog.LevelInfo)),宿主按结构化日志接收;stdout 只有握手行。 - 宿主调用
Stop、关闭 stdin 或发 SIGTERM 后Serve返回 nil,进程以退出码 0 退出;收尾的次序与时限见插件运行时。
验证:xihan-conformance plugin --dir <产物目录>(规范仓库的黑盒运行器,go install github.com/xihanfun/framework-spec/conformance/cmd/xihan-conformance@latest)。examples/echo 的测试就是这样对 echo-go 跑全部用例。运行器自带一份协议生成代码,与本 SDK 的 plugin/v1 不能链接进同一个二进制,所以在测试里以独立进程运行它,而不是导入它的库。
更完整的写法见 SDK 的 examples/echo(操作、订阅、健康、配置与宿主回调)与 examples/cache(远程缓存 Provider)。XiHan.Framework 的 framework/samples/EchoGoPlugin 与 CacheGoPlugin 只有可执行入口、同一份清单与 Go 模块文件,实现来自这两个示例,是它们在 .NET 宿主里的端到端运行。宿主一侧的协议、握手与生命周期、代理操作、回调与远程 Provider 的配置见进程外插件。
与宿主共用的行为
Result 的线上编码(RFC-0001):有值的成功 {"ok":true,"value":…},value 必填,只有值类型是 Maybe 时才可以是 null;没有值的成功(Result[Unit]、Success()){"ok":true},不写 value;失败 {"ok":false,"error":{…}},error 必填、不带 value。读取时 ok 缺失或不是布尔值、成功带 error、没有值的成功带 value 都拒绝,任何一层的重复成员名(如两个 ok,或 value、details、inner 里面的)也拒绝,成员名区分大小写,未知成员忽略。
Error 的线上编码(RFC-0001):成员按 code、message、messageKey、details、inner 的顺序写出;message 总是写出,messageKey 只在有键时写(Literal 没有键),details 为空、inner 没有时不写。读取时 code 必填且合法,message 必填、是字符串,不能为空也不能只有空白,messageKey 有就必须合法,details 必须是 JSON 对象、inner 必须是错误对象(null 与数组都拒绝),成员名区分大小写,未知成员忽略。空白指 RFC-0001「空白字符」写死的 25 个码位(U+0009–U+000D、U+0020、U+0085、U+00A0、U+1680、U+2000–U+200A、U+2028、U+2029、U+202F、U+205F、U+3000;rules.IsWhitespace,与握手行同一个函数),U+001C–U+001F 与零宽空格不是空白。Literal 与 WithText 的自由文本照同一规则,为空或只有空白时以 PRIMITIVES_VALIDATION_001 panic。
读取的 JSON 文本(Result 与 Error 的线上编码、操作载荷、清单)先过同一遍检查(RFC-0001「JSON 文本」,ADR-0236):语法按 RFC 8259(没有注释、尾逗号、单引号、NaN / Infinity、前导零、正号与多个根值,空文本与只有空白也不是 JSON),文本是 UTF-8,开头的 BOM 是语法错误;嵌套不超过 64 层(最外层是第 1 层);字符串与成员名必须是合法的 Unicode,非法 UTF-8、过长编码、编码成 UTF-8 的代理项、原始控制字符、非法转义与孤立的代理项转义都拒绝;任何一层都不能有重复的成员名,名字按转义还原后比较("a" 与 "\u0061" 重复),大小写不同不算重复。语法错误优先,位置只写 $;否则报第一处重复(第二次出现的成员)的路径。encoding/json 不查重复成员、把孤立的代理项换成 U+FFFD、嵌套上限是 10000,这一步由 SDK 内部的检查(internal/jsontext)先做,与一致性模块的 rules.CheckJSONText 回放同一份 json-text.json。
线上的数字按值模型往返(RFC-0001「Result」与 RFC-0010「模板」的值模型,ADR-0236):Error 的 details(插件协议 Error.details 的 JSON 文本也一样)按值模型读时,64 位有符号范围内整数写法的数字是 int64,原样往返(9007199254740993 不会变成 9007199254740992),其余是 float64,1e400 为无穷;写出时整数值的浮点带小数点(2.0、-0.0,范围外如 1E+17),对方读回的仍是浮点,float32 先换成最接近的 float64(float32(0.1) 写 0.10000000149011612),超出 int64 的无符号整数按浮点写,NaN 与无穷写成字符串 "NaN"、"Infinity"、"-Infinity"。字符串只转义必须转义的字符("、\、控制字符),<、>、& 与非 ASCII 原样。类型化的值(Result[Order]、Maybe[T]、ID[Tag, V])按与操作载荷相同的规则解码,见下文「操作载荷」;Result[any] 与值里的 any 是任意 JSON,数字读成原文的 json.Number,写回时与读到的相同。
操作载荷
operation.Invoker.Invoke 把载荷解码成请求类型的规则照 RFC-0011 规则 2(ADR-0236,与 .NET 的 System.Text.Json 缺省读取选项一致,不随 encoding/json 的习惯)。失败都是 KERNEL_VALIDATION_001 + kernel.operation.invalid_payload,reason 是第一处问题的 JSON 路径:
- 空载荷等价于
{};先过上面的共同检查,语法错误写$,重复成员写第一处重复的路径;载荷是null写$。 - 成员名区分大小写(
encoding/json不区分),未知成员忽略;数字不从字符串读,字符串也不从数字读(字段带json:",string"时除外)。 - 整数字段不接受小数点与指数(
1.0、1e2都不是整数),超出字段类型的范围即不符(int32字段收到2147483648);浮点字段接受整数写法,1e400上溢为无穷,1e-400为 0,float32按 32 位的范围读。 null:字符串、切片、数组、映射、结构体、指针与any接受,等于没有值(字段保持零值);整数、浮点与布尔(含它们的切片项与映射值)不接受。要接受null的数值或布尔写成指针(*int64、*bool)。- 必填:字段带
xihan:"required"标签即必填(对应 C# 的required),缺少时在所在对象结束时报该对象的路径(根上为$,嵌套如$.inner);只要求成员出现,值为null也算出现。没有这个标签的成员缺少时取零值。 - 按文本顺序报第一处问题:写在前面的类型不符先报,嵌套对象里缺少的成员先于外层后面的类型不符。
- 实现
json.Unmarshaler的类型(time.Time、json.RawMessage等)拿到原文自己解码,失败报它的路径;实现encoding.TextUnmarshaler的类型只接字符串;any是任意 JSON,原样保留读到的值:数字读成原文的json.Number(1e400、超出双精度的整数、2.0与2的区别都在),字符串、布尔、null、[]any与map[string]any照常,处理器原样返回时响应的 JSON 值与原文相等;[]byte读 base64 字符串。载荷的文本按 JSON 值比较,空白、成员顺序、转义与数字的写法不是契约。规范不规定的 Go 自己的类型(ADR-0236 的补充):字段是非空接口(如io.Reader、自定义的Shape接口)时解码报该处的路径,SDK 不猜具体类型,多态的请求由类型自己实现UnmarshalJSON;用户自己的UnmarshalJSON返回错误时报它所在值的路径,不往值的内部定位(SDK 自己的Result、Maybe等例外,它们报到里面)。字段名、嵌入结构体的提升与json标签照encoding/json。
type CreateOrder struct {
Customer string `json:"customer" xihan:"required"` // 必填,null 也算出现
Note string `json:"note"` // 可选,null 等于没有
Quantity int32 `json:"quantity"` // 可选,不接受 null 与 1.0
Discount *float64 `json:"discount"` // 可选,接受 null
Lines []OrderLine `json:"lines"`
Extra any `json:"extra"` // 任意 JSON,数字保留原文
}清单
manifest.Read 的检查顺序与错误照 RFC-0002 解析规则 2(ADR-0236,与 .NET 的 ManifestReader 逐字一致),每一步只报第一处问题,失败都是 *primitives.Error,错误码 KERNEL_CAPABILITY_006(manifest.ErrorCodeInvalidManifest):
- 共同的 JSON 读取检查:不是 JSON 为
kernel.manifest.invalid_json,reason是$;有重复成员时同一个键,reason是第一处重复的路径。Read不跳过 BOM;ReadFile按 UTF-8 读、跳过开头的 UTF-8 BOM,文件不存在为kernel.manifest.file_missing(参数path)。 - 根是
null:kernel.manifest.empty,没有参数。 - 按 Schema 逐项核对:
kernel.manifest.invalid,reason是第一处问题的路径,如$.provides[0].version。成员按文本顺序,各自依次查 Schema 之外的成员(区分大小写)、null、类型、取值,对象与数组进到里面再查;一个对象查完后按required的顺序查缺少的成员。接口版本是不带前导零的正整数,不超过 2147483647,只有requires[].version可以带一个^;中间件名非空,阶段与枚举只认小写名,contributes.health符合^[a-z][a-z0-9.-]*$,contributes.permissions重复时报第二次出现的项,activation至少一项。 - 跨字段约束:插件没有
isolation、非插件写了isolation或permissions、provides重复、requires重复、bindings的名字重复,按这个顺序,键是primitives.manifest.*,参数只有id。
Manifest.Validate 先按 Schema 核对清单写出的形态,再核对跨字段约束,码是 PRIMITIVES_VALIDATION_001(与 .NET 的 Manifest.Validate 一致)。manifest.Write 的排版写死(RFC-0002「写出」):两个空格缩进、LF、末尾不换行、": "、空数组写 []、成员顺序固定、列表总写、role 缺省写 provider、activation 缺省写 ["onStartup"]、$schema 固定,字符串只转义必须转义的字符;与 .NET 一样不做校验。可选的字符串 Package、Entry 与 ConfigContribution.Schema 是 *string:nil 是没写、写出时不写,指向空串是写了空串、写出 "package": "";用 manifest.Text("…") 赋值。
消息模板
模板参数先归到 RFC-0010「模板」的值模型(ADR-0236)——空、布尔、字符串、64 位整数、双精度浮点、数组与对象——再按说明符与区域写出,Go 的类型怎样归见语言映射。数组与对象写成紧凑的 JSON,对象成员按名字的 UTF-16 码元序排序、嵌套的 null 写 null、数字与顶层写法相同,超过 64 层的容器写 null。说明符只认 ^[DdFfNnXx][0-9]{0,2}$,E2、G、P、0.00、yyyy、空说明符、带空格、D100 都按无格式写;D 与 X 只用于整数,X 只用于非负整数,F 与 N 用于整数与浮点,用在别的值上都按无格式写。
格式化可以带区域:primitives.FormatMessageIn(locale, template, arguments)、TryFormatMessageIn、FormatArgumentIn(locale, value, format),Catalog.Resolve 按命中模板的区域取符号(回退到 en-US 的模板按 en-US 写)。区域只改变小数点与分组符,取自规范的固定表:de-DE、es-ES、pt-BR 是 , 与 .,fr-FR 是 , 与 U+202F,ru-RU 是 , 与 U+00A0,en-US、zh-CN、zh-TW、ja-JP、ko-KR、表外的区域与不给区域都是 . 与 ,,区域名不区分大小写。小数点用在无格式的浮点(含指数写法的尾数,de-DE 的 1.5e20 写 1,5E+20)与 F、N 上,分组符只用在 N 上;整数无格式时不分组,D、X 与数组、对象里的数字不受区域影响,负号、NaN、Infinity 也不变。不带区域的 FormatMessage、TryFormatMessage、FormatArgument、FormatValue 与 Describe 按不变文化。
调用器的内置步骤
operation.NewInvoker 在传入的管道的副本里加上三个内置步骤(RFC-0011 规则 10,ADR-0236),名字与 .NET 的内置中间件相同,都按归属 xihan.kernel.core(pipeline.KernelOwner)放在所在阶段的 Beginning,与同位置的其他中间件按 RFC-0004 的规则排序(归属的序数序,app 排在它前面):
- Observe 阶段
ObserveMiddleware:把排在它之后的中间件与处理器的 panic 翻译为KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception;排在它之前的(Ingress 阶段,或 Observe 阶段Beginning上归属排在xihan.kernel.core之前的)panic 原样交给调用方。 - Resilience 阶段
DeadlineMiddleware:进入时截止时间已到即KERNEL_TIMEOUT_001+kernel.invocation.deadline_before_start,后面的中间件与处理器不执行;进入时不核对取消;途中的超时与取消按截止令牌归因。 - Validate 阶段
ValidationMiddleware:原始调用(Invoker.Invoke)在这里把载荷解码成请求,失败即KERNEL_VALIDATION_001;类型化调用(operation.Invoke)跳过。
进入管道前只核对未登记(KERNEL_NOTFOUND_001)与类型化调用的类型不符(KERNEL_VALIDATION_002),按这个顺序。Invoker.Invoke 在管道结束之后才用 encoding/json 把响应编码成载荷,中间件用 operation.ResponseOf(ctx) 看到的是编码之前的响应对象;写不出时(浮点成员是 NaN 或无穷、通道或函数这样序列化不支持的值、MarshalJSON 失败或 panic)以 KERNEL_UNEXPECTED_001 + kernel.invocation.unhandled_exception 结束、没有载荷、不 panic,原因是 FrameworkError 时放进 inner;NaN 不写成 null 或字符串。类型化入口 operation.Invoke 不编码。
取消与截止时间只经 ctx.Done() 与 ctx.Err() 通知(RFC-0003 规则 1,ADR-0236):调用器、内置步骤与插件运行时都在调用方的 goroutine 里同步执行处理器,不中止它、不另起 goroutine 放弃它;令牌触发之后处理器照常返回结果的,调用以那个结果结束,只有处理器把取消写成结果(KERNEL_CANCELLED_001)时才按截止令牌归因。处理器要尽早结束,自己检查 ctx.Done()。Invoker.Pipeline() 返回实际执行的管道(含内置步骤)。
插件运行时
plugin.Serve 对宿主调用的处理照 spec/plugin/handshake.md、lifecycle.md §7 与 invocation.md(ADR-0237),由规范仓库的黑盒运行器 xihan-conformance plugin 的全部用例验证:
- 启动:监听与写握手行之前核对清单与声明(
kind是plugin、isolation是out-of-process、没有contributes.pipeline、primitives等于本 SDK 支持的原语层大版本primitives.SpecVersion、操作都在contributes.operations里、订阅的主题与方式合法且(主题,类型)不重复、目录含en-US),不合即不监听、不写握手行、在 stderr 记一条error并返回错误。健康项由健康回调在运行时给出,名字不在contributes.health里的那时丢掉。清单开头的 UTF-8 BOM 去掉后再读,握手发的也是去掉 BOM 的原文。 - 握手行:地址不含空白(空白的集合同 .NET 正则的
\s,含 U+0085、U+00A0、U+2028 等);tcp只写127.0.0.1:<端口>;缺省监听 unix 套接字,临时目录的路径含空白时改用 tcp。npipe 只允许当前用户(安全描述符D:P(A;;GA;;;<当前用户的 SID>))并拒绝远程客户端;unix 套接字放在新建的0700私有目录里。plugin.ParseEndpoint的规则就是一致性模块的rules.ParseEndpoint。 - 握手应答:
primitives写清单的值;只声明一元操作;订阅按声明顺序,方式总写competing或broadcast;catalogs只有作者的目录,运行时自己的目录不发。 - 会话令牌:元数据里必须恰好一个
xihan-plugin-session值,没有或两个以上都是Unauthenticated;令牌先于一切,包括次序核对与InvokeStream读第一帧。 - 调用次序:
Handshake只在Declared、Configure只在Resolved、Start只在Configured,各接受一次;Stop在Declared、Draining、Stopped之外接受一次;其余组合以FailedPrecondition拒绝、状态不变。Health、WatchHealth、Invoke、InvokeStream、HandleEvent任何状态都可以调用。 - 配置:
configuration为空等同{};通不过 RFC-0001 的共同 JSON 读取检查或不是对象时不调配置回调,PLUGINS_UNEXPECTED_001+plugins.process.failed(phase为configure,reason为the configuration is not a JSON object),进入Failed。Configuration.Decode的成员名按 ASCII 不区分大小写匹配(Unicode 的大小写折叠不算,开尔文符号 U+212A 不等于k),落在数字字段上的字符串合 JSON 数字的文法才当作数字(不带空白、正号与前导零),布尔只认true、false(ASCII 不区分大小写),其余照目标类型的常规读法。 - 启动与就绪:启动回调成功 →
Started→ 有健康回调就立即求一次,按结果进入Ready、Degraded或Failed(报别的状态按Ready,panic 按Degraded),没有就进入Ready→ 然后才应答。只有Ready、Degraded可服务,其余状态的调用与投递为PLUGINS_UNAVAILABLE_001+plugins.process.unavailable(state是状态名)。 - 健康:
Start之前报本地状态、没有健康项、不调回调;可服务期间每次Health求一次回调,只有回调报的Ready、Degraded、Failed改变状态,Failed不再回来;未声明的健康项丢掉、同名只记一条warning;回调 panic 时这一次是Degraded,error为plugins.process.failed(phase为health)、没有健康项,状态也迁到Degraded,之后的结果照常决定状态。WatchHealth先推当前状态,之后状态、健康项或错误变化时推送,可服务期间每 10 秒求一次回调,进入Draining时推一次,应答Stop后结束流。 - 生命周期回调的失败:返回
*primitives.Error原样带出;返回别的error或 panic 算作抛出,为PLUGINS_UNEXPECTED_001+plugins.process.failed,reason是错误的动态类型名,去掉包名、*与泛型实参(*fs.PathError写PathError),panic 写panic;错误的文本与 panic 的值只写进 stderr 日志。 - 停止:启动回调没有成功过的不调停止回调,直接应答
ok;成功过的进入Draining(只从可服务的状态)、拒绝新调用、等在途调用到宽限(grace_seconds为 0 按 5 秒),到时触发它们的取消信号、不再等,再调停止回调(进程里最多一次,reason原样),然后应答;停止回调失败写进StopResponse.status,照常退出。Serve返回 nil,进程以退出码 0 退出。 - stdin 关闭、SIGTERM 与
Serve的上下文结束:可服务的进入Draining,立即触发全部在途调用的取消信号并等它们;启动回调成功过、停止回调还没调过的调一次,reason为shutdown。从收到起最多 3 秒,到时不论是否完成都返回(进行中的Stop也受这 3 秒限制)。取消只经令牌通知,不理会取消的处理器不会被中止,只是不再等它。 Invoke:令牌 → 操作未声明为 gRPCUnimplemented(先于就绪)→ 不可服务为plugins.process.unavailable→ 还原上下文 → 调用器与完整管道;payload为空等同{}。InvokeStream:在流式操作契约的 RFC 之前不提供流式操作。读第一帧,流在第一帧之前结束或第一帧不是start为InvalidArgument,是start为Unimplemented,不论操作是否声明、插件是否就绪。HandleEvent:令牌 → 没有信封或方式不是空、competing、broadcast为InvalidArgument→ 按(主题,方式,类型)找订阅,没有为KERNEL_NOTFOUND_001+plugins.event.unsubscribed(空方式写competing)→ 不可服务为plugins.process.unavailable→ 匹配的订阅按声明顺序依次执行,第一个失败即结果;处理器 panic 为KERNEL_UNEXPECTED_001+kernel.invocation.unhandled_exception。- 上下文(
FromMetadata):trace_parent不合 RFC-0003 文法即没有父 Span;trace_state不进上下文;baggage只留已登记的键;deadline按invocation.md§2 的严格文法读(rules.ParseDeadline),读不出当作没有,生效的截止时间取它与 gRPC 截止时间较早的。invocation.Context以零值的time.Time表示没有截止时间,恰好是0001-01-01T00:00:00Z的截止时间记成晚 1 纳秒(仍是过期)。ToMetadata写 UTC、七位小数、+00:00(.NET 的O格式),trace_state为空。 - 写出错误(
ToProtoError):带消息键的错误text留空,由宿主翻译成调用方的语言;只有Literal写text;details是 JSON 对象文本,没有为空;inner照写。读入宿主写来的错误(FromProtoError、FromStatus,规则就是一致性模块的rules.ReadProtoError、ReadProtoStatus、ReadDetails,向量error-reading.json):错误码不合文法时整个错误换成plugins.process.failed(phase一律为invoke,Host.Publish的结果也一样;reason为invalid error code '<码>';原来的inner丢掉);消息键合文法按键还原、不取text,否则是自由文本(text为空或只有空白则取码);details为空、只有空白、是空对象{}、通不过共同 JSON 读取检查、不是对象,或任何一层有读成双精度会溢出的数时当作没有(下溢读成 0,超出 64 位的整数读成双精度);inner同此;ok为假却没有error、或整个status缺失时,phase为操作 ID(Host.Invoke)或publish(Host.Publish),reason为the host reported a failure without an error。
回调(plugin.HostOf(ctx) 取得的 Host,invocation.md §5):
- 回调端点:
XIHAN_PLUGIN_HOST_ADDRESS是宿主按偏好排序、以;分隔的一个或多个<network> <address>,任何一项不合法整个值不合法;运行时取第一个本 SDK 能连的项(Windows 上npipe、unix、tcp,其他系统unix、tcp),之后不换。.NET 宿主在 Windows 上给命名管道加回环 TCP,本 SDK 用 go-winio 连命名管道;只有回环 TCP 能用时经回环 TCP 回调。变量缺失、不合法或没有能连的项时照常服务,启动时记一条warning,每次回调都是PLUGINS_UNAVAILABLE_001+plugins.host.unavailable(reason为no supported callback endpoint),不发请求。 - 发出之前依次核对,不合即不发请求:① 有没有可用的回调端点(上一条);② 所需权限(
Invoke为capability:kernel.pipeline,Publish为capability:messaging.queue)既要在清单permissions里、也要在Configure的granted_permissions里,否则PLUGINS_DENIED_002+plugins.callback.denied;③ 回调上下文的xihan.tenant必须是插件此刻正在处理的某个调用或投递的租户,否则plugins.callback.tenant_denied;④ 回调上下文的截止时间已过时按DeadlineExceeded(KERNEL_TIMEOUT_001),已被取消时按「Cancelled,取消信号已触发」(KERNEL_CANCELLED_001)。Publish这几项都是整批的结果;信封的xihantenant不在本地核对,由宿主逐项判定。 - 元数据取自回调所在的调用上下文(这个上下文按 RFC-0003 写出的 traceparent,与
ToMetadata同一取法:上游的标志只留采样位,不原样转发收到的那一个;上面写法的 deadline、已登记的 baggage、空的 trace_state),gRPC 截止时间与 deadline 相同,带会话令牌。 - gRPC 失败按规范的映射表(
rules.MapCallbackStatus,向量callback-status.json),只按表映射,不另按时钟或令牌改写(grpc-go 在本端按截止时间中止调用时报的就是DeadlineExceeded,不用再归一):Unauthenticated为plugins.callback.session_invalid,PermissionDenied为plugins.callback.denied,DeadlineExceeded为超时,调用上下文已取消的Cancelled为取消,没取消的Cancelled、Unavailable与连接失败为plugins.host.unavailable(reason为<状态名>: <说明>),Invoke的Unimplemented与InvalidArgument为kernel.operation.unknown与kernel.operation.invalid_payload,其余为plugins.process.failed(phase为操作 ID 或publish)。Publish的 RPC 失败时每一项都是同一个错误;结果数与信封数不同时每一项都是plugins.process.failed(reason为the host returned <n> results for <m> envelopes);空的信封列表不发请求。
运行时的消息键(invocation.md §8,向量 plugin-messages.json):错误的 details 就是模板的参数,id 一律是清单 ID。宿主有这些键的目录,运行时不随握手发送;SDK 自带同样的 10 种区域(plugin.RuntimeCatalog(),Catalog.Resolver() 已经合并它,en-US 模板登记为默认模板)供本地渲染。
| 键 | 参数 | 错误码 |
|---|---|---|
plugins.process.unavailable | id、state | PLUGINS_UNAVAILABLE_001 |
plugins.process.failed | id、phase、reason | PLUGINS_UNEXPECTED_001 |
plugins.event.unsubscribed | id、topic、type、mode | KERNEL_NOTFOUND_001 |
plugins.host.unavailable | id、reason | PLUGINS_UNAVAILABLE_001 |
plugins.callback.denied | id、permission | PLUGINS_DENIED_002 |
plugins.callback.tenant_denied | id、tenant | PLUGINS_DENIED_002 |
plugins.callback.session_invalid | 无 | PLUGINS_DENIED_002 |
语言映射
模板参数归到 RFC-0010「模板」的值模型(见消息模板)时,Go 的类型这样归:
| Go 的值 | 值模型 | 说明 |
|---|---|---|
nil、nil 指针、nil 切片与映射 | 空 | 顶层写空串,嵌套写 null |
bool 与底层是 bool 的类型 | 布尔 | true / false |
string 与底层是 string 的类型 | 字符串 | 原样 |
int、int8…int64,uint…uint64 在 int64 范围内 | 整数 | rune 是 int32,按整数写;要写一个字符用 string(r) |
超出 int64 的 uint64、*big.Int | 浮点 | D 与 X 不再适用 |
float64、float32、*big.Float、*big.Rat | 浮点 | float32 换成最接近的 float64:float32(0.1) 写 0.10000000149011612 |
json.Number、json.RawMessage | 按 JSON 读 | 整数写法且在 64 位范围内是整数,其余数字是浮点 |
切片、数组(含 []byte) | 数组 | |
| 映射 | 对象 | 键写成它的文本 |
实现 error / fmt.Stringer 的值 | 字符串 | 取 Error() / String():time.Time、time.Duration、带 String 的枚举(primitives.Stability)都是 Go 自己的文本 |
| 其余(结构体、复数等) | 字符串 | fmt.Sprint 的文本 |
Go 自己的文本(日期、Duration、结构体)不跨语言:插件的目录要在宿主上格式化时,先把这些值转成字符串再放进参数。
一致性
本 SDK 按 RFC-0024 认领的一致性档与现状:
- 认领的档:
core、plugin与provider:caching.distributed@1;档的定义见规范仓库的conformance/profiles.json。 - 缺口:无。
- 钉的规范版本:见 SDK 仓库的
spec/子模块与go.mod里的一致性模块github.com/xihanfun/framework-spec/conformance,两者是同一个规范提交。 - 成熟度:在有钉在规范标签上的发布版之前是 Experimental。
- 范围:流式操作在流式契约的 RFC 之前不提供(
InvokeStream读第一帧后以InvalidArgument或Unimplemented结束);Wasm 载体不在本 SDK 范围。
怎样验证:
- 向量:各包的测试经一致性模块读取内嵌的
conformance/vectors并回放。仓库根的vectors_test.go按go.mod钉住的一致性模块内嵌的档表核对认领的档:认领的档要求的每个向量要么有测试回放、要么列为缺口并写明理由;规范在认领的档里新增向量时这个测试失败,要么回放它,要么列为缺口并给出理由。 - 黑盒运行器:
examples/echo与examples/cache的测试构建插件,用go.mod里同一版本的xihan-conformance跑全部用例,用例序列必须等于运行器的全集,名单外的跳过算失败(examples/cache没有订阅,只有event用例按规则跳过)。CI 在 Linux 与 Windows 上都跑。 - 与 .NET 宿主:用 Go 写的插件在 .NET 宿主里服务操作(
framework/samples/EchoGoPlugin);用 Go 实现的分布式缓存经远程 Provider 适配器通过 .NET 的缓存一致性套件(framework/samples/CacheGoPlugin,测试XiHan.Framework.Caching.Remote.Tests)。
破坏性改动与迁移
本节列出与规范、.NET 参考实现对齐时改掉的旧行为,以及调用方怎么改。
Success()/Result[Unit]编码为{"ok":true},旧版是{"ok":true,"value":{}};读取Result[Unit]时带value(含{})即拒绝,不保留兼容路径。迁移:与旧版 Go 程序互通的一方同时升级;自己拼 JSON 的地方去掉"value":{}。有值的成功缺value、value为null而值类型不是Maybe时旧版读成零值,现在拒绝;可能没有的值改用Result[Maybe[T]]。写出时值编码成null(如nil指针、nil切片)而值类型不是Maybe也报错,空集合用非nil的空切片或空映射。- 内核错误的码、键与参数与 .NET 一致(en-US 默认模板逐字照 .NET 的语言文件,由
primitives.DefaultTemplate取得,Error.Message在进程默认解析器解析不出时用它,再退回Describe):- 载荷不合法的键由
kernel.operation.payload_invalid改为kernel.operation.invalid_payload,参数由{reason}改为{id, reason},reason只写出错位置的 JSON 路径($.quantity、$.lines[1].quantity、$['unit price'],载荷是null、不是对象或根上就不合时写$),不再带encoding/json的报错文本与 Go 类型名(RFC-0011 规则 2)。成员名含.、空格、'、/、"、[、]、(、)、\、制表、换行、回车、换页、退格、U+0085、U+2028、U+2029 时写['名字']、名字原样不转义,空名字写$.;落在整数、浮点或布尔上的null(encoding/json悄悄当成零值)也算类型不符(ADR-0235)。新增operation.InvalidPayload(id, reason)。宿主按键再翻译时旧键找不到文案。 - 类型化调用类型不符(
KERNEL_VALIDATION_002+kernel.operation.type_mismatch)只带{id}(ADR-0236),en-US 模板为Operation '{id}' was invoked with request or response types that do not match its registration.;上一版带的expected、actual是 Go 的类型名,各语言写不出同样的参数,已去掉。迁移:读expected/actual的代码改为只用id,要看类型时在调用方自己记日志。 - 中间件以成功短路、处理器没有产出响应时,JSON 调用与类型化调用都返回
KERNEL_UNEXPECTED_001(kernel.operation.no_response,参数{id}),旧版 JSON 调用返回 OK 加空载荷。迁移:以成功短路的中间件要么调用next,要么返回失败。 operation.Add的重复登记与登记表已满改为返回*primitives.Error(KERNEL_OPERATION_001+kernel.operation.duplicate,参数{id, owner};KERNEL_OPERATION_002+kernel.operation.registry_full,参数{capacity}),旧版是*primitives.FrameworkError。迁移:errors.As(err, &framework)改为errors.As(err, &primitivesError);ID 不合法仍是FrameworkError。- 未初始化的
Result的错误改为PRIMITIVES_VALIDATION_002+primitives.result.uninitialized,旧版是没有键的文案。 - 内核错误的
message由Describe的形式(kernel.operation.unknown (id=x))变为 en-US 文案(Operation 'x' is not registered.);按文本匹配的地方改为按错误码匹配。
- 载荷不合法的键由
manifest.Read按 Schema 严格读取:成员名区分大小写(encoding/json默认不区分,旧版"ID"也能读进id);任何位置的null都拒绝(旧版当作缺省);primitives与provides[].version只能是数字字符串,只有requires[].version可以带^(旧版三处都接受^);Schema 的必填成员不能缺(旧版缺stability读成stable、缺stage读成ingress);JSON 之后的多余内容拒绝;同一层的重复成员名拒绝(旧版取最后一个);activation写成空数组拒绝(旧版当作缺省,缺省才是onStartup);contributes.operations按操作 ID 文法(连字符只在字母数字之间)。迁移:照spec/manifest/manifest.schema.json写清单,"primitives": "^1"改"1"。- 管道的顺序约束按 RFC-0004 规则 7:
Before/After的两端可以写命名实例的实例名,也可以写只登记了一个实例的类型名;名字命中多个登记(同类型的多个实例按类型名引用、实例名与别的类型名相同)是KERNEL_PIPELINE_003。报错的时机照 RFC-0004 规则 8(ADR-0235):重复登记、未知阶段(KERNEL_PIPELINE_002)、约束主体(第一个参数)未登记或按名字有歧义在登记时立即报,是编程错误,UseAt/UseNamedInstance/Before/After当场 panicFrameworkError(与http.ServeMux登记冲突时一样);约束目标未登记、有歧义、跨阶段与成环在排序时报,由Describe/Dump/Build返回。旧版把这些都推迟到Describe才返回,先写约束、后登记主体也能通过。迁移:先登记中间件再声明它的约束(目标仍可以晚于约束登记);按动态数据登记中间件的代码在登记前自己排重,或用recover接住*primitives.FrameworkError。 - 已登记 Baggage 键的值按 conventions/baggage-keys.md 核对(ADR-0204、ADR-0233):非空、按 UTF-16 码元计不超过 256(基本多文种平面以外的字符算两个)、不含 U+0000–U+001F 与 U+007F–U+009F。外部输入的入口(选项
invocation.WithBaggage,插件运行时从元数据建上下文也走它)遇到不合的值丢弃这个成员、原有的同名值保留;程序内逐项派生Context.WithBaggage(key, value)给已登记的键一个不合的值是编程错误,与键不合文法一样 panicFrameworkError(PRIMITIVES_VALIDATION_001,ADR-0235),不静默丢弃也不保留原值。旧版两处都原样放进上下文。迁移:派生前用primitives.IsBaggageEntryAcceptable核对来自外部的值,或改用选项WithBaggage让不合的值被丢弃;xihan.idempotency-key例外,留给 Idempotency 阶段拒绝;未登记的键不在这里核对。新增primitives.IsBaggageValueAcceptable、IsBaggageEntryAcceptable与MaxBaggageValueLength。插件运行时从元数据建上下文时随之丢弃。 - 追踪标志按 RFC-0003 规则 7:没有上游时
Context.TraceFlags()为空(这次调用是链路的根),旧版一律当作已采样;写出traceparent时标志只写采样位(00或01),上游的00原样传下去,其余位不进上下文(ADR-0235;旧版把03这样的标志原样写出),没有上游时 SDK 没有采样器、写01;traceparent只认版本00与小写十六进制,ff等其他版本当作没给(旧版接受任意两位版本);WithTrace只给 ID 不给标志按已采样处理。是否采样只看标志的最低位(invocation.IsSampled),旧版只认01,03也算不采样。 operation.Invoker把中间件或处理器的 panic 翻译为KERNEL_UNEXPECTED_001(kernel.invocation.unhandled_exception,没有参数),与 .NET Observe 阶段翻译未处理的异常一致(RFC-0011 规则 5,规则 10 要求语言 SDK 实现);panic 的值与堆栈只写进slog.Default()的日志,值是FrameworkError时作为内部错误带上。旧版不恢复 panic,插件进程随之崩溃。要让进程退出的处理器改用os.Exit。- 超时与取消的归因只看截止令牌(RFC-0004、ADR-0092):
invocation.Context.Cancellation()在截止时间已到时报KERNEL_TIMEOUT_001,即使调用方先取消了;截止令牌没有触发时报KERNEL_CANCELLED_001。旧版按先触发的那个报,调用方先取消、随后到了截止时间时仍是取消。新增Context.DeadlineExceeded()。operation.Invoker的内置步骤DeadlineMiddleware承担 .NETDeadlineMiddleware的归因:进入 Resilience 阶段时截止时间已到即KERNEL_TIMEOUT_001(kernel.invocation.deadline_before_start);下游写下KERNEL_CANCELLED_001而截止令牌已触发时改写为KERNEL_TIMEOUT_001。按错误码决定重试的调用方要按超时处理这类调用。 operation.Current、RequestOf、ResponsePayloadOf只在调用期间、在经管道传下来的上下文上可见:每次调用的状态(描述、请求、终点、响应载荷)放在为这次调用派生的上下文里,不再写进对象袋,调用结束后调用方的上下文与对象袋保持原样。旧版把它们留在对象袋里,类型化调用的终点不清,同一上下文随后的 JSON 调用会执行上一次的类型化终点(缺陷)。调用结束后还在调用方上下文上读这三项的代码要改为在中间件里读。primitives.Unexpected的参数改为(code, messageKey, details, inner),与其他工厂和NewError一致(RFC-0001、ADR-0137);旧版是(code, messageKey, inner, details)。两个参数类型不同,旧调用编译即报错,交换后两个实参即可。- 模板的格式说明符改为可移植子集(RFC-0010),不再按 Go 的
fmt动词解释:D[n](整数,最少 n 位补零)、X[n]/x[n](非负整数的十六进制)、F[n](定点小数,缺省 2 位)、N[n](千分位,、小数点.,缺省 2 位);F 与 N 按值的精确十进制展开舍入,正好一半时取偶(四舍六入五成双,与 .NET 一致:0.125 写F2得0.12,2.5 写F0得2)。D、F、N 不区分大小写(d3等同D3,旧版把小写当成不支持),精度是字母后的 0–2 位数字(ADR-0236 起,见下文)。其他说明符(日期、自定义数字模式)是 .NET 格式串,SDK 按无格式输出。迁移:{count:%03d}改{count:D3},{n:%x}改{n:x},{n:%.2f}改{n:F2};插件目录在握手时交给 .NET 宿主按 .NET 规则格式化,旧的%写法到了宿主那里会被当作自定义数字格式,必须改。 - 模板支持
{{/}}转义;占位符名按^([A-Za-z][A-Za-z0-9_]*|[0-9]+)$,下划线开头的{_x}不再是占位符而是字面量;没有闭合的{及其后的文本原样保留。 primitives.Catalog.Resolve改为严格解析:找不到键或任一占位符缺值即返回假,Error.Message随之退回Describe;旧版缺值时仍返回半截译文。需要宽松格式化时直接用FormatMessage,需要严格格式化时用新增的TryFormatMessage。区域名比较不再区分大小写。- 消息参数的文本形式改由
primitives.FormatValue统一(模板与Describe共用,RFC-0010):nil与nil指针写空串,旧版写<nil>;浮点在 1e-4 ≤ |x| < 1e17 或 x = 0 时写最短往返的十进制、不用指数,2.0写2、1e16 写10000000000000000;范围之外写1E+17、9.9E-05、5E-324这样的指数形式,负零写-0,非数与无穷写NaN、Infinity、-Infinity(ADR-0235)。F 与 N 写出全部整数位,负数舍入成零时保留负号(-0.00)。依赖旧文本(如在日志里匹配<nil>)的地方要改。 Result与Error里同一层的重复成员名不合法(ADR-0235),旧版由encoding/json取最后一个。Error读取更严:details为null或数组、inner为null、messageKey不合文法(含空串)、message缺失、为空串或不是字符串时json.Unmarshal返回PRIMITIVES_VALIDATION_001,旧版会静默忽略。发送端按上面的编码写即可;messageKey为空时不写这个成员。- JSON 文本的共同读取检查(RFC-0001「JSON 文本」,ADR-0236):
Result与Error读取时开头的 BOM、嵌套超过 64 层、孤立的代理项转义("\ud800")与非法 UTF-8 都拒绝,旧版由encoding/json接受(孤立的代理项换成 U+FFFD)。操作载荷先过同一遍检查:语法错误(含 BOM、嵌套超过 64 层、孤立的代理项)的reason一律$;任何一层的重复成员是KERNEL_VALIDATION_001,reason是第一处重复的路径,先于其他问题(旧版encoding/json取最后一个);只有空白的载荷不再等价于{}(空载荷仍等价于{}),按语法错误处理。manifest.Read同样拒绝这些写法。迁移:发送合法的 UTF-8 JSON,不在文本前加 BOM,生成 JSON 的代码去掉重复成员。 - 线上的数字按值模型往返(ADR-0236):
Result[any]、Result[map[string]any]的值与Error.Details里的整数读成int64,旧版由encoding/json读成float64(超过 2^53 的整数因此失真);整数值的浮点写成2.0、-0.0(旧版写2、-0,对方读成整数);NaN与无穷写成字符串(旧版json.Marshal报错,整个Result写不出)。插件协议的Error.details照同一模型读写,读回的数组与对象是[]any与map[string]any,不是合法 JSON 对象的细节丢弃。Result、Maybe、ID的类型化值改用 SDK 的解码:成员名区分大小写(旧版"Count"也能读进count)、整数不接受1.0、整数与布尔不接受null、数字不从字符串读。迁移:按float64断言细节里整数的代码改为同时接受int64(或用primitives.FormatValue取文本);发送端照字段的 JSON 名字写成员。 - 操作载荷按 RFC-0011 规则 2 解码(ADR-0236),不再交给
encoding/json:成员名区分大小写(旧版"Quantity"也能读进quantity);int32等窄整数按自己的范围核对;浮点字段的1e400读成无穷(旧版报类型不符);null落在整数、浮点、布尔的切片项与映射值上也报类型不符;新增必填标签xihan:"required";几处问题同时存在时按文本顺序报第一处,缺少的必填成员在所在对象结束时报。迁移:调用方照字段的 JSON 名字写成员;需要接受null的数值改用指针;契约要求必填的成员加上xihan:"required"。 - 清单的读取与写出与 .NET 逐字一致(RFC-0002,ADR-0236):
manifest.Read、ReadFile的错误由*primitives.FrameworkError(PRIMITIVES_VALIDATION_001,英文说明)改为*primitives.Error,码KERNEL_CAPABILITY_006,键是kernel.manifest.invalid_json/empty/invalid/file_missing或primitives.manifest.*,参数只有路径(reason)、path或id;Validate也返回*primitives.Error。接口版本超过 2147483647 拒绝(旧版到 int 的上限,ParseRequirement、ParseDeclaration同样);中间件名为空、contributes.health不合文法开始拒绝。ReadFile跳过开头的 UTF-8 BOM,Read不跳过。Write改为规范的排版:列表总写([])、role与activation写出缺省值、requires[].optional与bindings[].required总写、字符串不再转义<、>、&与非 ASCII,Write不再校验(与 .NET 一样),Activation为空切片时写["onStartup"]。只有 Wasm 插件能贡献中间件的规则从manifest.Read移到plugin.Serve(.NET 宿主在发现插件时核对,ManifestReader不核对)。迁移:按错误码匹配的地方改为errors.As(err, &primitivesError)并看Code与MessageKey;按英文说明匹配的地方改为看路径;比较写出文本的测试更新期望值。 - 模板的值按值模型写出(RFC-0010「模板」,ADR-0236):数组与对象写成紧凑的 JSON(旧版是
fmt.Sprint的[1 a]、map[a:1]);超出 int64 的uint64是浮点(旧版写全部数字,D照样补零);float32按float64的值写(float32(0.1)由0.1变为0.10000000149011612);json.Number的小数写法是浮点,F按二进制值舍入(2.675写F2由2.68变为2.67),7.50写7.5。说明符只认^[DdFfNnXx][0-9]{0,2}$:精度最多两位(旧版到 999),D用在浮点上(含2.0)按无格式写(旧版对整数值的浮点补零)。迁移:要固定写法的值先在调用方转成字符串;需要三位以上精度时改在代码里格式化。新增FormatMessageIn、TryFormatMessageIn、FormatArgumentIn,Catalog.Resolve按命中模板的区域写小数点与分组符(旧版一律按不变文化),依赖旧文本的地方要改。 - 调用器的截止时间、解码与异常翻译改为管道里的内置步骤(RFC-0011 规则 10,ADR-0236,撤销 ADR-0235 的「在第一个中间件之前核对截止时间」):截止时间已到时 Ingress 与 Observe 阶段的中间件照常执行,到 Resilience 阶段才以
deadline_before_start结束(旧版一个中间件都不执行);载荷在 Validate 阶段才解码,排在它之前的中间件(认证、租户、授权)的失败先于载荷不合法报出(旧版在处理器之前解码,载荷不合法总是最后才发现,但认证失败的调用也会先解码);Ingress 阶段与 Observe 阶段Beginning上归属排在xihan.kernel.core之前的中间件 panic 原样交给调用方(旧版一律翻译)。管道里不能再登记名为ObserveMiddleware、DeadlineMiddleware、ValidationMiddleware的中间件。迁移:需要在截止时间核对之前做的事放在 Ingress 或 Observe 阶段;要被翻译 panic 的中间件放在 Observe 阶段End或之后;用到原始请求对象的中间件放在 Validate 阶段之后。 - 清单可选的字符串改为指针(ADR-0236 的补充):
Manifest.Package、Manifest.Entry与ConfigContribution.Schema由string改为*string,分得清「写了空串」与「没写」,写了空串时Write照写"package": "",与 .NET 一致(旧版一律省略空串)。迁移:赋值改为Package: manifest.Text("XiHan.Orders"),读取改为先判nil再解引用;比较两份清单时比较指向的值。 - 管道配置错误的消息改为 .NET 的英文原文(RFC-0004 规则 8,ADR-0236 的补充),各语言逐字相同:如
Middleware ordering constraints in stage 'validate' form a cycle: 'Guard[a]', 'Guard[b]'.(成环时按基准次序列出全部仍被卡住的中间件,按名字登记的实例写成类型名[名字];旧版只写阶段)、The ordering constraint of middleware 'Guard[a]' references unregistered middleware 'zz'.、Unknown pipeline stage 'bogus'.。约束目标改为逐阶段解析,前一阶段成环先于后一阶段的约束目标未登记报出(旧版先解析全部约束)。错误码不变。迁移:按消息文本匹配的地方改为按错误码匹配。 - 任意 JSON 原样保留读到的值(RFC-0011 规则 2,ADR-0236 的补充):载荷与
Result值里类型为any的成员,数字由int64/float64改为原文的json.Number(上一版按值模型读,2.0写回成2,1e400读成无穷、写不进响应)。Error.Details与插件协议的错误细节仍按值模型读成int64/float64。迁移:对any里的数字做类型断言的代码改为断言json.Number,再用Int64()/Float64()取值。 - 响应在管道结束之后编码(RFC-0011 规则 10「编码」,ADR-0236 的补充):中间件里不再有载荷,
operation.ResponsePayloadOf去掉,改为operation.ResponseOf(ctx)返回编码之前的响应对象(类型化调用也有);写不出的响应由KERNEL_UNEXPECTED_001+ 没有键的英文文案改为kernel.invocation.unhandled_exception,原因只进日志,框架错误放进inner,MarshalJSON的 panic 也接住。迁移:在 Egress 里读响应载荷的中间件改读ResponseOf的对象,需要文本时自己编码。 - 插件运行时照 ADR-0237 改为与规范一致(见插件运行时),公开 API 的变化:
- 去掉
Options.StopGrace:grace_seconds为 0 时按 5 秒、stdin 关闭与 SIGTERM 最多 3 秒都由规范写死。迁移:删掉这个字段。 - 去掉
StatusFromError与FromGrpcError:生命周期回调的失败按规则换成plugins.process.failed(reason是错误的类型名,旧版是带err.Error()文本的Literal),回调的 gRPC 失败按规范的映射表在Host里映射(旧版Unauthenticated与PermissionDenied都是plugins.callback.denied,Unavailable是plugins.process.unavailable{reason})。迁移:需要映射时用一致性模块的rules.MapCallbackStatus。 FromProtoError(err)改为FromProtoError(err, pluginID),FromStatus(status)改为FromStatus(status, pluginID, phase):错误码不合法时整个错误换成plugins.process.failed(旧版保留原码在details.code),带键的错误不再带text。迁移:传入清单 ID 与阶段(回调的操作 ID 或publish)。- 新增
RuntimeCatalog、RuntimeCatalogName与消息键常量MessageUnsubscribed、MessageHostUnavailable、MessageTenantDenied、MessageSessionInvalid;Catalog.Resolver()合并运行时的目录。
- 去掉
- 插件运行时的行为变化,调用方一般不用改代码:带消息键的错误写出时
text为空(旧版写渲染后的文本);XIHAN_PLUGIN_HOST_ADDRESS按列表解析,不合法时照常启动、回调以plugins.host.unavailable失败(旧版拒绝启动),HostOf在插件的调用里总有值;回调在发出前核对权限与租户;找不到订阅由kernel.operation.unknown{topic, type, mode}改为plugins.event.unsubscribed{id, topic, type, mode},匹配多个订阅时依次执行(旧版只交给第一个),处理器 panic 不再让进程崩溃;Invoke先报未声明再报未就绪;InvokeStream读第一帧后才结束;Started不再可服务,Start在应答之前求一次健康;Handshake在Failed里不再接受,次序不对的Stop以FailedPrecondition拒绝;Stop先等在途调用再调停止回调、再应答(旧版先调回调、应答之后才等);stdin 关闭时调停止回调(reason为shutdown);配置节不是对象时进入Failed;Configuration.Decode的成员名只按 ASCII 不区分大小写,字符串按 JSON 数字的文法转数字,布尔只认true、false(旧版去掉首尾空白,并接受1、t等);FromMetadata只留已登记的 Baggage 键、截止时间按严格文法读并与 gRPC 截止时间取较早的,ToMetadata写O格式;ParseEndpoint不去掉首尾空白,按规范的空白集合与回环地址写法核对;tcp 只监听127.0.0.1(旧版也接受::1);握手里没写方式的订阅写competing;npipe 只允许当前用户;WatchHealth 求健康回调的间隔由 1 秒改为 10 秒;清单开头的 BOM 去掉后再读与发送。 Error的自由文本不能为空,也不能只有空白(RFC-0001,ADR-0245),空白按 RFC-0001「空白字符」的 25 个码位判断(U+001C–U+001F 与零宽空格不是空白):Error.WithText遇到空串或只有空白的文案以PRIMITIVES_VALIDATION_001panic,旧版不检查参数;Literal与线上读取的message只有空白也拒绝,旧版只拒绝空串。迁移:调用前先判断文案是否只有空白,只有空白时改用错误码作文案,或者不调用WithText。
