企业官网建设流程全解析

前言

先纠正一个容易产生的误解：API 版本管理是一套接口演进规范，PHP 8.4 并没有提供内置的版本路由或版本隔离能力。你在 8.0 上怎么设计版本，8.4 上还是怎么设计。标题把「8.4」和「版本管理」放在一起，容易让人以为升级语言版本就能解决兼容问题。

PHP 8.4 对这件事的真实价值在于：属性钩子（Property Hooks）和非对称可见性让版本适配层写得更干净。旧版本接口和新版本接口共用同一个内部模型，输出格式的差异集中在几个计算属性上，而不是散落在十几个if ($version === 1)分支里。

本文先讲清楚哪些改动算破坏性变更，再给出三种版本策略的取舍，最后用一个完整的版本路由器加适配层示例（PHP 8.4+）把「一套代码同时服务 v1 和 v2」落地。

一、先定义什么叫做「兼容」

版本管理的全部难度来自一件事：已上线的接口有人在用，你不能改坏它。所以第一步是分清哪些改动是安全的：

一个实用的判断标准：只要一个老请求在改动后可能拿到不同的结果或者失败，就算破坏性变更，就必须开新版本。

二、三种版本策略的取舍

对绝大多数团队来说，URL 路径版本是默认选择：它让日志、监控、网关限流规则都能按版本切分，排查问题时一眼能看出调用方在用哪一版。

三、兼容旧接口的三层结构

真正决定项目会不会演变成「每个版本复制一份代码」的，是有没有把这三层分开：

入口层（版本路由） │ 根据 URL 前缀决定用哪套适配器 ▼ 适配层（DTO / 资源转换） │ 把内部统一模型转换成某个版本的线上格式 ▼ 领域层（业务逻辑，只有一份） 订单怎么创建、库存怎么扣，与版本无关

关键原则：领域层永远只有一份，版本差异只允许出现在入口层和适配层。如果某次改动让两个版本的业务逻辑真的不同了（比如 v2 引入了新的风控流程），那应该做成两个不同的领域服务，而不是在同一个方法里塞版本判断。

代码实战：一套代码同时服务两个版本

需求：v1的用户接口返回合并后的name字段和 Unix 时间戳；v2返回拆分后的first_name/last_name和 ISO 8601 时间。内部模型只有一个。

先写适配层（PHP 8.4+，用属性钩子把格式转换集中在属性定义处）：

<?php // resources.php —— 需要 PHP 8.4+ declare(strict_types=1); /** 内部统一模型，领域层只认它 */ final class UserModel { public function __construct( public readonly int $id, public readonly string $firstName, public readonly string $lastName, public readonly DateTimeImmutable $createdAt, ) {} } /** v1 的线上格式 */ final class UserResourceV1 { public function __construct(private UserModel $user) {} // 虚拟属性：没有后备存储，只由 get 钩子算出来 public string $name { get => trim("{$this->user->firstName} {$this->user->lastName}"); } public int $created_at { get => $this->user->createdAt->getTimestamp(); } public function toArray(): array { return [ 'id' => $this->user->id, 'name' => $this->name, 'created_at' => $this->created_at, ]; } } /** v2 的线上格式：字段拆开，时间用 ISO 8601 */ final class UserResourceV2 { public function __construct(private UserModel $user) {} public string $first_name { get => $this->user->firstName; } public string $last_name { get => $this->user->lastName; } public string $created_at { get => $this->user->createdAt->format(DateTimeInterface::ATOM); } // 非对称可见性：外部可读，只有本类能改，省掉一个 getter public private(set) string $schema = 'user.v2'; public function toArray(): array { return [ 'id' => $this->user->id, 'first_name' => $this->first_name, 'last_name' => $this->last_name, 'created_at' => $this->created_at, 'schema' => $this->schema, ]; } }

再写版本路由。这里用一个「按版本逐级回退」的注册表——某个接口在 v2 里没有特殊处理时，自动复用 v1 的实现，这样新增一个版本只需要登记真正变化的接口：

