java API接口怎样版本化

在 Java 里做 API 接口版本化，常见做法可以按「URL、请求头、参数、媒体类型、代码组织」几个维度来设计。下面系统讲一下主流方案和示例。

一、基于 URL 路径（最常用 ✅）

方式：在路径中带版本号

/api/v1/users
/api/v2/users

Spring Boot 示例

@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller {
    @GetMapping
    public List<UserV1> list() { ... }
}

@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller {
    @GetMapping
    public List<UserV2> list() { ... }
}

✅ 优点

• 简单直观
• 易于调试、日志清晰
• 浏览器/网关友好

❌ 缺点

• URL 会变
• 控制器类会增多

二、基于请求参数（可选）

/api/users?version=1
/api/users?version=2

@GetMapping("/users")
public Object list(@RequestParam int version) {
    if (version == 1) return userService.listV1();
    return userService.listV2();
}

✅ 简单
❌ 不推荐大型系统（URL 不清晰）

三、基于 Header（推荐用于 REST）

GET /api/users
Accept: application/vnd.myapi.v1+json

或

GET /api/users
X-API-Version: 2

Spring 示例

@GetMapping(value = "/users", headers = "X-API-Version=1")
public List<UserV1> listV1() { ... }

@GetMapping(value = "/users", headers = "X-API-Version=2")
public List<UserV2> listV2() { ... }

✅ 优点

• URL 稳定
• 更符合 REST 风格

❌ 缺点

• 不够直观
• 浏览器测试麻烦

四、基于 Content-Type / Accept（HATEOAS 风格）

Accept: application/vnd.company.user.v1+json

常配合 Spring HATEOAS / Spring Content Negotiation

✅ 专业
❌ 复杂度高

五、基于注解的优雅方案（推荐 ⭐）

自定义版本注解

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    int value();
}

@RestController
@RequestMapping("/users")
public class UserController {

    @ApiVersion(1)
    @GetMapping
    public Object v1() { ... }

    @ApiVersion(2)
    @GetMapping
    public Object v2() { ... }
}

通过 HandlerInterceptor 或 RequestMappingHandlerMapping 解析版本。

✅ 适合中大型系统
✅ 可统一控制

六、代码组织建议（重要）

controller
 ├── v1
 │   └── UserController.java
 ├── v2
 │   └── UserController.java

dto
 ├── v1
 │   └── UserDTO.java
 ├── v2
 │   └── UserDTO.java

或

api
 ├── UserApiV1
 ├── UserApiV2

七、版本策略建议

✅ 推荐组合

• 对外 API：URL 版本（v1 / v2）
• 内部微服务：Header 或注解
• 长期演进：DTO 分层 + 兼容策略

✅ 版本原则

• 只新增，不破坏旧版本
• 旧版本至少维护 6–12 个月
• 明确 Deprecated 时间

八、总结对照表

如果你用的是 Spring Boot / Spring Cloud / 微服务 / Gateway，我可以给你一份完整版本化方案模板（含拦截器、Swagger、网关路由）。