zhkugh/laravel-api-response

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

v1.0.0 2026-01-19 03:09 UTC

Requires

• php: ^8.2
• illuminate/http: ^12.0
• illuminate/support: ^12.0
• illuminate/validation: ^12.0

Requires (Dev)

• laravel/pint: ^1.24
• pestphp/pest: ^4.3
• pestphp/pest-plugin-laravel: ^4.0

MIT

• Zhkugh

• json
• rest
• api
• response
• laravel
• macro
• exception-handling
• unified-response

README

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

特性

• ✅ 全局可用：无需继承或引入，直接使用 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);
    },
]);

响应格式

成功响应

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

错误响应

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

分页响应

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

控制器示例

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function index()
    {
        $users = User::paginate(15);
        return response()->paginated($users);
    }

    public function store(Request $request)
    {
        $user = User::create($request->validated());
        return response()->created($user);
    }

    public function show(User $user)
    {
        return response()->success($user);
    }

    public function update(Request $request, User $user)
    {
        $user->update($request->validated());
        return response()->updated($user);
    }

    public function destroy(User $user)
    {
        $user->delete();
        return response()->deleted();
    }
}

扩展

使用 HTTP 状态码常量

包提供了 HttpStatusCode 常量类，推荐使用常量替代魔法数字：

use Zhkugh\LaravelApiResponse\HttpStatusCode;

return response()->error('错误', HttpStatusCode::BAD_REQUEST);
return response()->success($data, '成功', HttpStatusCode::CREATED);
return response()->error('未授权', HttpStatusCode::UNAUTHORIZED);

添加自定义响应宏

在服务提供者中：

use Illuminate\Support\Facades\Response;
use Zhkugh\LaravelApiResponse\HttpStatusCode;

Response::macro('customSuccess', function ($data) {
    return Response::json([
        'success' => true,
        'data' => $data,
        'timestamp' => now()->toIso8601String(),
    ], HttpStatusCode::OK);
});

IDE 支持

本包提供了 IDE 自动补全支持。详细配置请查看 README_IDE.md。

快速配置（VS Code + Intelephense）

在项目根目录的 .vscode/settings.json 中添加：

{
    "intelephense.stubs": [
        "vendor/zhkugh/laravel-api-response/ide-helper.php"
    ]
}

测试

composer test

贡献

欢迎提交 Issue 和 Pull Request。

许可证

MIT License. 查看 LICENSE 文件了解更多信息。