<?php // router.php —— 需要 PHP 8.4+ declare(strict_types=1); require __DIR__ . '/resources.php'; final class VersionRouter { /** @var array<string, array<string, callable>> 版本 => [路由键 => 处理器] */ private array $handlers = []; public function register(string $version, string $route, callable $handler): void { $this->handlers[$version][$route] = $handler; } /** 从请求版本开始，向低版本逐级回退查找处理器 */ public function resolve(string $version, string $route): callable { $candidates = ['v1', 'v2', 'v3']; // 有序的版本列表 $start = array_search($version, $candidates, true); if ($start === false) { throw new RuntimeException("未知的 API 版本: {$version}"); } for ($i = $start; $i >= 0; $i--) { $v = $candidates[$i]; if (isset($this->handlers[$v][$route])) { return $this->handlers[$v][$route]; } } throw new RuntimeException("未找到处理器: {$version} {$route}"); } } // ---- 组装 ---- $router = new VersionRouter(); // 两个版本共用的接口，只在 v1 注册一次即可 $router->register('v1', 'GET /users/{id}', function (int $id): array { $model = new UserModel($id, 'Ada', 'Lovelace', new DateTimeImmutable('2026-01-02T03:04:05+00:00')); return (new UserResourceV1($model))->toArray(); }); // v2 覆盖这一个接口，返回新格式 $router->register('v2', 'GET /users/{id}', function (int $id): array { $model = new UserModel($id, 'Ada', 'Lovelace', new DateTimeImmutable('2026-01-02T03:04:05+00:00')); return (new UserResourceV2($model))->toArray(); }); // ---- 模拟请求 ---- function dispatch(VersionRouter $router, string $method, string $path): array { // 解析 /v1/users/42 这类路径 if (preg_match('#^/(v\d+)(/.*)$#', $path, $m) !== 1) { throw new RuntimeException('路径必须带版本前缀，例如 /v1/users/42'); } [$all, $version, $rest] = $m; $id = 0; if (preg_match('#^/users/(\d+)$#', $rest, $mm) === 1) { $id = (int) $mm[1]; } $handler = $router->resolve($version, "{$method} {$rest}"); return $handler($id); } header('Content-Type: application/json; charset=utf-8'); // 对已废弃的 v1 明确发出弃用信号 $requestPath = '/v1/users/42'; if (str_starts_with($requestPath, '/v1/')) { header('Deprecation: true'); header('Sunset: Wed, 30 Jun 2027 23:59:59 GMT'); // 必须用 HTTP-date 格式 } echo json_encode(dispatch($router, 'GET', $requestPath), JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);

同一份代码分别请求两个版本，输出分别是：

GET /v1/users/42 { "id": 42, "name": "Ada Lovelace", "created_at": 1767323045 } GET /v2/users/42 { "id": 42, "first_name": "Ada", "last_name": "Lovelace", "created_at": "2026-01-02T03:04:05+00:00", "schema": "user.v2" }

Deprecation和Sunset响应头是被广泛支持的弃用信号：前者告诉调用方「这个版本已经进入废弃期」，后者给出一个明确的关停时间，格式必须是 HTTP-date（Wed, 30 Jun 2027 23:59:59 GMT），写成2027-06-30这类格式客户端解析不了。

常见坑点

1. 
   
2. 每个版本复制一份控制器
3. 
   
   

❌ 建app/v1/OrderController.php、app/v2/OrderController.php，两边各改一份。 ✅ 领域逻辑只保留一份，差异放到资源适配层；新版本默认复用旧实现。

1. 
   
2. 版本号只写在前端，后端不校验
3. 
   
   

❌ 前端把/v1硬编码进 URL，后端对未知版本默默按最新版处理。 ✅ 后端维护一份版本白名单，遇到未知版本返回 400 并列出支持的值，避免「静默升级」引发的事故。

1. 
   
2. 把版本号当默认参数放在查询串
3. 
   
   

❌GET /orders?version=2，某天有人把默认值从 1 改成 2，所有没传参数的调用方瞬间换结构。 ✅ 版本放在路径前缀里，缺失就是未定义行为，而不是「默认最新版」。

1. 
   
2. 用响应头里的字段告诉客户端版本，但结构本身没变
3. 
   
   

❌ 同一个 URL 有时返回name，有时返回first_name，靠头区分，缓存中间件一脸懵。 ✅ 结构变了就换 URL 前缀，让「同一 URL 结构恒定」这条不变式成立。

1. 
   
2. 属性钩子拿不到序列化结果
3. 
   
   

❌ 直接json_encode($resourceV1)，期望带出虚拟属性name。 ✅ 序列化只读取后备存储，虚拟属性不会自动出现，必须显式实现toArray()或JsonSerializable。

1. 
   
2. 把Sunset写成非 HTTP-date
3. 
   
   

❌Sunset: 2027-06-30—— 解析失败的客户端会直接忽略这个头，等于没发。 ✅ 用gmdate('D, d M Y H:i:s \G\M\T', $ts)生成。

1. 
   
2. 旧版本没有退出时间表
3. 
   
   

❌ 三个版本同时在线跑了两年，每个改动都要维护三套适配。 ✅ 从发布新版本那天起就定下旧版本的Sunset日期，并提前至少一个季度发出弃用通知。

1. 
   
2. 不做契约测试
3. 
   
   

❌ 改完内部模型，v1 的输出结构悄悄变了，直到客户报障才发现。 ✅ 为每个版本固化一组响应 fixture，在 CI 里对两个版本都跑一遍断言。

总结

要让新旧接口长期共存而代码不膨胀，靠的是三件事：把版本差异全部收敛到适配层、让高版本默认回退复用低版本的实现、以及给每个旧版本一个明确的Sunset时间。PHP 8.4 的属性钩子在这里只承担了一个很具体的角色——让「同一个内部字段、两种线上表示」写在一处，而不是散落在各处的条件分支里。