扩展边界

扩展边界

本页定义了 Plumego x/* 扩展家族的结构与治理，解释 x/* 是什么、包如何在其中组织，以及晋升路径是什么。

晋升标准详见 扩展稳定性策略。 各家族当前成熟度状态见 扩展成熟度。

x/* 不是什么

x/* 不是插件市场。插件市场的特征是：

• 包由社区贡献，质量标准参差不齐。
• 没有共同所有权或审查预期。
• 成熟度通过下载量或年龄推断，而非通过明确标准。

Plumego 的 x/* 不是这样工作的。每个扩展家族都有所有者、定义的职责边界、机器可读的清单和明确的成熟度级别。x/* 中的包是具有显式成熟度级别和验证路径的能力家族。

评估 x/* 包时，第一个问题不是”它是否存在？“，而是”它的成熟度状态是什么，支撑该状态的证据是什么？“

x/* 是什么

x/* 是产品能力、协议适配和业务领域特性所在的层——与稳定内核分离，以防止这些关注点拉伸内核的兼容性承诺。

这种分离有两个目的：

1. 稳定性隔离。 稳定根承载长期兼容性承诺。扩展家族被允许更快演进，这对产品能力和面向生态系统的集成是合适的。

2. 范围清晰。 新工程师或 AI Agent 查看变更时，可以立即知道它是否触及了长期稳定内核，还是明确边界的能力区域。

四类扩展家族

A — 面向应用的能力家族

常见服务模式的直接应用入口，是主要的扩展发现接口。

家族	主要角色
x/rest	资源路由约定、CRUD 模式、分页
x/websocket	WebSocket 集线器、连接生命周期、房间广播
x/gateway	反向代理、重写规则、后端池、边缘传输
x/tenant	租户解析、策略、配额、限流、会话、租户感知存储
x/observability	导出器、追踪器、收集器和适配器接入
x/fileapi	HTTP 文件上传/下载传输
x/ai	AI 提供商契约、会话、流式传输、工具调用
x/messaging	面向应用的消息流
x/frontend	静态和嵌入式资源服务、SPA 回退
x/resilience	扩展层使用的熔断器和限流原语
x/observability/ops	受保护的管理路由、运行时诊断

深入下级原语之前，先从面向应用的家族开始。

B — 支撑原语

由 A 类家族或需要直接访问特定原语的应用代码使用的底层构建块。

包	父家族	角色
x/data/cache	x/data	缓存拓扑和 Redis 支持的实现
x/gateway/discovery	x/gateway	服务发现后端契约和适配器
x/messaging/mq	x/messaging	消息队列原语
x/messaging/pubsub	x/messaging	发布/订阅代理原语
x/messaging/scheduler	x/messaging	进程内定时任务、延迟任务、可重试任务
x/messaging/webhook	x/messaging	出站 webhook 分发
x/gateway/ipc	x/gateway	进程间通信传输原语
x/data	—	持久化接口：文件、幂等性、高级拓扑

从所属家族入口开始发现，不要直接从下级原语开始。

C — 本地开发和受保护操作

必须在没有显式认证门控的情况下绝不暴露在生产环境的包。

包	角色
x/observability/devtools	调试端点、请求检查器、仅限本地的诊断
x/observability/ops	受保护的管理和运行时诊断路由

两者都需要调用方在认证路径下显式挂载，都不会自注册或默认使用公开路由。

D — 快速演进的领域包

领域本身快速演进、兼容性预期相对较轻的家族。

包	说明
x/ai	稳定层级子包（provider、session、streaming、tool）与实验性根家族分开评估
x/frontend	SPA 和资源服务模式随 Web 工具链变化
x/data 高级拓扑	子接口清单选择特定稳定目标

成熟度阶梯

所有 x/* 包从 experimental 开始。晋升是显式的，需要满足 扩展稳定性策略 中的标准。

状态	含义	采用指导
experimental	API 形态可能变更；没有兼容性预期	用于评估、原型开发，或在你自己承担升级风险时使用
beta	API 在当前主版本内稳定；破坏性变更需要弃用通知	在明确范围的场景中可用于生产
ga	完整的 v1 兼容性承诺	默认的生产选择

所有家族的当前状态见 扩展成熟度。

采用顺序

评估 x/* 扩展家族时：

1. 在 扩展成熟度 中查看当前状态和推荐入口。
2. 阅读 docs/modules/ 下该家族的入门文档。
3. 阅读 module.yaml 了解职责和非目标。
4. 从对应的 reference/with-* 应用开始获取接入指导。
5. 在确定生产采用之前，检查 specs/extension-beta-evidence.yaml 了解已知阻塞项。

不要仅凭包的存在推断生产就绪性。

x/* 的非目标

扩展家族不被允许：

• 以迫使稳定根变更来适配它们的方式导入稳定根。
• 在没有调用方显式挂载的情况下自注册路由、中间件或生命周期钩子。
• 定义替代的规范应用布局。
• 通过修改自己的 module.yaml 状态来自我晋升。

边界违规会被自动检测：

go run ./internal/checks/dependency-rules
go run ./internal/checks/extension-maturity
go run ./internal/checks/extension-beta-evidence

下一步阅读

• 核心边界 — 什么属于稳定内核
• 扩展稳定性策略 — 晋升标准
• 扩展成熟度 — 当前状态看板
• x/* 家族 — 可选能力概览