PHP接口版本控制：URL与Header双控技巧

// 检查是否以 /api/v{number} 开头 if (count($parts) >= 3 && $parts[1] === 'api') { $version = $parts[2];

if ($version === 'v1') {
    include 'controllers/v1/UserController.php';
    $controller = new V1\UserController();
    echo $controller->getList();
} elseif ($version === 'v2') {
    include 'controllers/v2/UserController.php';
    $controller = new V2\UserController();
    echo $controller->getList();
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Unsupported API version']);
}

} else { http_response_code(404); echo json_encode(['error' => 'Not found']); }

实际项目中可结合框架路由（如 Laravel、Slim）实现更优雅的分组路由：
```php
// Slim Framework 示例
$app->group('/api/v1', function () {
    $this->get('/users', 'V1\UserController:getList');
});

$app->group('/api/v2', function () {
    $this->get('/users', 'V2\UserController:getList');
});
```

2. 通过 Header 携带版本号控制逻辑
这种方式更“RESTful”，将版本信息放在请求头中，保持 URL 干净。常见做法是使用自定义 Header，如：

Accept-Version: v1

或复用 Accept 头：

Accept: application/json; version=v1

实现逻辑：

  
在入口文件或中间件中读取请求头中的版本标识
  
根据版本选择不同的处理逻辑或注入不同服务
  
统一 URL 路径，后端自动适配版本


读取 Header 版本示例：
```php
function getApiVersion() {
    // 方法一：读取自定义头
    $version = $_SERVER['HTTP_ACCEPT_VERSION'] ?? 'v1'; // 默认 v1

    // 方法二：解析 Accept 头（更标准）
    $accept = $_SERVER['HTTP_ACCEPT'] ?? '';
    if (preg_match('/version=(v?[0-9]+)/i', $accept, $matches)) {
        $version = $matches[1];
    }

    return strtolower($version);
}

// 使用
$version = getApiVersion();

if ($version === 'v1') {
    $service = new V1\UserService();
} elseif ($version === 'v2') {
    $service = new V2\UserService();
} else {
    http_response_code(400);
    echo json_encode(['error' => 'Invalid version']);
    exit;
}

echo json_encode($service->getUsers());
```

优点对比：

  
URL 版本：简单明了，便于调试和缓存，适合大多数场景
  
Header 版本：URL 更规范，适合对 REST 设计要求高的系统，但调试略复杂


3. 混合策略与最佳实践
实际项目中可以结合两种方式，优先级建议为：

Header 版本 > URL 版本 > 默认版本

这样客户端可通过任意方式指定版本，提升灵活性。

建议：

  
明确文档中说明版本控制方式
  
设置默认版本，避免未传版本时出错
  
废弃旧版本时返回 410 或提示升级信息
  
使用中间件统一处理版本解析，避免重复代码


基本上就这些。关键在于统一规则、清晰划分逻辑，并保持向后兼容性。不复杂但容易忽略细节。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《PHP接口版本控制：URL与Header双控技巧》文章吧，也可关注golang学习网公众号了解相关技术文章。