https://github.com/mitoop/laravel-api-response
Normalize and standardize Laravel API response data structures.
https://github.com/mitoop/laravel-api-response
api response
Last synced: 5 months ago
JSON representation
Normalize and standardize Laravel API response data structures.
- Host: GitHub
- URL: https://github.com/mitoop/laravel-api-response
- Owner: mitoop
- Created: 2023-07-15T04:05:29.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2025-11-02T09:05:14.000Z (8 months ago)
- Last Synced: 2025-11-02T09:12:15.664Z (8 months ago)
- Topics: api, response
- Language: PHP
- Homepage:
- Size: 116 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
Laravel API Response
## ✨ 主要功能
🎯 提供统一且标准化的响应格式，同时支持普通分页与游标分页
🔧 支持自定义状态码与扩展字段
📦 灵活设置响应头（可添加签名、追踪 ID、版本号等）
🚀 无缝兼容 Laravel API 资源
🐛 已定制异常处理器，实现统一格式化输出
## 环境需求
以下为最低环境要求：
- PHP >= 8.2
- Laravel ^11.0｜^12.0
## 安装
```shell
composer require mitoop/laravel-api-response
```
## 输出格式
```jsonc
{
"success": true, // 请求是否成功。true 表示成功，false 表示失败。由系统自动判断，无需手动设置。
"code": 0, // 状态码。默认值为 0（成功）、1（失败）、-1（登录失效），可通过 `setDefaults` 自定义。
"message": "success", // 提示信息
"data": {}, // 成功响应的主体内容
"meta": { // 分页信息对象，仅在分页响应时返回
"pagination": "page", // 分页类型，可为 "page" 或 "cursor"
"page": 1, // 当前页码（仅 page 分页）
"page_size": 20, // 每页条数
"has_more": false, // 是否有下一页
"total": 100, // 总条数（仅 paginate 方法有，simplePaginate 没有）
"next_cursor": "..." // 下一个游标（仅 cursor 分页）
},
"errors": {} // 错误详情对象，仅在请求失败时返回，类型可为 object 或 array
}
```
## 使用
```php
use Mitoop\Http\RespondsWithJson;
class Controller extends BaseController
{
use RespondsWithJson;
}
```
#### 可用方法
包含三个方法 `success`, `error`, `deny`, 分别对应成功, 失败, 登录失效三种情况
```php
class Controller extends BaseController
{
use RespondsWithJson;
public function successEmpty()
{
return $this->success();
}
public function successWithData()
{
return $this->success(['Hello']);
}
public function successWithPagination()
{
return $this->success(User::active()->paginate());
}
public function errorDefault()
{
return $this->error();
}
public function errorCustomMessage()
{
return $this->error('自定义错误信息');
}
public function unauthorized()
{
return $this->deny('登录信息已失效, 请重新登陆!');
}
}
```
## 自定义状态码以及扩展字段
在 `AppServiceProvider@boot` 方法中添加如下代码
```php
use Mitoop\Http\JsonResponderDefault;
app(JsonResponderDefault::class)->apply([
'success' => 0,
'error' => 1,
'deny' => -1,
'extra' => [
'request_id' => app('request_id'),
],
]);
```
## API 资源
支持 API 资源, `只需要`改下继承关系, 其他不需要任何改变
Tips: 更改下系统默认的 `stub`, 每次直接生成好继承关系
#### 普通资源继承 `Mitoop\Http\Resources\Resource`
```php
use Illuminate\Http\Request;
use Mitoop\Http\Resources\Resource;
class LoraResource extends Resource
{
public function toArray(Request $request): array
{
return [
'id' => $this->id,
'name' => $this->name,
];
}
}
```
#### 资源集合继承 `Mitoop\Http\Resources\ResourceCollection`
```php
use Mitoop\Http\Resources\ResourceCollection;
class LoraCollection extends ResourceCollection
{
}
```
#### 和原来一样，直接返回资源对象，自动应用统一响应格式
```php
class Controller extends BaseController
{
public function show()
{
// 直接返回标准化的 API Resource
return new LoraResource(Lora::find(1));
}
}
```
## 异常
已定制异常处理器，开发者只需少量配置即可实现统一格式化输出，同时支持完全自定义异常逻辑。
1. 在 `AppServiceProvider` 类中添加如下代码
```php
use Illuminate\Contracts\Debug\ExceptionHandler;
use Mitoop\Http\Exceptions\Handler;
public $singletons = [
ExceptionHandler::class => Handler::class,
];
```
2. 在 `bootstrap/app.php` 中添加如下代码
```php
use Illuminate\Foundation\Configuration\Exceptions;
->withExceptions(function (Exceptions $exceptions) {
// 只需要根据需求配置异常映射
// 其他异常由统一 Handler 接管，无需单独处理
$exceptions->map(JWTException::class, fn ($e) => new AuthenticationException);
})
```
## License
MIT