PHPAPI版本管理与升级策略

PHPAPI版本管理与升级策略

API版本管理让接口可以平稳演进。不同客户端可以使用不同版本的API。今天说说PHP中API版本管理的实现。

URL路径版本是最常见的版本管理方式。

```php
// /api/v1/users
// /api/v2/users

class VersionedRouter
{
private array $routes = [];

public function version(int $version, callable $callback): void
{
$router = new Router();
$callback($router);
$this->routes[$version] = $router;
}

public function dispatch(string $method, string $uri): void
{
preg_match('#^/api/v(\d+)/#', $uri, $matches);
$version = (int)($matches[1] ?? 1);

$router = $this->routes[$version] ?? $this->routes[max(array_keys($this->routes))];
$router->dispatch($method, $uri);
}
}

$api = new VersionedRouter();

$api->version(1, function (Router $r) {
$r->get('/api/v1/users', fn() => json_encode(['version' => 'v1', 'users' => []]));
});

$api->version(2, function (Router $r) {
$r->get('/api/v2/users', fn() => json_encode(['version' => 'v2', 'users' => [], 'meta' => ['count' => 0]]));
});

// $api->dispatch('GET', '/api/v2/users');
?>

请求头版本管理。

```php
class HeaderVersionRouter
{
public function detectVersion(): int
{
$accept = $_SERVER['HTTP_ACCEPT'] ?? 'application/vnd.app.v1+json';
preg_match('/v(\d+)/', $accept, $matches);
return (int)($matches[1] ?? 1);
}

public function getController(string $base, int $version): string
{
return "App\\Api\\V{$version}\\{$base}Controller";
}
}
?>

版本之间的兼容性和迁移。

```php
class VersionMigrator
{
public static function migrateInputV1ToV2(array $v1Data): array
{
return [
'user_name' => $v1Data['name'],
'email' => $v1Data['email'],
'age' => $v1Data['age'] ?? null,
'tags' => isset($v1Data['tag']) ? [$v1Data['tag']] : [],
];
}

public static function migrateOutputV2ToV1(array $v2Data): array
{
return [
'name' => $v2Data['user_name'],
'email' => $v2Data['email'],
'age' => $v2Data['age'],
];
}
}

// 旧的v1接口
function handleV1Request(): array
{
$input = json_decode(file_get_contents('php://input'), true);
$v2Input = VersionMigrator::migrateInputV1ToV2($input);
$result = processV2Logic($v2Input);
return VersionMigrator::migrateOutputV2ToV1($result);
}
?>

API版本的废弃策略。

```php
class VersionPolicy
{
public static function getStatus(int $version): array
{
$policies = [
1 => ['status' => 'deprecated', 'sunset' => '2024-06-30', 'migrate_to' => 2],
2 => ['status' => 'stable', 'sunset' => null, 'migrate_to' => null],
3 => ['status' => 'beta', 'sunset' => null, 'migrate_to' => null],
];

return $policies[$version] ?? ['status' => 'unknown'];
}

public static function addWarningHeaders(int $version): void
{
$policy = self::getStatus($version);
if ($policy['status'] === 'deprecated') {
header('Warning: 299 - "This API version is deprecated. Migrate to v' . $policy['migrate_to'] . ' before ' . $policy['sunset'] . '"');
header('Sunset: ' . $policy['sunset']);
}
}
}
?>

API版本管理让接口可以平稳演进。URL路径版本直观易懂，请求头版本更干净。版本迁移要向前兼容，旧版本标记废弃后逐步下线。客户端有足够时间迁移到新版本。