基于Laravel开发RESTfulAPI接口设计规范【标准】-php教程-PHP中文网

api路由须定义在routes/api.php并带显式版本前缀（如/v1/users），禁用web.php中/api路径；jsonresource禁止业务逻辑；错误响应须标准化；业务逻辑必须下沉至service层。

基于laravel开发restfulapi接口设计规范【标准】

API路由必须定义在`routes/api.php`且带显式版本前缀

直接在web.php里写Route::get('/api/users', ...)是危险操作——它会意外加载start_session中间件，导致并发下「headers already sent」错误，且无法享受api中间件组默认禁用CSRF、session的防护机制。

版本号必须出现在URL路径中，例如/v1/users，而不是靠Accept: application/vnd.myapp.v2+json或?version=2。CDN缓存、Nginx日志分析、OpenAPI文档生成、监控埋点都依赖URI可读性与确定性。

routes/api.php里统一用Route::prefix('v1')->group(...)包裹所有路由
apiResource()生成的命名会自动带v1.前缀（如v1.users.index），这对route()辅助函数和测试断言至关重要
避免三级及以上嵌套路由（如/v1/users/{user}/posts/{post}/comments），实测响应延迟增加30%以上

`JsonResource`只做字段映射，禁止放业务逻辑

toArray()方法本质是视图层，不是处理器。一旦在里面调用$this->user->profile或Auth::user()，就可能触发N+1查询、权限绕过、序列化时抛出异常——而且这类问题在单元测试里极难复现。

常见错误现象包括：同一User模型在/v1/users和/v1/orders里返回字段不一致；资源类测试被迫mock数据库；API响应时间忽高忽低。

Laravel 13.2.0

PHP中文网提供Laravel 13.2.0版本下载，Laravel框架是基于 PHP 8.3+ 的高性能框架，官方推荐通过 Composer 安装。它内置 AI SDK、JSON:API Resources 及原生向量搜索，支持属性驱动开发与队列路由，大幅提升开发效率。相比旧版，13.2.0 优化了缓存 TTL 管理与实时通信，无需 Redis 即可横向扩展。作为现代 Web 开发首选，它兼顾安全与极速体验，助您快速构建企业级应用。

下载

只允许访问$this->属性或$this->relation（已预加载）
字段过滤、权限判断、关联数据组装，全部移入Service层或Controller，在调用new UserResource($user)前完成
需要动态字段（如is_favorite）时，用构造参数传入布尔值，而非在toArray()里查表

错误响应必须标准化，禁用调试信息

生产环境返回Whoops!页面或Exception堆栈，等于把数据库结构、文件路径、环境配置全送给攻击者。Laravel默认的APP_DEBUG=true仅限本地开发。

标准错误响应应包含status（HTTP状态码）、message（用户友好提示）、code（机器可读错误码，如VALIDATION_FAILED），不含任何敏感上下文。

全局注册App\Exceptions\Handler里的render()方法，对ValidationException、ModelNotFoundException等做统一JSON格式化
绝不使用response()->json(['error' => $e->getMessage()], 500)——$e->getMessage()可能泄露SQL或路径
第三方包（如Passport）抛出的异常，需在render()里显式捕获并降级为标准格式

业务逻辑必须下沉至`Service`层，Controller仅作协调

把验证、事务、第三方API调用、缓存更新全塞进Controller，会导致单个方法超200行、无法复用、难以测试。多人协作时，一个接口改三次，五个人要同步改七处代码。

典型症状：Controller里出现DB::transaction、Http::post()、Cache::remember()混用；同一个update逻辑在UserController和AdminUserController里重复实现。

每个核心用例建独立Service类（如UserRegistrationService），接受DTO对象，返回标准结果或抛出领域异常
Controller只负责解析请求、调用Service、包装Resource、返回响应——不超过15行
Service方法必须无副作用：不直接return响应，不调用abort()或response()

真正卡住团队的，从来不是“怎么让接口跑起来”，而是“当第17个前端调用/v1/users加了include=profile,settings时，你能否在不改Controller、不碰Resource的前提下，安全扩展字段加载逻辑”。这要求从第一天就守住分层边界——Service决定「做什么」，Resource决定「怎么展」，路由决定「怎么找」。