应根据项目规模与长期规划选择框架：中小团队选ThinkPHP 8以快速上线，中大型项目选Laravel以支撑复杂生态；路由须复数名词、嵌套≤两级、版本前置；控制器方法需严格对应REST动作并强制验证；响应统一状态码（201/404/422）与data/error结构；文档须通过注解与工具实时同步。
你需要在PHP项目中快速搭建一套符合行业标准的RESTful API，同时避开常见框架选型陷阱和设计雷区。这不只是写几个路由和控制器的事——从路由命名到状态码返回，从验证机制到文档同步，每一步都直接影响接口的可维护性与前端联调效率。
选框架：别被“流行”带偏节奏
ThinkPHP 8 和 Laravel 是当前国内 PHP API 开发最常被对比的两个选项，但适用场景差异极大。
方法一：选 ThinkPHP 8 —— 适合中小团队、交付周期紧、需快速上线的项目。它内置资源路由（Route::resource()）、开箱即用的验证器生成命令（php think make:validate User）、轻量级中间件链，且对国产云服务兼容性好。部署时只需 PHP 8.0+ 环境，无 Composer 依赖爆炸风险。
方法二：选 Laravel —— 适合中大型项目、长期演进系统、已有 Sanctum/JWT 认证体系或需对接 Scout/Elasticsearch 的场景。它的 Eloquent ORM 关联预加载、API Resource 资源转换、测试覆盖率工具链成熟，但 vendor 目录体积大，首次 composer install 常卡在 guzzlehttp/psr7 版本冲突上。
立即学习“PHP免费学习笔记（深入）”；
【注意：Laravel 11 默认禁用全局 CSRF 保护，但 API 路由仍可能意外继承 web 中间件组，导致 POST 请求 419 错误】
定路由：URL里一个动词都不能留
第一步：所有资源路径必须用复数名词，/users ✅，/user ❌，/getUsers ❌。
第二步：子资源嵌套最多两级，/users/123/orders ✅，/users/123/orders/456/items ❌——第三层应拆为独立资源 /items?order_id=456。
第三步：版本号必须前置且强制携带，/api/v1/users ✅，/users?version=v1 ❌。ThinkPHP 中在 route/app.php 里用 Route::group(['prefix' => 'api/v1'], function () { ... }) 封装；Laravel 则在 routes/api.php 外层加 Route::prefix('v1')->group(...)。
第四步：删除操作必须用 DELETE /api/v1/users/123，禁止写成 POST /api/v1/users/123/delete。后者会让 Nginx 缓存层误判为可缓存请求，且无法被 Swagger 自动生成 DELETE 标签。
写控制器：每个方法只干一件事
ThinkPHP 8 中执行：php think make:controller api/UserController，生成的类已预置 index、show、store、update、destroy 五个方法，直接填充业务逻辑即可。
Laravel 中运行：php artisan make:controller Api/UserController --api，该命令会跳过 create 和 edit 方法（它们属于 Web 页面逻辑），只保留 RESTful 必需的五个方法。
关键细节：所有 store 和 update 方法开头必须调用验证器，ThinkPHP 写 $this->validate($this->request->param(), 'User.create')，Laravel 写 $request->validate([...])。漏掉这步，非法手机号、超长昵称、SQL 注入字段会直通模型层。
设响应：状态码比 JSON 数据更重要
成功创建用户必须返回 HTTP 201 状态码，不是 200。ThinkPHP 中写 return json(['data' => $user])->code(201)；Laravel 中写 return response()->json(['data' => $user], 201)。
资源不存在统一返回 404，不要用 200 + {"error": "not found"}。前者能被前端 Axios 自动拦截进 catch，后者要手动判断字段，极易漏处理。
参数校验失败必须返回 422（Unprocessable Entity），不是 400。400 表示客户端语法错误（如 JSON 格式损坏），422 才表示数据语义错误（如邮箱格式不对、密码太短）。Laravel 默认支持，ThinkPHP 需在验证器中设置 failException 为 true 并捕获 ValidateException 后手动设 code 为 422。
所有响应体结构必须一致：顶层键名固定为 data（成功时）或 error（失败时），禁止混用 result、response、payload 等命名。这是前端 SDK 自动解析的前提。
配文档：不写注释=没写接口
方法一：用 ThinkPHP + topthink/think-swagger 扩展。安装后在 app/middleware/ 下注册中间件，然后给控制器方法加 PHPDoc 注解：@api @GET /api/v1/users、@param int $id、@return \think\Response。访问 /swagger 即实时渲染 UI。
方法二：Laravel 项目直接装 darkaonline/l5-swagger，运行 php artisan l5-swagger:generate。它会扫描 @OA\Get 等 OpenAPI 3.0 注解，但注意：控制器里不能出现 use OpenApi\Annotations as OA; 这种写法，必须用完整命名空间 @OA\Get，否则生成失败。
【关键前提：所有接口 URL 必须与路由定义完全一致，包括前缀 /api/v1/。Swagger 不识别动态路由参数别名，/users/{id} 必须写成 /users/{id}，不能写成 /users/:id】
