API废弃时应在响应头中使用Warning字段（如299码），配合200或426状态码，Laravel需手动注入且按路由精确控制，避免中间件统一处理；配置废弃映射、防范缓存覆盖，并可通过路由模型绑定实现版本感知。
API版本废弃时如何返回标准警告响应
直接在响应头里加 Warning 字段，配合状态码 200 或 426 Upgrade Required（后者更明确但需客户端配合）。Laravel 本身不内置该逻辑，得手动注入——别依赖中间件统一塞头，因为废弃提示必须精确到路由/控制器动作。
常见错误是只改响应体（比如加个 "deprecated": true），结果客户端根本收不到或忽略。HTTP 标准警告机制靠的是响应头，不是 JSON 字段。
- 用
response()->json()后链式调用header('Warning', '299 - "API v1 is deprecated; use v2 instead")' - 警告码必须是三位数字，
299是 IETF 指定的“厂商自定义警告”码，安全可用 - 不要用
410 Gone替代——那是资源彻底删除，不是“还能用但别用了”
在 Laravel 路由或控制器中动态判断是否废弃
硬编码版本判断容易漏，建议把废弃配置抽成数组，按路由名或控制器方法做映射。别用中间件全局扫描 request()->route()->getName()，性能差且无法区分同路由不同版本（比如 api.v1.users.index vs api.v2.users.index）。
使用场景：v1 接口还在跑，但已不接受新调用；v2 已上线，需让旧客户端感知升级必要性。
- 在
app/Http/Controllers/Api/V1/UserController.php的方法开头加检查：if (config('api.deprecated_routes')['users.index'] ?? false) { ... } - 配置项
api.deprecated_routes值为['users.index' => ['since' => '2024-03-01', 'replacement' => 'api.v2.users.index']] - 注意：路由名要和
Route::name()定义完全一致，大小写敏感
避免废弃提示被缓存覆盖
CDN 或浏览器缓存可能把带 Warning 头的响应缓存下来，导致新请求没触发废弃逻辑却仍返回旧警告。这不是 Laravel 的锅，但必须主动防御。
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
关键点在于：废弃提示是「有状态」的响应，不能被无差别缓存。
- 在返回警告响应时，强制设置
Cache-Control: no-cache, must-revalidate - 别依赖
Response::cache()，它默认不处理警告头的缓存语义 - 如果用了
redis缓存响应体，确保废弃判断逻辑在缓存读取之后、响应生成之前执行
Laravel 10+ 中利用 Route Model Binding 做版本感知路由
当接口路径含版本号（如 /api/v1/users），别用正则匹配提取版本再 if-else，容易和路由缓存、命名冲突。Laravel 的隐式绑定机制可以更干净地接管。
性能影响小，但要求你把版本号作为路由参数显式声明，并绑定到一个值对象。
- 定义路由：
Route::get('/api/{version}/users', [UserController::class, 'index'])->where('version', 'v1|v2') - 创建
app/Models/ApiVersion.php，实现resolveRouteBinding方法，检查$value === 'v1'时返回废弃标记 - 控制器里接收
ApiVersion $version，调用$version->isDeprecated()决定是否加警告头
复杂点在于，废弃不是二值开关——可能某接口在 v1.2 废弃，但 v1.1 还算“过渡期”。这种粒度得靠时间戳 + 版本比较，别图省事全写死布尔值。
