API版本管理规范
良好的API需要保持向前兼容，特别是在APP场景或者是其他第三方客户端的场景，产品需求的升级改进要求不影响现有的版本正常工作。因此对外暴露的所有API需要有统一的版本管理策略来应对兼容性问题。
版本控制模式
根据不同的应用场景，制定了两种API的版本控制模式：
1. API（URL）自带版本
https://www.fota.com/api/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.2/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.3/account/user/general?_t=1541397626404
2. HTTP Header指定版本
:authority: fota.com
:method: GET
:path: /api/account/user/general?_t=1541402217410
:scheme: https
accept: application/json, text/plain
accept-encoding: gzip, deflate, br
api-version:1.0.1
API版本升级方案约定和案例
开闭原则。
对于小版本的更新可以在单个接口中进行处理，对于大版本的更新，可以提供新的Controller，或新建服务部署新版本的接口，保留每个版本的服务。
1. 小版本升级
小版本的更新，在原接口中做扩展，做兼容。例如：一个应用场景，在1.0.1版本是获取的是总资产和保证金率的数据，在1.0.2版本获取的是总资产和安全边界的数据，在后续的版本获取的是保证金率和安全边界的数据。
@Authorization
@RequestMapping(value = "/general", method = RequestMethod.GET)
@ResponseBody
public Result getUserGeneralInfo() {
String apiVersion = RequestHeaderContext.getInstance().getApiVersion();
if (apiVersion.equals("1.0.1")){
// 获取总资产和保证金率数据
} else if (apiVersion.equals("1.0.2")){
// 获取总资产和安全边界数据
} else {
// 获取保证金率和安全边界数据
}
Long userId = tokenUtil.getUserIdByLoginToken(RequestHeaderContext.getInstance().getToken());
return accountManager.getUserGeneralInfo(userId);
}
当然，服务端也可以做兼容，把总资产、保证金率和安全边界的数据都返回，保障返回的JSON对象字段只增不删不改，客户端根据自己当前的版本显示不同的值。
apiVersion的值是从Header获取：
:authority: fota.com
:method: GET
:path: /api/contract/list?contractId=1027&_t=1541402217410
:scheme: https
accept: application/json, text/plain
accept-encoding: gzip, deflate, br
api-version:1.0.1
2. 大版本升级
无法兼容的接口，采用新建Controller，甚至部署新的应用服务和nginx。例如：这次这个接口需要获取的数据是一个List的数据，而不是两个单独的值。
把修改的接口放在新的Controller中，旧的接口不需要处理，客户端自己区分。
@Slf4j
@Controller
@RequestMapping("v1.2/account/user")
public class AccountControllerV2 extends BaseController {
@Autowired
private AccountManager accountManager;
/**
* 总资产和保证金率的List数据
*
* @return
*/
@Authorization
@RequestMapping(value = "/general", method = RequestMethod.GET)
@ResponseBody
public Result getUserGeneralInfo() {
String apiVersion = RequestHeaderContext.getInstance().getApiVersion();
if (apiVersion.equals("1.2.1")){
// 获取总资产和保证金率数据
} else if (apiVersion.equals("1.2.2")){
// 获取总资产和安全边界数据
} else {
// 获取保证金率和安全边界数据
}
Long userId = tokenUtil.getUserIdByLoginToken(RequestHeaderContext.getInstance().getToken());
return accountManager.getUserGeneralInfo(userId);
}
}
在服务端新建Controller，甚至部署新的应用服务和nginx（方便回滚）。
https://www.fota.com/api/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.2/account/user/general?_t=1541397626404
https://www.fota.com/api/v1.3/account/user/general?_t=1541397626404
使用场景
1. 接口变动非常大或者整个产品大版本发布
此种情况下可以采用URL自带版本的方式，提供新的Controller，甚至部署新的应用服务和nginx。URL中无版本号即走默认逻辑。
2. 常规的版本升级和BUGFIX
一般情况下使用HTTP Header中指定的版本号，在代码逻辑中进行判断就可满足需求。Header中无版本号即走默认处理逻辑。
3. 两种模式同时使用
URL自带模式用来处理大版本变动，当大版本已经升级完成，后续的小需求迭代仍然可以使用HEADER的方式来保持API兼容。
