工具与模式的版本管理
演进您的服务器，同时不破坏客户端。
工具与模式的版本管理 是 CoddyKit 上的免费 MCP Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 MCP Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 MCP Academy 课程共包含 4 节课。
客户端依赖您的数据形状
其他客户端连接后，就会依赖您的工具名称和参数形状。随意更改它们会同时破坏所有客户端。
添加式变更是安全的
添加带默认值的可选参数，可以让旧的调用方继续工作。它们只需忽略自己没有发送的新字段。
def search(q: str, limit: int = 10) -> list:
...破坏性变更会带来问题
重命名工具、移除参数，或将某个参数改为必需，都属于破坏性变更。现有客户端会突然发出不再符合要求的调用。
先添加，再弃用
要演进某个字段，请添加新字段并保留旧字段。在旧字段的描述中标记为已弃用，以便调用方知道需要迁移。
在工具名称中加入版本
如果确实需要进行破坏性变更，请在 v1 旁边发布一个v2工具。两者同时运行一段时间，让客户端按照自己的节奏迁移。
@mcp.tool(name="search_v2")
def search_v2(query: str) -> list:
...服务器报告自身版本
您的服务器会在握手期间公布名称和版本。请更新版本号，以便客户端知道自己连接的是哪个版本。
mcp = FastMCP("my-server")
# version surfaces in server info遵循语义化版本规范
请使用语义化版本：修复问题时更新补丁版本，添加功能时更新次版本，进行破坏性变更时更新主版本。版本号本身就能说明变化。
扩展输出，不要缩减输出
向结果中添加字段通常是安全的，而移除字段则属于破坏性变更。请将输出模式视为客户端会解析的一项承诺。
维护变更日志
在变更日志中记录每次工具和模式的变更。升级的用户需要知道哪些内容发生了变化、哪些是新增的，以及哪些已经移除。
为弃用内容设定终止日期
请公布旧工具将被移除的时间。明确的终止日期可以推动迁移，同时避免让任何人毫无准备地措手不及。
针对旧客户端进行测试
发布前，请像旧客户端那样调用您的服务并运行测试。这样可以发现类型检查器无法识别的意外破坏。
快速检查
对现有工具进行哪项变更，可以保证当前客户端仍能安全使用？
回顾：安全地演进
优先采用增量式变更，在移除之前先弃用；真正需要破坏性变更时发布 v2；遵循语义化版本规范，并维护变更日志。您可以放心发布！🚀
用 AI 导师学习 Python — 免费
在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。
- 课程
- 30
- 课程
- 120
常见问题解答
「工具与模式的版本管理」课时是免费的吗？
是的 — 「工具与模式的版本管理」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 MCP Academy 课程的其余内容，请升级到 CoddyKit PRO。 MCP Academy 课程共包含 4 节课。
「工具与模式的版本管理」这节课中我会学到什么？
演进您的服务器，同时不破坏客户端。 你通过在浏览器中直接运行的动手代码来练习 MCP Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 MCP Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 MCP Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「工具与模式的版本管理」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 MCP Academy 课中编写并运行代码吗？
能。每节 MCP Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。
此课程中的所有课时
- 分层服务器架构
- 通过环境配置设置与机密信息
- 幂等且感知副作用的工具
- 工具与模式的版本管理