弃用策略

弃用策略

本文档定义了 Plumego 在稳定版本中管理公开 API、扩展包和配置接口弃用的方式。

适用范围

本策略适用于：

• 稳定库根 (core, router, contract, middleware, security, store, health, log, metrics) — 从 v1 开始的正式兼容性承诺。
• 规范参考 (reference/standard-service) — 与稳定根 API 保持同步，不作为可复用的扩展目录。
• CLI (cmd/plumego) — 受支持的命令行工具；不是 Go 导入接口。

本策略不适用于：

• x/* 扩展包——具体规则见下方各层级说明。
• 内部包（internal/，未导出符号）——实现细节，可能在不通知的情况下变更。
• _test.go 文件中的测试辅助函数。
• 没有外部兼容性承诺的预发布迁移包装器和兼容垫片。

Agent 清理规则：一旦仓库中最后一个调用方已迁离预发布或内部兼容包装器，应在同一次变更中移除该包装器。不要仅因为它在迁移期间有用就保留死包装器。

扩展包层级

x/* 扩展包遵循 扩展稳定性策略 中定义的成熟度阶梯。兼容性规则因层级而异：

层级	模块	兼容性规则
beta	x/gateway, x/observability, x/rest, x/websocket	导出 API 在次要版本发布引用之间冻结。破坏性变更需要新的标记引用和快照对比。不允许静默破坏。
experimental	其他所有 x/*	无兼容性冻结。API 和配置可能在任意提交之间变更。有明确理由时采用，不要默认采用。
ga	暂无	完整的稳定根级兼容性承诺。

从 experimental 升级到 beta 需要在 specs/extension-beta-evidence.yaml 中记录证据。

兼容性承诺（v1 稳定根）

对于稳定根中每个导出符号（类型、函数、接口、常量、变量）：

• 其签名在主版本内不会以不兼容的方式变更。
• 包不会在主版本内重命名或移除。
• godoc 中记录的行为不会静默退化。

新的主版本（如 v2）是破坏性变更的受支持机制。

弃用流程

第 1 步 — 在代码中标记

在符号上方紧接着添加 // Deprecated: godoc 注释，包含：

• 替代内容（包路径、函数名或方法）。
• 引入弃用通知的版本。
• 计划移除的版本（主版本号，或尚未确定时填 “TBD”）。

// Deprecated: Use middleware/httpmetrics.Middleware instead.
// Deprecated since: v1.0.0. Planned removal: v2.
func OldMiddlewareHelper(...) { ... }

第 2 步 — 在发布说明中记录

每次弃用必须出现在引入弃用通知的版本的发布说明中。

第 3 步 — 维护一个主版本周期

弃用符号在弃用通知发布后至少保持一个完整主版本的功能正常。

• v1.x 中弃用 → v2.0 时可以移除。
• v2.x 中弃用 → v3.0 时可以移除。

第 4 步 — 在下一个主版本中移除

移除只在主版本边界发生，并且必须列入该主版本的迁移指南。

扩展包（x/*）——无兼容性冻结

扩展包处于实验性状态，可能：

• 在次要版本之间更改 API 签名。
• 在不升级主版本的情况下重命名、拆分、合并或移除。
• 晋升为稳定根状态（从该时刻起适用完整弃用流程）。

依赖 x/* 包的用户应将依赖固定到特定发布版本，并在每次升级时查阅发布说明。

不构成破坏性变更的情况

以下变更不视为破坏性变更，不需要弃用通知：

• 添加新的导出符号（函数、类型、常量、变量）。
• 向使用构造函数的结构体添加新的可选字段。
• 向具体类型添加新方法。
• 修复旧行为与文档合约不符的 bug。
• 更改未导出（内部）代码的行为。
• 改进错误消息，且不更改错误码或 HTTP 状态码。

治理

• 高风险包（core, router, contract, security）的弃用决策需要由 module.yaml 中列出的运行时或安全所有者审查。
• 中等风险包的弃用决策可由模块所有者做出。
• 所有弃用必须在发布前通过标准发布门控：make gates。

当前弃用列表

v1.0 时暂无弃用。

下一步阅读

• 扩展稳定性策略 — x/* 模块晋升标准
• 发布策略 — 支持矩阵和兼容性读法
• 稳定根 — v1 承诺覆盖的包列表