一、前言

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

二、接口代码版本规范

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

1. 控制器目录架构：

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

2. 接口路由设计

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

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

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

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

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

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

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

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

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

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

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

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