php如何实现接口版本管理_phpurl路径与header携带版本号控制逻辑

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']);
}

<p>实际项目中可结合框架路由（如 Laravel、Slim）实现更优雅的分组路由：</p>
<font style="color:#1976d2">```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');
});
```</font>

<H3>2. 通过 Header 携带版本号控制逻辑</H3>
<p>这种方式更“RESTful”，将版本信息放在请求头中，保持 URL 干净。常见做法是使用自定义 Header，如：<br>
<font style="color:#d32f2f">Accept-Version: v1</font><br>
或复用 Accept 头：<br>
<font style="color:#d32f2f">Accept: application/json; version=v1</font></p>

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

<p><strong>读取 Header 版本示例：</strong></p>
<font style="color:#1976d2">```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());
```</font>

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

<H3>3. 混合策略与最佳实践</H3>
<p>实际项目中可以结合两种方式，优先级建议为：<br>
Header 版本 > URL 版本 > 默认版本</p>

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

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

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