【架构实战】API版本管理：让接口平滑演进

一、一次接口变更让30个客户端崩溃2018年后端团队修改了一个返回字段的名字把userName改成了username。他们觉得这只是个小改动没有通知客户端团队直接上线了。结果30个客户端全部崩溃——iOS、Android、H5、小程序全部报错。那天下午全公司都在紧急修复光回归测试就跑了一整天。从那以后我们对API版本管理有了血的教训接口一旦发布就是契约不能随便改。二、API版本管理策略2.1 版本管理方式┌─────────────────────────────────────────────────────────────────┐ │ API版本管理方式 │ │ │ │ 1. URL路径版本 │ │ /api/v1/users │ │ /api/v2/users │ │ 优点直观、简单 │ │ 缺点路由膨胀 │ │ │ │ 2. 请求头版本 │ │ GET /api/users │ │ Header: X-API-Version: 2 │ │ 优点URL不变 │ │ 缺点不够直观 │ │ │ │ 3. Content-Type版本 │ │ Content-Type: application/vnd.company.v2json │ │ 优点RESTful │ │ 缺点复杂 │ │ │ │ 4. 查询参数版本 │ │ /api/users?version2 │ │ 优点简单 │ │ 缺点不够规范 │ │ │ └──────────────────────────────────────────────────────────────────┘2.2 版本演进规则版本号规则MAJOR.MINOR.PATCH MAJOR不兼容的变更 - 删除字段 - 修改字段类型 - 修改接口语义 MINOR向后兼容的变更 - 新增字段 - 新增接口 - 新增枚举值 PATCHBug修复 - 不影响接口行为三、Spring Boot实现3.1 URL路径版本/** * API版本控制配置 */ConfigurationpublicclassApiVersionConfig{/** * 自定义版本注解 */Target({ElementType.TYPE,ElementType.METHOD})Retention(RetentionPolicy.RUNTIME)publicinterfaceApiVersion{intvalue()default1;}/** * 版本路由条件 */publicclassApiVersionConditionimplementsRequestConditionApiVersionCondition{privateintapiVersion;publicApiVersionCondition(intapiVersion){this.apiVersionapiVersion;}OverridepublicApiVersionConditioncombine(ApiVersionConditionother){returnnewApiVersionCondition(other.apiVersion);}OverridepublicApiVersionConditiongetMatchingCondition(HttpServletRequestrequest){Stringpathrequest.getRequestURI();MatchermatcherPattern.compile(/v(\\d)/).matcher(path);if(matcher.find()){intversionInteger.parseInt(matcher.group(1));if(versionapiVersion){returnthis;}}returnnull;}OverridepublicintcompareTo(ApiVersionConditionother,HttpServletRequestrequest){returnother.apiVersion-apiVersion;}}}/** * V1版本接口 */RestControllerRequestMapping(/api/v1/users)publicclassUserV1Controller{GetMapping(/{id})publicUserV1VOgetUser(PathVariableLongid){UseruseruserService.getById(id);returnUserV1VO.builder().id(user.getId()).userName(user.getName())// V1字段名.email(user.getEmail()).build();}}/** * V2版本接口新增字段、修改字段名 */RestControllerRequestMapping(/api/v2/users)publicclassUserV2Controller{GetMapping(/{id})publicUserV2VOgetUser(PathVariableLongid){UseruseruserService.getById(id);returnUserV2VO.builder().id(user.getId()).username(user.getName())// V2字段名修改.email(user.getEmail()).phone(user.getPhone())// V2新增字段.avatar(user.getAvatar())// V2新增字段.build();}}3.2 版本兼容策略/** * 版本兼容适配器 */ServiceSlf4jpublicclassUserApiAdapter{/** * 根据版本号返回对应VO */publicObjectadapt(Useruser,intapiVersion){switch(apiVersion){case1:returnUserV1VO.builder().id(user.getId()).userName(user.getName()).email(user.getEmail()).build();case2:returnUserV2VO.builder().id(user.getId()).username(user.getName()).email(user.getEmail()).phone(user.getPhone()).avatar(user.getAvatar()).build();default:returnUserV2VO.from(user);}}}/** * 统一用户接口自动适配版本 */RestControllerRequestMapping(/api/users)publicclassUserController{AutowiredprivateUserApiAdapteradapter;GetMapping(/{id})publicObjectgetUser(PathVariableLongid,RequestHeader(valueX-API-Version,defaultValue2)intapiVersion){UseruseruserService.getById(id);returnadapter.adapt(user,apiVersion);}}四、版本迁移策略4.1 迁移流程┌─────────────────────────────────────────────────────────────────┐ │ 版本迁移流程 │ │ │ │ 1. 新版本上线与旧版本并存 │ │ - 新版本标记为Beta │ │ - 旧版本继续服务 │ │ │ │ 2. 通知客户端迁移 │ │ - 发布迁移文档 │ │ - 设置迁移截止日期 │ │ │ │ 3. 监控旧版本使用量 │ │ - 记录每个版本的调用量 │ │ - 通知未迁移的客户端 │ │ │ │ 4. 旧版本下线 │ │ - 确认所有客户端已迁移 │ │ - 旧版本返回410 Gone │ │ │ └──────────────────────────────────────────────────────────────────┘4.2 版本监控/** * API版本监控 */AspectComponentSlf4jpublicclassApiVersionMonitor{AutowiredprivateMeterRegistrymeterRegistry;Around(annotation(org.springframework.web.bind.annotation.RequestMapping) || annotation(org.springframework.web.bind.annotation.GetMapping) || annotation(org.springframework.web.bind.annotation.PostMapping))publicObjectmonitor(ProceedingJoinPointjoinPoint)throwsThrowable{HttpServletRequestrequest((ServletRequestAttributes)RequestContextHolder.currentRequestAttributes()).getRequest();StringapiVersionrequest.getHeader(X-API-Version);if(apiVersionnull){apiVersion1;// 默认版本}Stringurirequest.getRequestURI();// 记录版本使用量meterRegistry.counter(api.version.calls,uri,uri,version,apiVersion).increment();returnjoinPoint.proceed();}}五、踩坑实录坑1没有版本控制接口直接改了所有客户端报错。解决所有接口必须有版本号变更走新版本。坑2版本太多维护不过来同时维护5个版本代码重复严重。解决限定同时支持的版本数量最多2-3个加速旧版本下线。坑3迁移期太长旧版本一直在用新版本没人迁移维护成本越来越高。解决设置明确的下线时间过期返回410。坑4内部接口没有版本管理内部微服务间调用没有版本控制一方改了接口另一方就挂。解决内部接口也要版本管理使用Feign的fallback。坑5文档和代码不同步API文档还是旧版本的代码已经改了。解决使用Swagger/SpringDoc自动生成文档。六、总结API版本管理要点原则说明契约精神接口一旦发布不可随意修改向后兼容新版本要兼容旧版本版本共存新旧版本并存平滑迁移及时下线旧版本定期清理文档同步代码和文档保持一致最佳实践URL路径版本最实用同时支持的版本不超过3个监控每个版本的使用量设置明确的下线时间内部接口也要版本管理血的教训API是团队之间的契约。改一行代码前想想会影响谁。版本管理不是负担是保护伞。思考题你的API有版本管理吗有没有因为接口变更导致的问题个人观点仅供参考