Laravel API Response

✨ 主要功能

环境需求

安装

composer require mitoop/laravel-api-response

输出格式

{
 "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
}

使用

use Mitoop\Http\RespondsWithJson;
class Controller extends BaseController
{
 use RespondsWithJson;
}

可用方法

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('登录信息已失效, 请重新登陆!');
 }
}

自定义状态码以及扩展字段

use Mitoop\Http\JsonResponderDefault;
app(JsonResponderDefault::class)->apply([
 'success' => 0,
 'error' => 1,
 'deny' => -1,
 'extra' => [
 'request_id' => app('request_id'),
 ],
]);

API 资源

普通资源继承 Mitoop\Http\Resources\Resource

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

use Mitoop\Http\Resources\ResourceCollection;
class LoraCollection extends ResourceCollection
{
}

和原来一样,直接返回资源对象,自动应用统一响应格式

class Controller extends BaseController
{
 public function show()
 {
 // 直接返回标准化的 API Resource
 return new LoraResource(Lora::find(1));
 }
}

异常

 use Illuminate\Contracts\Debug\ExceptionHandler;
 use Mitoop\Http\Exceptions\Handler;
 
 public $singletons = [
 ExceptionHandler::class => Handler::class,
 ];

use Illuminate\Foundation\Configuration\Exceptions;
->withExceptions(function (Exceptions $exceptions) { 
 // 只需要根据需求配置异常映射
 // 其他异常由统一 Handler 接管,无需单独处理
 $exceptions->map(JWTException::class, fn ($e) => new AuthenticationException); 
})

License