webapi 版本控制

一、问题

　　软件开发过程中，常常会需要变更以前的接口，添加或删除接口请求字段，接口字段校验、甚至是变更请求/返回字段名称，如果强制要求所有客户端跟着一起升级代价太大。如果接口从一开始就考虑到了版本的设计，那么做到平滑升级就很容易了。

二、版本控制方式

1、利用url传入版本

以@RequestMapping("/api")controller为例：

在路径里传入版本号：

优点：可以做到大版本切换，路由下的所有接口同时更新

缺点：实际中往往不会涉及很多接口同时升级，并且往往难以控制不同接口的版本（版本管理容易混乱）

    /**
     * http://localhost:8090/api/v1/getUser/111
     * {"userId":111,"userName":"小明"}
     *
     * @param userId
     * @return
     */
    @RequestMapping(value = "/v1/getUser/{userId}")
    public GetUserV1Response getUserInfoV1(@PathVariable("userId") Integer userId) {
        return new GetUserV1Response(userId, "小明");
    }

通过参数传入（POST 或 GET）

可以单独控制，注意version不存在和乱传值的处理

    /**
     * http://localhost:8090/api/getUser/111?version=v1
     * {"userId":111,"userName":"小明"}
     * <p>
     * http://localhost:8090/api/getUser/111?version=v2
     * {"userId":111,"userName":"小明","notes":"version 2"}
     *
     * @param userId
     * @return
     */
    @RequestMapping(value = "/getUser/{userId}")
    public Object getUserInfo(@PathVariable("userId") Integer userId, @RequestParam("version") String version) {
        if ("v1".equals(version)) {
            return new GetUserV1Response(userId, "小明");
        }
        return new GetUserV2Response(userId, "小明", "version 2");
    }

2、利用request header

以@RequestMapping("/api2")controller为例：

header设置在Controller或Action上都可以，设置在Controller上，控制所有Action的版本，设置在Action上，单独控制一个Action的版本

@RestController
@RequestMapping(value = "/api2")
public class ApiVersionHeaderDemoController {
    @Autowired
    private HttpServletRequest request;

    //request header
    @RequestMapping(value = "/getUserById/{userId}", headers = "version=v2")
    public Object getUserInfo(@PathVariable("userId") Integer userId) {return new GetUserV2Response(userId, "小明", "version 2");
    }
}

对应版本：

不支持的版本：

3、利用content type

利用自定义请求的Content-Type来控制版本：

    /**
     * 请求的是 application/vnd.apiversioncontrol.v1+json
     * 返回的是 application/json;charset=UTF-8
     * v1 是api版本
     *
     * @param userId
     * @return
     */
    @RequestMapping(value = "/getUserById/{userId}", consumes = "application/vnd.apiversioncontrol.v1+json")
    public Object getUserInfoV11(@PathVariable("userId") Integer userId) {
        return new GetUserV2Response(userId, "小明", "version 2");
    }

返回的是Content-Type：application/json;charset=UTF-8（不指定produces，默认是application/json;charset=UTF-8）

同时指定request和response的Content-Type为：application/vnd.apiversioncontrol.v2+json

    /**
     * 请求、返回Content-Type都是 application/vnd.apiversioncontrol.v1+json
     * v1 ：为api版本
     *
     * @param userId
     * @return
     */
    @RequestMapping(value = "/getUserById/{userId}", consumes = "application/vnd.apiversioncontrol.v2+json", produces = "application/vnd.apiversioncontrol.v2+json")
    public Object getUserInfoV12(@PathVariable("userId") Integer userId) {
        return new GetUserV2Response(userId, "小明", "version 2");
    }

同时指定request和response的Content-Type为：application/vnd.apiversioncontrol+json;version=v2

    /**
     * 请求、返回Content-Type都是 application/vnd.apiversioncontrol+json;version=v2
     * v2 ：为api版本
     *
     * @param userId
     * @return
     */
    @RequestMapping(value = "/getUserById/{userId}", consumes = "application/vnd.apiversioncontrol+json;version=v2", produces = "application/vnd.apiversioncontrol+json;version=v2")
    public Object getUserInfoV2(@PathVariable("userId") Integer userId) {
        return new GetUserV2Response(userId, "小明", "version 2");
    }

三、注解实现

注解来实现：SpingMVC框架实现restfull接口的版本控制

参考：webapi-version-control