<?php/** * 案例053：API版本管理 * 说明：路由前缀v1/v2实现版本隔离，新旧版本并存，平滑升级 * 需要安装的包：hyperf/http-server */declare(strict_types=1);namespaceApp\Controller;useHyperf\HttpServer\Annotation\Controller;useHyperf\HttpServer\Annotation\GetMapping;useHyperf\HttpServer\Annotation\Middleware;useHyperf\HttpServer\Contract\RequestInterface;/** * 版本管理策略： * 方案一（推荐）：URL路径版本号 /api/v1/users、/api/v2/users * 方案二：请求头版本号 Accept: application/vnd.api+json;version=2 * 方案三：查询参数 /api/users?version=2 * * 这里用方案一，最直观，对缓存也友好 */// ========== V1版本（旧版本，继续维护中） ==========/** * V1用户接口 * 特点：返回字段少，格式简单 */#[Controller(prefix:'/api/v1/users')]classUserV1Controller{publicfunction__construct(privateRequestInterface$request){}/** * GET /api/v1/users/{id} * V1返回格式：字段少，直接返回data */#[GetMapping(path:'{id:\d+}')]publicfunctionshow(int$id):array{$user=\Hyperf\DbConnection\Db::table('users')->find($id);if(!$user){return['code'=>404,'message'=>'用户不存在'];}// V1只返回基础字段return['code'=>0,'data'=>['id'=>$user->id,'name'=>$user->name,// V1用name字段],];}#[GetMapping(path:'')]publicfunctionindex():array{$users=\Hyperf\DbConnection\Db::table('users')->select(['id','name'])// V1只返回id和name->paginate(20);return['code'=>0,'data'=>$users];}}// ========== V2版本（新版本） ==========/** * V2用户接口 * 特点：字段更丰富，格式有变化，比如name改成了nickname */#[Controller(prefix:'/api/v2/users')]classUserV2Controller{publicfunction__construct(privateRequestInterface$request){}/** * GET /api/v2/users/{id} * V2返回格式变化： * 1. name字段改名为nickname * 2. 新增avatar、created_at字段 * 3. 分页信息更丰富 */#[GetMapping(path:'{id:\d+}')]publicfunctionshow(int$id):array{$user=\Hyperf\DbConnection\Db::table('users')->find($id);if(!$user){return['code'=>404,'message'=>'用户不存在','data'=>null];}return['code'=>0,'message'=>'success','data'=>['id'=>$user->id,'nickname'=>$user->name,// V2改名了'avatar'=>$user->avatar??'',// V2新增字段'email'=>$user->email,// V2新增字段'created_at'=>$user->created_at,],];}#[GetMapping(path:'')]publicfunctionindex():array{$page=(int)$this->request->query('page',1);$size=(int)$this->request->query('size',20);$total=\Hyperf\DbConnection\Db::table('users')->count();$users=\Hyperf\DbConnection\Db::table('users')->select(['id','name as nickname','avatar','email'])// V2字段->forPage($page,$size)->get();return['code'=>0,'data'=>$users,'meta'=>['total'=>$total,'page'=>$page,'size'=>$size],// V2有meta];}}/** * 版本路由器：根据请求头里的Accept版本号自动路由到对应版本 * 同时支持URL路径版本和请求头版本两种方式 */classApiVersionMiddlewareimplements\Psr\Http\Server\MiddlewareInterface{publicfunctionprocess(\Psr\Http\Message\ServerRequestInterface$request,\Psr\Http\Server\RequestHandlerInterface$handler):\Psr\Http\Message\ResponseInterface{// 从Accept头解析版本号，如 Accept: application/json; version=2$accept=$request->getHeaderLine('Accept');$version='v1';// 默认版本if(preg_match('/version[=\/](\d+)/i',$accept,$m)){$version='v'.$m[1];}// URL路径里有明确版本号就用URL的，优先级更高$path=$request->getUri()->getPath();if(preg_match('#/api/(v\d+)/#',$path,$m)){$version=$m[1];}// 存到协程上下文，Controller里可以读到\Hyperf\Context\Context::set('api_version',$version);return$handler->handle($request);}}/** * 版本兼容性处理：用装饰器模式，V2继承V1复用代码，只重写变更的方法 */classUserV3ControllerextendsUserV2Controller{/** * V3只改了详情接口，列表接口复用V2的 */#[GetMapping(path:'{id:\d+}')]publicfunctionshow(int$id):array{$v2Result=parent::show($id);if($v2Result['code']!==0)return$v2Result;// V3在V2基础上增加更多字段$v2Result['data']['extra_field']='v3新字段';return$v2Result;}}
