README

Laravel 13+ 统一 API 响应与异常处理扩展包。

要求

• PHP >= 8.4
• Laravel ^13.0

跨框架对齐

Hyperf 侧对应实现：felo-z/hyperf-api-response（PHP >= 8.2，Hyperf >= 3.2）。

两包共享相同的 JSON 契约、ap() 调用方式与 Pipeline 设计，便于 Laravel 与 Hyperf 服务返回一致格式。

安装

composer require felo-z/laravel-api-response

发布配置（可选，包已内置默认配置）：

php artisan vendor:publish --provider="FeloZ\LaravelApiResponse\ApiResponseServiceProvider"

快速使用

ap()->ok(['id' => 1], 'ok');
ap()->success(['id' => 1], 'success');
ap()->message('created', 201, ['id' => 1]);
ap()->failed('bad request', 400, ['field' => 'name']);
ap()->exception($throwable);

也支持 Facade：

\FeloZ\LaravelApiResponse\Facades\Ap::ok(['id' => 1], 'ok');

响应结构

{
  "status": true,
  "code": 200,
  "message": "OK",
  "data": {},
  "error": {}
}

HTTP 状态码策略

• code 在 100–599：HTTP 状态码 = code
• code 为业务码：成功 → HTTP 200，失败 → HTTP 400

业务失败不会被误判为系统 500，与 Hyperf 版行为一致。

异常自动接管

安装后通过 ApiResponseServiceProvider 注册 render_using，对以下请求自动将未捕获异常转为统一 JSON：

• expectsJson() 为 true
• 路径匹配 render_api_paths（默认 api/*）

业务代码只需 throw，无需手动 return ap()->exception(...)。

文档

• API 响应使用说明
• 接入示例
• 前后端约定模板
• 前端判定规则
• 项目扩展指南
• 升级说明

开发

composer install
composer run test
composer run fix-style

License

MIT