从 #5563 里拆出的残留半边(该单的维护者裁定明确允许「对齐或如实报告」,实施后判定对齐不合理,故立此单)。基线 origin/main @ 55c74deeb。
事实
packages/spec/src/api/plugin-rest-api.zod.ts 为 GET /meta/:type/:name 声明了唯一响应 schema:
responseSchema: 'GetMetaItemResponseSchema'
#5563 把这条路由的普通读取(缓存 / 非缓存 / 各兜底)全部收敛到了这个信封。但同一条路由带上 ?layers=true 时走的是 getMetaItemLayered,应答的是三层诊断投影:
{ type, name, code, overlay, overlayScope, effective, validation }
code(artifact 基线)/ overlay(per-org 定制行)/ effective(两者合并后、即普通读取会给的那个值)是并列的三层,驱动 Studio 元数据编辑页的「代码默认 vs 覆盖 vs 生效」对比页签。
为什么 #5563 没有把它一起收敛
把三层塞进 GetMetaItemResponseSchema 的单个 item 里,等于把这个诊断本身删掉 —— 它存在的全部意义就是三层分开可见。所以 #5563 的实施停在普通读取,并在 handler 里就地写明了理由(rest-server.ts 的 wantLayered 分支上方)。
剩下的不是运行时分裂,而是声明缺口:同一条路由按 query flag 分岔到两种资源表示,spec 只声明了其中一种。
影响
可能的处置(未定,spec 座位)
- A:新增
GetMetaItemLayeredResponseSchema,并让路由声明能表达「按 query 分岔的两种表示」(需要确认 plugin-rest-api.zod.ts 的路由条目是否支持多响应 schema —— 若不支持,这一步本身就是一个契约表达能力的决定); - B:把 layered 视图拆成自己的路径(例如
GET /meta/:type/:name/layers),一条路径一个响应形状,不需要扩展路由声明的表达能力; - B 更贴合「一条路由一个形状」,代价是既有
?layers= 调用方(Studio 编辑器)要跟着迁移。二者都动公开契约,不代拍。
关联:#5563(母单,已收敛普通读取)、#5545。
从 #5563 里拆出的残留半边(该单的维护者裁定明确允许「对齐或如实报告」,实施后判定对齐不合理,故立此单)。基线
origin/main@55c74deeb。事实
packages/spec/src/api/plugin-rest-api.zod.ts为GET /meta/:type/:name声明了唯一响应 schema:#5563 把这条路由的普通读取(缓存 / 非缓存 / 各兜底)全部收敛到了这个信封。但同一条路由带上
?layers=true时走的是getMetaItemLayered,应答的是三层诊断投影:code(artifact 基线)/overlay(per-org 定制行)/effective(两者合并后、即普通读取会给的那个值)是并列的三层,驱动 Studio 元数据编辑页的「代码默认 vs 覆盖 vs 生效」对比页签。为什么 #5563 没有把它一起收敛
把三层塞进
GetMetaItemResponseSchema的单个item里,等于把这个诊断本身删掉 —— 它存在的全部意义就是三层分开可见。所以 #5563 的实施停在普通读取,并在 handler 里就地写明了理由(rest-server.ts的wantLayered分支上方)。剩下的不是运行时分裂,而是声明缺口:同一条路由按 query flag 分岔到两种资源表示,spec 只声明了其中一种。
影响
?layers=true会写出错的解析 —— 声明说是{ type, name, item },实际拿到的是六键的层投影;GET /meta/:type/:nameanswers two different body shapes on the same request — the cached branch (the DEFAULT) returns the bare document, the non-cached branch returns the spec-declared{ type, name, item }envelope #5563 收敛的立论同族:声明必须能被强制,机器可读表面不能撒谎(ADR-0076 D12 精神);可能的处置(未定,spec 座位)
GetMetaItemLayeredResponseSchema,并让路由声明能表达「按 query 分岔的两种表示」(需要确认plugin-rest-api.zod.ts的路由条目是否支持多响应 schema —— 若不支持,这一步本身就是一个契约表达能力的决定);GET /meta/:type/:name/layers),一条路径一个响应形状,不需要扩展路由声明的表达能力;?layers=调用方(Studio 编辑器)要跟着迁移。二者都动公开契约,不代拍。关联:#5563(母单,已收敛普通读取)、#5545。