MCP工具弃用 / 下线通知 / 迁移指引本篇是《MCP实战手记》篇12企业级Toolbox治理的延伸篇只拆「弃用迁移」一个点把篇12 §6 的弃用状态机拆开——宽限 14 天→stub 30 天→物理删除附 docUrl 迁移指引模板和调用方通知清单。仓库tagv12Gitee0. 半夜 500 的代价篇12 开篇第四类事故是「僵尸」某工具负责人离职半年没人维护却一直出现在发现列表。比僵尸更疼的是硬下线——removed当天 3 个调用方集体 500才发现没拉调用方清单、没给迁移指引。正确做法是「不删先标期」给调用方一段迁移窗口窗口内工具还在带告警窗口后才彻底移除并保留 stub 指引。1. 弃用状态机ACTIVE ──deprecate()── DEPRECATED宽限≥14天仍可用但告警 │ advanceLifecycle() 宽限期满 ▼ REMOVEDstub 30天调用返回迁移指引而非500 │ advanceLifecycle() stub期满≥30天 ▼ TOMBSTONE永久保留迁移路由调用返回 410docUrl**不丢迁移路径**字段status、deprecatedAt、docUrl迁移指引、removedAt、tombstoneAt。2. 实现voiddeprecate(ToolboxIdid){ToolboxDefinitiondefrequireActive(id);def.setStatus(DEPRECATED);def.setDeprecatedAt(now());def.setDocUrl(migrationDoc(id));// 例如 /docs/migrate/get_report-v2save(def);redis.publish(toolbox-events,deprecate:id);}// 仅主节点执行Redis 分布式锁 / leader 选举如 ShedLock避免多实例重复推进重复通知SchedulerLock(nameadvanceLifecycle,lockAtMost10m)voidadvanceLifecycle(){for(def infindAll(DEPRECATED))if(Days.between(def.deprecatedAt,now())14){promoteToRemoved(def);// statusREMOVED, removedAtnowredis.publish(toolbox-events,lifecycle:def.id);// 通知各实例失效本地缓存见 04}for(def infindAll(REMOVED))if(Days.between(def.removedAt,now())30){promoteToTombstone(def);// 保留 docUrl永久返回 410指引不丢迁移路径redis.publish(toolbox-events,lifecycle:def.id);}}resolve对已 REMOVED / TOMBSTONE 都返回指引而非 500tombstone 永久保留路径不丢迁移if(def.getStatus()REMOVED||def.getStatus()TOMBSTONE)thrownewIllegalStateException(已移除: id迁移见 def.getDocUrl());3. docUrl 迁移指引怎么写调用方照着就能迁模板# 迁移指引retail-cn/get_report - 状态已弃用REMOVED请迁移到 retail-cn/get_report2.0.0 - 变更返回值结构 get_report1.0.0 - 2.0.0字段 text - {text, blocks} - 影响当前调用方将返回 410 本指引 - 步骤1) 改调用版本号 2) 适配新返回值 3) 灰度验证见篇12·版本灰度实战 - 联系人张三 / 迁移 issue #1234. 调用方清单导出 通知deprecate 时导出现在谁在调这个工具监控 / 访问日志聚合发通知而非静默deprecate(query_store) - 导出调用方: [order-svc, report-svc, mobile-bff] - 通知: 企业群 对应 owner 邮件附迁移指引链接 - 宽限 14 天倒计时提醒第 7 / 12 / 14 天5. 实测输出链deprecate(query_store) - statusDEPRECATED, deprecatedAtT0 T07d 提醒: query_store 14天后移除 T014d advanceLifecycle() - statusREMOVED(stub), removedAtT014d resolve(admin, query_store) - IllegalStateException: 已移除迁移见 /docs/migrate/query_store T044d advanceLifecycle() - TOMBSTONE永久保留迁移路由返回 410指引不丢路径多实例篇12 §8A 把 query_store 推进 REMOVEDB 的发现列表里它已消失——两实例读同一份 Redis 状态。6. 踩坑踩坑2弃用未通知removed 当天 3 个调用方 500。根因 deprecate 没拉调用方清单。修法deprecate 即导出调用方 发通知 倒计时提醒§4。踩坑3同名冲突A/B 团队都注册 get_reportRegistry 覆盖。已由复合键owner_team_idname解决篇12 §2弃用时也按完整 id 操作互不误伤。7. 边界声明本机已验证deprecate→REMOVED→TOMBSTONE 状态机、resolve 返回迁移指引含 tombstone、多实例同步。待生产验证①真实调用方清单聚合依赖访问日志 / APM②advanceLifecycle多实例调度须加 leader 选举ShedLock/分布式锁否则每实例各跑一遍会重复通知 owner③Redis 持久化弃用/灰度状态是关键控制面Redis 需开 AOF/RDB 或治理状态以 DB 为源避免重启丢失宽限窗口。本文只拆弃用迁移一点治理层总览与复合键见篇12 深度文。同专题推荐篇12 深度文企业级Toolbox治理篇12·版本灰度实战caller 路由到指定版本篇12·权限评分实战scope 拦截与健康度指标篇12·多实例一致性深潜Redis 与本地缓存降级代码仓库tagv12Gitee