面试题：微服务架构下API版本管理策略及在服务文档中的体现

Question

随着微服务的演进，API版本管理成为关键。请描述几种常见的API版本管理策略，以及如何在服务文档中清晰地表述不同版本API的功能差异、兼容性等内容，以便于使用者准确理解和调用。

Answer 1

常见API版本管理策略

1. URL版本化：在URL中体现版本号，如/v1/users 、/v2/users。这种方式直观，易于理解和实现，客户端通过改变URL来访问不同版本API 。但缺点是如果版本过多，URL会变得冗长。
2. Header版本化：在HTTP请求头中设置版本信息，如Accept: application/json; version=v1 或X-API-Version: v2。优点是不会污染URL，且可以灵活切换版本而无需更改URL结构。不过，这种方式对客户端要求较高，需要正确设置请求头。
3. 媒体类型（MIME Type）版本化：通过定义不同的媒体类型来区分版本，如application/vnd.company.v1+json 、application/vnd.company.v2+json。该方式能明确表达数据格式和版本，适用于RESTful API 。但缺点是需要客户端和服务器端都正确解析和处理自定义的媒体类型。

在服务文档中表述不同版本API内容

1. 功能差异：
   • 以表格形式对比不同版本API的功能。例如： | API版本 | 新增功能 | 修改功能 | 废弃功能 | | ---- | ---- | ---- | ---- | | v1 | - | - | - | | v2 | 用户批量查询接口 | 用户详情接口返回字段增加用户等级 | 删除单个用户接口 |
   • 对每个功能差异进行详细描述，包括输入参数、输出结果的变化等。如“v2版本的用户详情接口在v1基础上，返回字段增加了user_level，表示用户在系统中的等级，取值范围为1 - 5”。
2. 兼容性：
   • 说明不同版本API之间的兼容性关系，如“v2版本API与v1版本部分接口不兼容，例如v1中的删除单个用户接口在v2中已废弃，不建议继续使用”。
   • 对于存在兼容性问题的接口，提供从旧版本迁移到新版本的指南，如“若您之前使用v1版本的删除单个用户接口，在v2版本中，请使用批量删除接口，并将需要删除的用户ID以数组形式传入”。