PHPackages                             zhkugh/laravel-api-response - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. zhkugh/laravel-api-response

ActiveLibrary[HTTP & Networking](/categories/http)

zhkugh/laravel-api-response
===========================

A pluggable Laravel package for unified REST API responses with Response Macros and exception handling

v1.0.0(5mo ago)08MITPHPPHP ^8.2CI failing

Since Jan 19Pushed 5mo agoCompare

[ Source](https://github.com/zhkugh/laravel-api-response)[ Packagist](https://packagist.org/packages/zhkugh/laravel-api-response)[ RSS](/packages/zhkugh-laravel-api-response/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (6)Versions (2)Used By (0)

Laravel API Response
====================

[](#laravel-api-response)

一个可插拔、可扩展的 Laravel REST API 响应宏包，提供统一的响应格式和异常处理。

[![Latest Version on Packagist](https://camo.githubusercontent.com/eada56d174da975f87af5f665f81dbeb20cd1804c9ab64c70999df3199af19d8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a686b7567682f6c61726176656c2d6170692d726573706f6e73652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/zhkugh/laravel-api-response)

特性
--

[](#特性)

- ✅ **全局可用**：无需继承或引入，直接使用 `response()->success()` 或 `Response::success()`
- ✅ **代码简洁**：提供丰富的响应宏方法
- ✅ **统一格式**：异常和正常响应格式一致
- ✅ **符合 Laravel 最佳实践**：使用 Response Macro 和 Service Provider
- ✅ **可插拔**：通过 Composer 安装即可使用
- ✅ **可扩展**：支持自定义异常处理器和消息
- ✅ **高性能**：优化的配置读取和异常处理逻辑
- ✅ **类型安全**：完整的类型声明和 PHPDoc 注释
- ✅ **常量支持**：提供 `HttpStatusCode` 常量类

要求
--

[](#要求)

- PHP >= 8.2
- Laravel >= 12.0

安装
--

[](#安装)

通过 Composer 安装：

```
composer require zhkugh/laravel-api-response
```

包会自动注册服务提供者，无需手动配置。

配置
--

[](#配置)

发布配置文件（可选）：

```
php artisan vendor:publish --tag=api-response-config
```

配置文件位置：`config/api-response.php`

使用
--

[](#使用)

### 基本用法

[](#基本用法)

#### 成功响应

[](#成功响应)

```
// 使用 response() 辅助函数
return response()->success($data);
return response()->success($data, '操作成功');
return response()->success($data, '操作成功', 200);

// 使用 Response Facade
use Illuminate\Support\Facades\Response;
return Response::success($data);
```

#### 错误响应

[](#错误响应)

```
return response()->error('操作失败');
return response()->error('操作失败', 400);
return response()->error('操作失败', 400, $errors);
```

#### 分页响应

[](#分页响应)

```
$users = User::paginate(15);
return response()->paginated($users);
return response()->paginated($users, '获取用户列表成功');
```

#### 快捷方法

[](#快捷方法)

```
// 创建成功 (201)
return response()->created($data);
return response()->created($data, '创建成功');

// 更新成功 (200)
return response()->updated($data);
return response()->updated($data, '更新成功');

// 删除成功 (200)
return response()->deleted();
return response()->deleted('删除成功');

// 未找到 (404)
return response()->notFound();
return response()->notFound('资源未找到');

// 未授权 (401)
return response()->unauthorized();
return response()->unauthorized('未授权访问');

// 禁止访问 (403)
return response()->forbidden();
return response()->forbidden('禁止访问');

// 验证失败 (422)
return response()->validationError($errors);
return response()->validationError($errors, '验证失败');
```

### 异常处理

[](#异常处理)

在 `bootstrap/app.php` 中注册异常处理器：

```
use Zhkugh\LaravelApiResponse\ExceptionHandler;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions): void {
        $exceptions->render(function (\Throwable $e, $request) {
            return ExceptionHandler::render($e, $request);
        });
    })->create();
```

### 自定义异常处理器

[](#自定义异常处理器)

在 `config/api-response.php` 中配置：

```
'custom_handlers' => [
    \App\Exceptions\CustomException::class => function ($e, $request) {
        return response()->error('自定义错误消息', 400);
    },
    \Stancl\Tenancy\Exceptions\TenantCouldNotBeIdentifiedByPathException::class => function ($e, $request) {
        return response()->error('租户未找到', 404);
    },
],
```

或者在服务提供者中动态注册：

```
use Zhkugh\LaravelApiResponse\ExceptionHandler;

ExceptionHandler::registerCustomHandlers([
    \App\Exceptions\CustomException::class => function ($e, $request) {
        return response()->error('自定义错误', 400);
    },
]);
```

响应格式
----

[](#响应格式)

### 成功响应

[](#成功响应-1)

```
{
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
        "id": 1,
        "name": "示例"
    }
}
```

### 错误响应

[](#错误响应-1)

```
{
    "success": false,
    "code": 400,
    "message": "操作失败",
    "errors": {
        "email": ["邮箱格式不正确"]
    }
}
```

### 分页响应

[](#分页响应-1)

```
{
    "success": true,
    "code": 200,
    "message": "获取成功",
    "data": [
        {
            "id": 1,
            "name": "示例"
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 15,
        "total": 150,
        "from": 1,
        "to": 15
    }
}
```

控制器示例
-----

[](#控制器示例)

```