java API接口怎么版本化

在 Java 里做 API 接口版本化，常见做法大致可以分为 URL 路径、请求参数、Header、Content-Type、子域名 几种方式。下面按实用程度给你梳理一下，并附 Java（Spring Boot 为主）示例。

一、URL 路径版本（最常用 ✅）

方式：把版本写在 URL 中
示例：

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

Spring Boot 示例

@RestController
@RequestMapping("/api/v1/users")
public class UserV1Controller {

    @GetMapping
    public String getUsers() {
        return "v1 users";
    }
}

@RestController
@RequestMapping("/api/v2/users")
public class UserV2Controller {

    @GetMapping
    public String getUsers() {
        return "v2 users";
    }
}

✅ 优点：

• 直观、易调试
• 对前端友好
• 缓存、网关容易处理

❌ 缺点：

• URL 会变长

二、请求参数版本（较少用）

方式：通过参数区分版本

/api/users?version=1

@GetMapping("/users")
public String getUsers(@RequestParam int version) {
    if (version == 1) return "v1";
    if (version == 2) return "v2";
    throw new IllegalArgumentException();
}

✅ 优点：URL 不变
❌ 缺点：

• 不直观
• 不利于缓存

三、Header 版本（推荐用于 RESTful API）

方式：通过请求头区分

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

或

X-API-Version: 1

示例（自定义 Header）

@GetMapping(value = "/users", headers = "X-API-Version=1")
public String v1() {
    return "v1";
}

@GetMapping(value = "/users", headers = "X-API-Version=2")
public String v2() {
    return "v2";
}

✅ 优点：

• URL 干净
• 更符合 REST 风格

❌ 缺点：

• 调试不如 URL 直观

四、Accept Header（Content Negotiation）

Accept: application/vnd.company.app-v1+json

@GetMapping(
  value = "/users",
  produces = "application/vnd.company.app-v1+json"
)
public String v1() { return "v1"; }

适合 对外公开 API（如开放平台）

五、子域名版本（大厂常用）

v1.api.example.com/users
v2.api.example.com/users

适合：

• 微服务
• 多租户系统

六、Spring 推荐的“官方方式”（Spring 6+）

Spring 6 提供了 API Versioning

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

    @GetMapping
    @ApiVersion(1)
    public String v1() { return "v1"; }

    @GetMapping
    @ApiVersion(2)
    public String v2() { return "v2"; }
}

（需 Spring 6 / Spring Boot 3）

七、实际项目建议 ✅

最佳实践：

• 向后兼容尽量不改版本
• 老版本设 Deprecation 时间
• 文档（Swagger）明确标注版本

如果你愿意，我也可以帮你：

• 设计一套 API 版本规范
• 写一个 Spring Boot 版本路由示例
• 讲 如何优雅废弃旧版本 API

你现在的项目用的是 Spring Boot 几？