如何更优雅管理API接口版本（v1/v2/v3…）

一、前言

一个web项目中，随着需求的变更或增加，API接口也会跟着变化，而如果APP发布后，已使用的接口肯定不能直接覆盖更新，需要新增升级版本接口和新的APP版本对应，因此多个版本接口更替后，如何更优雅管理不同版本接口代码，如何设计更直观的接口文档呈现给app端，这是我们后端工程师需要考虑的事情，下面总结接口版本管理经验。

二、接口代码版本规范

考虑到接口今后一定会进行版本迭代，因此一开始开发的时候，就需要对代码进行版本考量下的代码目标架构。

1. 控制器目录架构：

v1版本控制器目录：apps/controller/v1/……

v2版本控制器目录：apps/controller/v2/……

    在controller下增加子集文件夹：controller/v1/……、controller/v2/……等等，初始版本的接口全部放在v1下。

2. 接口路由设计

v1版本接口路由：/v1/login

v2版本接口路由：/v2/login

3. 不同版本控制器代码分类依据

（1）在发布APP前的所有代码，都属于v1版本代码；

（2）发布APP后，如果是新增加的需求，和已发布v1版本接口需求不冲突，新增控制器或接口，仍然属于v1版本代码；

（3）发布APP后，如果新增需求和v1已发布版本接口冲突，为了兼容老版本APP，必须在v2文件夹下新增控制器开发v2版本接口。

遵循以上分类原则，依次递推，严格区分不同版本接口代码，结合下一部分的接口文档，利于不同版本接口更新维护。

三、不同版本接口文档规范

版本迭代的接口，如果写在一起，APP真的要疯。最好能给APP一种重新开始的感觉，归零后，面对新接口，沟通起来新老接口文档区别明显，这就大大避免了无谓的撕逼。具体接口文档设计如下：

| —— 文档快捷导航

| —— 产品交互流程
    | —— v1版本
    | —— v2版本
    | —— ……

| —— 文档规范
    | —— 接口规范（接口地址，请求方式，接口参数，响应参数）
    | —— 接口文档规范
    | —— ……

| —— 开发计划

| —— 全局状态码

| —— 【v1】API文档
    | —— v1接口文档说明：包含v1接口基础地址、状态码、推送码等说明；
    | —— v1接口更新日志
    | —— 用户模块
    | —— 设备模块

| —— 【v2】API文档
    | —— v2接口文档说明：包含v2接口基础地址、状态码、推送码等说明；
    | —— v2接口更新日志
    | —— 用户模块
    | —— 设备模块
    

目录说明：
    1. 文档快捷导航：根据接口目录结构，把不同版本接口汇总到表格中，然后对应加上接口文档链接，让APP对接时更容易定位接口位置，如：

【v1】API  [文档说明(带链接)]  [更新日志(带链接)]
路由	说明
/v1/login（带指向接口文档的链接）	用户登录
/v1/user/info（带指向接口文档的链接）	获取用户详情
……

【v2】API [文档说明(带链接)]  [更新日志(带链接)]
路由	说明
/v2/login（带指向接口文档的链接）	用户登录
/v2/user/info（带指向接口文档的链接）	获取用户详情
……

    2. 全局状态码：根据接口、推送等不同板块业务需求，对不同业务下的接口设计不同数字段的状态码，遇到这样设计下的状态码，沟通或出现问题更容易定位接口，如：

       指定200为正确响应状态码，500为服务器异常响应状态码；

       其他情况下，根据业务模块区分，用户功能相关接口非正确响应状态码指定1001~1050；设备操作功能模块非正确响应状态码指定1051~1100，以此类推。

    3. 接口更新日志说明：APP对接接口前，不用记录接口更新日志；APP对接后，接口输入参数或输出参数有变化时，需记录接口更新日志，接口更新日志记录模板如下：

格式如下：

日期【年-月-日】

1. 功能模块文件夹名称：接口名称（带链接），[增加 | 减少] [必要 | 非必要] [上报 | 响应] 参数 xxx；
2. 功能模块文件夹名称：接口名称（带链接），[增加 | 减少] [必要 | 非必要] [上报 | 响应] 参数 xxx；
……


如：

2019-04-22

1. 用户模块：用户登录，增加必要上报参数type；
2. 设备模块：添加设备，增加响应参数name字段；
……

2019-04-25

1. 用户模块：用户登录，增加必要上报参数type；
2. 设备模块：添加设备，增加响应参数name字段；
……