PHP 8.1怎么实现API接口版本管理

前言接口上线三个月产品要改一个字段的语义status从整数枚举改成字符串。你改了代码老版本 App 立刻白屏因为客户端把paid当成数字解析失败。这时候才发现项目里根本没有「版本」这个概念——所有请求都打在/api/users上改一次就是一次全量破坏性变更。版本管理的核心不是「多加一个路径前缀」而是三件事让客户端能明确声明它要哪个版本、让服务端能把请求路由到对应版本的实现、让旧版本能安全地下线。前两件是技术问题第三件是流程问题但只有三件都做到版本号才真的有用。本文以 PHP 8.1 为基准用到了PHP 8.1引入的枚举、只读属性、never返回类型、一等可调用语法实现一套最小可用的版本管理骨架用枚举定义版本、用三种策略解析客户端声明的版本、用一个版本化的处理器注册表分发请求并在响应里带上废弃提示头。示例是完整可运行的 CLI 程序不需要 Web 服务器。一、先选版本标识放在哪三种常见位置各有取舍方式请求示例优点缺点URL 路径GET /v2/users直观、好调试、天然进缓存键版本「长」在 URL 里改版就要改路径请求头Accept: application/vnd.demojson;version2URL 干净、语义规范手写 curl 调试麻烦容易被网关忽略查询参数GET /users?version2实现最简单容易漏进缓存键导致串版本语义弱实际项目里的稳妥做法是路径优先、请求头兜底路径方式让绝大部分客户端和网关都不出错请求头方式留给不方便改 URL 的场景。查询参数不推荐作为主方案因为 CDN 和反向代理的缓存键如果没把version算进去v1的响应会被回给v2的客户端。选好位置之后要定一条铁律未声明版本的请求必须落到一个固定版本上而且这个默认值要写进文档、写进测试。默认值跟着「最新版」漂移是最隐蔽的破坏性变更。二、用枚举把版本变成类型版本号是典型的「有限取值集合」用枚举最合适。枚举是 PHP 8.1 引入的顺带澄清一个常见混淆只读属性也是 8.1但只读类要到 8.2两者别搞混?php declare(strict_types1); // api_version.php —— 需要 PHP 8.1 /** 支持的接口版本 */ enum ApiVersion: string { case V1 v1; case V2 v2; /** 请求里没声明版本时落到哪个版本——这个值必须固定不能随时改成「最新」 */ public const FALLBACK self::V2; /** 当前对外主推的版本 */ public const LATEST self::V2; /** 已废弃版本的停服时间null 表示还在维护中 */ public function sunsetDate(): ?string { return match ($this) { self::V1 Wed, 01 Jul 2026 00:00:00 GMT, // HTTP 日期格式 self::V2 null, }; } public function isDeprecated(): bool { return $this-sunsetDate() ! null; } }枚举带来两个实打实的好处一是ApiVersion::tryFrom(v3)直接返回null不用手写校验分支二是处理器注册表的键变成受类型约束的值拼错版本号会在开发期就暴露。注意sunsetDate()返回的是 HTTP 日期格式的字符串——Sunset响应头要求的正是这个格式。三、三种来源的解析顺序final class ApiRequest { public function __construct( public readonly string $method, public readonly string $path, public readonly array $query [], public readonly array $headers [], ) {} } final class VersionResolver { /** 兜底版本构造时可覆盖方便测试 */ public function __construct(private string $fallback v2) {} public function resolve(ApiRequest $req): ApiVersion { // 1) 路径前缀/v1/users、/v2/users if (preg_match(#^/(v\d)(?:/|$)#, $req-path, $m) 1) { return $this-parse($m[1]); } // 2) Accept 头application/vnd.demojson;version2 $accept (string) ($req-headers[accept] ?? ); if (preg_match(/version(\d)/i, $accept, $m) 1) { return $this-parse(v . $m[1]); } // 3) 兜底固定默认版本 return $this-parse($this-fallback); } private function parse(string $raw): ApiVersion { $version ApiVersion::tryFrom($raw); if ($version null) { throw new ApiError(400, 不支持的接口版本{$raw}); } return $version; } } final class ApiError extends RuntimeException { public function __construct(public readonly int $status, string $message) { parent::__construct($message); } }只读属性readonlyPHP 8.1让ApiRequest一旦构造完就不可变中间件没办法偷偷改掉路径或版本头——排查问题时这一点很省事。四、分发一个版本一张处理器表不要在控制器里写if ($version ApiVersion::V1) { ... } else { ... }。版本分支一旦散落到各处加第三版时你会想把项目删掉重来。正确做法是把「版本 方法 路径」映射到处理器处理器之间的差异由各自实现负责。实战完整可运行示例把下面这段保存成api_version.php直接php api_version.php运行它会用八个模拟请求跑完整条链路。?php declare(strict_types1); // api_version.php —— 需要 PHP 8.1 /* 上面的 ApiVersion / ApiRequest / ApiError / VersionResolver 放在这里 */ /** 把 [状态码, 响应体, 响应头] 渲染成文本供 CLI 演示打印 */ function render(array $response): string { [$status, $payload, $headers] $response; $out HTTP {$status}\n; foreach ($headers as $name $value) { $out . {$name}: {$value}\n; } return $out . json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES) . \n; } /** 真实部署时的出口输出响应并结束进程。never 表示这个函数永不返回 */ function sendJson(int $status, array $payload, array $headers []): never { http_response_code($status); header(Content-Type: application/json; charsetutf-8); foreach ($headers as $name $value) { header({$name}: {$value}); } echo json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), \n; exit; // 声明成 never 就必须真的不返回 } final class ApiKernel { /** var arraystring, arraystring, callable 版本 METHOD /path 处理器 */ private array $handlers []; private VersionResolver $resolver; public function __construct() { $this-resolver new VersionResolver(ApiVersion::FALLBACK-value); // ---- v1裸数组 整数状态 ---- $this-handlers[ApiVersion::V1-value][GET /users] static fn (): array [ users [[id 1, name alice, status 1]], ]; // ---- v2包一层 data/metastatus 改成字符串 ---- $this-handlers[ApiVersion::V2-value][GET /users] static fn (): array [ data [[id 1, name alice, status active]], meta [page 1], ]; // v1 独有的老接口 $this-handlers[ApiVersion::V1-value][GET /legacy/ping] static fn (): array [pong 1]; } /** return array{int, array, array} [状态码, 响应体, 响应头] */ public function dispatch(ApiRequest $req): array { try { $version $this-resolver-resolve($req); $path $this-stripVersionPrefix($req-path); $key $req-method . . $path; $handler $this-handlers[$version-value][$key] ?? null; if ($handler null) { throw new ApiError(404, 接口不存在{$req-method} {$path}); } $headers $this-lifecycleHeaders($version); $headers[X-Api-Version] $version-value; return [200, [ok true, body $handler()], $headers]; } catch (ApiError $e) { return [$e-status, [ok false, error $e-getMessage()], []]; } } /** 把 /v2/users 还原成 /users避免处理器表里塞两套路径 */ private function stripVersionPrefix(string $path): string { return preg_replace(#^/v\d#, , $path) ?: /; } /** 废弃与停服提示 */ private function lifecycleHeaders(ApiVersion $version): array { if (!$version-isDeprecated()) { return []; } $headers [Deprecation true]; $sunset $version-sunsetDate(); if ($sunset ! null) { $headers[Sunset] $sunset; } return $headers; } } // ---------------- 模拟八个请求 ---------------- $kernel new ApiKernel(); $cases [ [GET, /v1/users, [], []], [GET, /v2/users, [], []], [GET, /users, [], []], // 未声明版本 - 兜底 [GET, /users, [], [accept application/vnd.demojson;version1]], // 头里声明 v1 [GET, /v3/users, [], []], // 不存在的版本 [GET, /v1/legacy/ping, [], []], [GET, /v2/legacy/ping, [], []], // v2 里已删掉 [POST, /v2/users, [], []], // 方法不支持 ]; foreach ($cases as [$method, $path, $query, $headers]) { printf( %s %s %s \n, $method, $path, $headers [] ? : json_encode($headers)); echo render($kernel-dispatch(new ApiRequest($method, $path, $query, $headers))), \n; } // 真实部署时的入口php -S 或 FPM把请求交给同一套内核再走 sendJson 输出 if (PHP_SAPI ! cli) { sendJson(...$kernel-dispatch(new ApiRequest( $_SERVER[REQUEST_METHOD] ?? GET, (string) (parse_url($_SERVER[REQUEST_URI] ?? /, PHP_URL_PATH) ?: /), $_GET, array_change_key_case(getallheaders() ?: [], CASE_LOWER), ))); }运行后会看到几个关键结果/v1/users返回status为整数1并带上Deprecation: true和Sunset/v2/users返回status为字符串active加上data/meta外层不带版本的/users落到v2/v1/legacy/ping有响应而/v2/legacy/ping返回 404 —— 这正是版本管理的意义同一个路径在不同版本下可以是完全不同的东西。常见坑点1. 把版本判断散落在业务代码里❌if ($version v1) { $status (int) $row[status]; } else { $status $row[status]; }散落在几十个方法里。 ✅ 每个版本一份独立的处理器实现差异集中在各自的实现里共享逻辑抽到内部服务层而不是在控制器里打补丁。2. 用浮点或字符串大小比较版本❌if ((float) $v 1.5)——1.10会被当成1.1比1.9小v10 v9在字符串比较下也成立。 ✅ 用枚举本文做法或者把版本存成整数1、2、10再比较大小。3. 默认版本跟着「最新版」漂移❌ 上线 v3 时顺手把兜底版本从v2改成v3所有没声明版本的客户端被静默升级。 ✅ 兜底版本是一个独立的、需要评审才能改的常量本文的ApiVersion::FALLBACK和LATEST分开维护。4. 认为「只加字段」就绝对安全❌ 给user对象加一个role字段认为老客户端会忽略它。实际上严格校验 schema 的客户端尤其用了强类型反序列化的移动端框架会因为多出未知字段而解析失败。 ✅ 兼容性判断标准是「旧客户端能否安全忽略」不确定时就把新增字段放进新版本或者让客户端显式声明兼容模式。5. 版本不支持时返回 404❌ 请求/v9/users时返回 404 和「接口不存在」——客户端会以为是自己拼错了路径反复重试。 ✅ 返回 400或 406取决于语义并明确说明「不支持的接口版本」让客户端能区分「版本不对」和「路径不对」。6. 忘了给旧版本发废弃信号❌ v1 还在跑但没有加任何提示客户端不知道该升级直到停服那天集体故障。 ✅ 响应里带上Deprecation: true和Sunset停服时间HTTP 日期格式并在文档里提前公告。这两个头都是提示不会让客户端自动行为改变所以还必须配合实际的沟通。7. 版本号没进缓存键❌ 用?version2标识版本CDN 按「路径」缓存结果 v2 的响应被回给了 v1 的客户端。 ✅ 版本信息必须出现在缓存键里。用路径方式天然满足用查询参数或请求头方式要在 CDN 配置里显式把对应维度加进Vary或缓存键。8. 只在输出上做版本区分输入不做❌ 新版请求体多了一个filters字段但老版本的处理器也收到同一个请求体于是把不认识的字段静默忽略或直接报错。 ✅ 请求体解析和校验同样要按版本走未知字段的处理策略拒绝还是忽略要写进每个版本的约定里。总结环节做法关键点版本位置路径优先请求头兜底版本必须进缓存键类型表达enum ApiVersion: stringtryFrom()直接给出校验解析顺序路径 →Accept头 → 兜底兜底版本固定不随最新版漂移分发版本 方法路径 处理器差异集中在各版本实现里下线DeprecationSunset头提示之外还要有实际沟通错误版本不支持返回 400/406与「路径不存在」区分开API 版本管理的难点不在解析出v1还是v2而在于把「版本」当成一条贯穿请求全流程的显式维度路由要认它、缓存要认它、请求体校验要认它、下线流程也要认它。PHP 8.1 的枚举和只读属性恰好能把这条维度表达成类型让拼错的版本号在开发期就报错而不是等到线上白屏。