API版本控制的类型有哪些？如何实现API版本控制？

Hey there! Great question—API versioning is a critical part of building maintainable, user-friendly APIs, and there are several solid approaches to choose from. Let’s walk through each common type, how to implement them, and their pros and cons:

1. URL路径版本控制（最广泛使用） #

This is the most straightforward and intuitive method: you embed the version number directly into the API’s URL path. Users can immediately see which version they’re interacting with, which makes debugging and sharing links easy.

实现示例（Express.js） #

const express = require('express');
const app = express();

// 定义v1版本的路由
const v1Router = express.Router();
v1Router.get('/users', (req, res) => {
  res.json({ 
    version: 'v1', 
    data: [{ id: 1, name: 'Alice' }] 
  });
});

// 定义v2版本的路由
const v2Router = express.Router();
v2Router.get('/users', (req, res) => {
  res.json({ 
    version: 'v2', 
    data: [{ id: 1, fullName: 'Alice Smith' }] 
  });
});

// 挂载版本路由
app.use('/v1', v1Router);
app.use('/v2', v2Router);

app.listen(3000, () => console.log('API running on port 3000'));

Pros: 直观易懂，用户能快速识别版本；路由隔离清晰，便于维护。
Cons: 版本变更会改变URL，旧的书签/缓存链接需要更新；不符合部分REST purists的观点（认为URL应仅代表资源，而非版本）。

2. 查询参数版本控制 #

With this approach, you keep the base URL the same and specify the version via a query parameter (like ?version=v1). It’s a low-effort way to add versioning without restructuring your URL paths.

实现示例（Django） #

from django.http import JsonResponse

def get_users(request):
    # 默认使用v1版本
    api_version = request.GET.get('version', 'v1')
    
    if api_version == 'v1':
        return JsonResponse({
            'version': 'v1',
            'data': [{'id': 1, 'name': 'Alice'}]
        })
    elif api_version == 'v2':
        return JsonResponse({
            'version': 'v2',
            'data': [{'id': 1, 'fullName': 'Alice Smith'}]
        })
    else:
        return JsonResponse({'error': 'Unsupported API version'}, status=400)

Pros: 无需修改基础URL，兼容旧的无版本请求；实现简单，无需复杂路由配置。
Cons: 版本参数容易被忽略或遗忘；不符合REST最佳实践（查询参数应过滤资源，而非改变资源结构）。

3. 请求头版本控制 #

Here, you use a custom HTTP header (like X-API-Version) or the standard Accept header to specify the API version. This keeps your URLs clean and focused on resources, which aligns with REST principles.

实现示例（Spring Boot - 自定义头） #

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

    @GetMapping
    public ResponseEntity<?> getUsers(
        @RequestHeader(value = "X-API-Version", defaultValue = "v1") String version
    ) {
        if ("v1".equals(version)) {
            return ResponseEntity.ok(Map.of(
                "version", "v1",
                "data", List.of(Map.of("id", 1, "name", "Alice"))
            ));
        } else if ("v2".equals(version)) {
            return ResponseEntity.ok(Map.of(
                "version", "v2",
                "data", List.of(Map.of("id", 1, "fullName", "Alice Smith"))
            ));
        } else {
            return ResponseEntity.badRequest().body(Map.of("error", "Unsupported version"));
        }
    }
}

实现示例（Spring Boot - Accept头） #

You can also use the standard Accept header for content negotiation:

@GetMapping(produces = "application/vnd.example.v1+json")
public ResponseEntity<?> getUsersV1() {
    return ResponseEntity.ok(Map.of(
        "version", "v1",
        "data", List.of(Map.of("id", 1, "name", "Alice"))
    ));
}

@GetMapping(produces = "application/vnd.example.v2+json")
public ResponseEntity<?> getUsersV2() {
    return ResponseEntity.ok(Map.of(
        "version", "v2",
        "data", List.of(Map.of("id", 1, "fullName", "Alice Smith"))
    ));
}

Pros: URL保持干净，符合REST设计；版本信息不污染资源路径；适合服务间调用。
Cons: 不直观，用户无法从URL看到版本；调试时需要额外检查请求头，对非技术用户不太友好。

4. 媒体类型版本控制（Content Negotiation） #

This is a more formalized version of the Accept header approach, using vendor-specific media types (like application/vnd.yourcompany.v1+json). It’s defined by RFC standards and is the most REST-compliant method.

实现示例（FastAPI） #

from fastapi import FastAPI, Header
from pydantic import BaseModel

app = FastAPI()

# 定义不同版本的响应模型
class UserV1(BaseModel):
    id: int
    name: str

class UserV2(BaseModel):
    id: int
    fullName: str

@app.get("/users", response_model=UserV1)
async def get_users_v1(
    accept: str = Header("application/vnd.example.v1+json")
):
    return {"id": 1, "name": "Alice"}

@app.get("/users", response_model=UserV2)
async def get_users_v2(
    accept: str = Header("application/vnd.example.v2+json")
):
    return {"id": 1, "fullName": "Alice Smith"}

Pros: 完全符合REST规范；版本信息与媒体类型绑定，语义清晰；适合成熟的API生态。
Cons: 学习曲线较陡，用户需要了解自定义媒体类型；调试和文档需要额外说明。

选择建议 #

• 如果追求简单直观，优先选URL路径版本控制，适合面向开发者的公开API。
• 如果需要保持URL稳定，且版本逻辑简单，用查询参数版本控制。
• 如果想严格遵循REST设计原则，或者API主要供其他服务调用，选请求头/媒体类型版本控制。

内容的提问来源于stack exchange，提问作者Samet Baskıcı