Skip to content

[裁决] MetadataProtocol 是否应声明 publishMetaItem 成员 —— 半声明的门(响应已声明、请求未声明) #11006

Description

@os-elon

#10350 分出,由 PM engine 席上报。这是 packages/spec 契约变更,需要维护者裁决——#10350 的卡片正文自己把 spec 挡在外面并要求「若修复需要它就停下上报」,这就是那次上报。

⛔ 在裁定前不会有任何工作建立在它之上。

已测量的事实(不是推断)

#10350 要求「类型带上 packageId 之后移除 REST 调用点的 (p as any) cast」。这一半做不到,原因是结构性的,dev 前后各测一次、错误逐字节相同:

删掉 cast 得到的是 TS2339 — Property 'publishMetaItem' does not exist on type 'RestProtocol',而不是TS2353(对象字面量属性不匹配)。也就是说 cast 承的是「成员存在性」的重,不是「请求形状」的重——给 metadata-protocol 自己的请求类型加字段,不可能给一个 spec 声明的接口加成员。

按内容核实(packages/spec/src/api/protocol.zod.ts):

2444: saveMetaItem(request: SaveMetaItemRequest): Promise<SaveMetaItemResponse>;
2451: deleteMetaItem?(request: DeleteMetaItemRequest): Promise<DeleteMetaItemResponse>;
2463: getMetaItemLayered?(request: GetMetaItemLayeredRequest): Promise<GetMetaItemLayeredResponse>;

publishMetaItem不在其中;调用点的 p 来自 resolveProtocol(...),类型是 RestProtocol

今天的状态是一扇「半声明的门」:响应侧已经声明了(PublishMetaItemResponseSchema#7294),请求侧和成员没有。而这个不对称正是 #7294 当初要消除的东西。

三个选项(dev 推荐 B,但明确说这是维护者的决定)

A. 保持现状 —— publishMetaItem 继续作为 ADR-0076 D9 的服务端专有扩展、靠 cast 到达。零 spec 面;代价是调用点的请求字面量永远没有东西检查,也就是 #10350 归档时针对的那个缺口永久敞开。

B. 在 MetadataProtocol 上声明一个可选成员(接 PublishMetaItemRequest,返回 Promise<PublishMetaItemResponse>),可选性与 getMetaItemLayered / deleteMetaItem 一致。cast 退化成既有的 optional-call 惯用法,#9741TransportScopedMetaRequest 包装器套上去之后,未声明的键在调用点变成编译错误

C. 只在 spec 声明 PublishMetaItemRequest、不加接口成员,在 REST 门口用它给字面量定型。拿到强制力而不把扩展提升为已声明成员;代价是 spec 里多一个没有成员消费的请求类型。

dev 给 B 的理由(转述,供裁决参考)

相关

Metadata

Metadata

Assignees

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions