在 #4910 开工核查中发现,记录备查,未认领 。基线 origin/main @ 2e284b2546。
事实
packages/core/src/api-registry.ts 的 ApiRegistry(路由冲突检测、优先级解析、RBAC 集成、发现查询,约 500 行)由 createApiRegistryPlugin() 注册为 api-registry 服务。
装配点全部在示例文件里 :
$ grep -rn "createApiRegistryPlugin" --include=*.ts packages/ examples/ | grep -v node_modules | grep -v .test.
packages/core/src/api-registry-plugin.ts:35,59 ← 定义处 + 文档注释
packages/core/examples/api-registry-example.ts:21,167,287,374,446
(无任何 packages/runtime、packages/cli、examples/app-* 的装配)
'api-registry' 服务的消费者同样只有 packages/core/examples/api-registry-example.ts。真实 boot 佐证:showcase 起 47 个 plugin(pnpm dev -- --fresh),plugin 列表里没有 api-registry。
因此 packages/spec/src/api/registry.zod.ts 的 ApiEndpointRegistrationSchema 整面零执行 ,不只是 #4686 盯的 rateLimit(registry.zod.ts:379),还包括 requiredPermissions(注释里承诺「the gateway layer automatically validates these permissions before allowing the request to proceed」—— 没有任何 gateway 层读它,这是安全语义)、parameters、requestBody、responses、security、operationId、tags。
与 #4936 的关系(两份端点声明,都不执行)
仓里有两套 端点声明形状:api/endpoint.zod.ts 的 ApiEndpointSchema(从 defineStack({ apis }) 可达,#4936 证明其执行链断在挂载与 matchEndpoint 两处)与本单的 ApiEndpointRegistrationSchema(从 ApiRegistryEntrySchema 可达,执行器压根没被装配)。两套都零执行 —— 这本身就是 ADR-0076「一条路由一个属主」要防的形状,只不过这里两个属主都没上岗。
建议(协议级,留给维护者裁决)
按 ADR-0049 摘除 ApiEndpointRegistrationSchema / ApiRegistryEntrySchema 与 ApiRegistry 本身,示例一并删除。装配 + 接执行 :让真实 composition 挂载 api-registry,并把 requiredPermissions 等键接到实际的 gateway 校验;先解决与 ApiEndpointSchema 的二选一(声明式 apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint 全仓无实现 #4936 与 声明式 apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint 全仓无实现 #4936 :两套端点声明的存废本就该一起决定,分开裁很容易留下第三份形状。
⚠️ requiredPermissions 的注释以现在时 承诺自动鉴权(registry.zod.ts 约 383 行起),对着这段注释写元数据的作者会以为端点受保护 —— 无论走哪条路线,这段注释都必须先改成事实。
关联:#4686 、#4910 、#4936 、#4938 、ADR-0049、ADR-0076、Prime Directive #10 。
在 #4910 开工核查中发现,记录备查,未认领。基线
origin/main@2e284b2546。事实
packages/core/src/api-registry.ts的ApiRegistry(路由冲突检测、优先级解析、RBAC 集成、发现查询,约 500 行)由createApiRegistryPlugin()注册为api-registry服务。装配点全部在示例文件里:
'api-registry'服务的消费者同样只有packages/core/examples/api-registry-example.ts。真实 boot 佐证:showcase 起 47 个 plugin(pnpm dev -- --fresh),plugin 列表里没有 api-registry。因此
packages/spec/src/api/registry.zod.ts的ApiEndpointRegistrationSchema整面零执行,不只是 #4686 盯的rateLimit(registry.zod.ts:379),还包括requiredPermissions(注释里承诺「the gateway layer automatically validates these permissions before allowing the request to proceed」—— 没有任何 gateway 层读它,这是安全语义)、parameters、requestBody、responses、security、operationId、tags。与 #4936 的关系(两份端点声明,都不执行)
仓里有两套端点声明形状:
api/endpoint.zod.ts的ApiEndpointSchema(从defineStack({ apis })可达,#4936 证明其执行链断在挂载与matchEndpoint两处)与本单的ApiEndpointRegistrationSchema(从ApiRegistryEntrySchema可达,执行器压根没被装配)。两套都零执行 —— 这本身就是 ADR-0076「一条路由一个属主」要防的形状,只不过这里两个属主都没上岗。建议(协议级,留给维护者裁决)
ApiEndpointRegistrationSchema/ApiRegistryEntrySchema与ApiRegistry本身,示例一并删除。requiredPermissions等键接到实际的 gateway 校验;先解决与ApiEndpointSchema的二选一(声明式apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint全仓无实现 #4936),否则是把第二套方言也养大。apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint全仓无实现 #4936 合并裁决:两套端点声明的存废本就该一起决定,分开裁很容易留下第三份形状。requiredPermissions的注释以现在时承诺自动鉴权(registry.zod.ts约 383 行起),对着这段注释写元数据的作者会以为端点受保护 —— 无论走哪条路线,这段注释都必须先改成事实。关联:#4686、#4910、#4936、#4938、ADR-0049、ADR-0076、Prime Directive #10。