dragon-code/api-response

此包已被废弃，不再维护。未建议替代包。

用于标准化基于Symfony应用程序API响应的包。

维护者

详细信息

github.com/TheDragonCode/api-response

源代码

问题

资助包维护！
TheDragonCode
Open Collective
Boosty
Yoomoney

安装量: 1,643

依赖项: 0

建议者: 0

安全: 0

星级: 38

关注者: 1

分支: 0

开放问题: 2

v10.0.0 2022-04-20 23:50 UTC

Requires

Requires (Dev)

Conflicts

MIT 83f053d9ca8a0fb6df20ea86dbf24cf610ab09e6

  • Andrey Helldar <helldar.woop@ai-rus.com>

symfonyapiresponselaravelapi responselumenapi-responsedragondragon-code

This package is auto-updated.

Last update: 2023-02-14 21:12:46 UTC

README

API Response

Stable Version Unstable Version Total Downloads License

用于标准化基于 Symfony 的应用程序API响应的包。

入门

升级指南

[ 回到顶部 ]

安装

要获取最新版本的 API Response，只需使用 Composer 需求项目

$ composer require dragon-code/api-response

此命令将自动为您当前环境安装最新版本的包。

当然，您也可以手动更新您的 require 块并运行 composer update，如果愿意的话

{
    "require": {
        "dragon-code/api-response": "^9.1"
    }
}

好了！使用 api_response() 辅助函数。

兼容性表

包版本 PHP最小版本 Symfony版本 支持 链接
^9.0 7.2.5 ^4.0, ^5.0, ^6.0 Supported 升级指南
^8.0 7.2.5 ^4.0, ^5.0 Not Supported 升级指南
^7.0 7.2.5 ^4.0, ^5.0 Not Supported 升级指南
^6.0 7.3 ^4.0, ^5.0 Not Supported 升级指南
^5.0 7.1.3 ^4.0, ^5.0 Not Supported ---
^4.4.1 5.6.9 ^3.0, ^4.0, ^5.0 Not Supported ---
^4.0 5.6.9 ^3.0, ^4.0 Not Supported ---

[ 回到顶部 ]

使用方法

使用 data 键

使用代码作为 NULL

// php 7.4 and below
return api_response(null, 304);

// php 8.0
return api_response( status_code: 304 );

返回代码 304

{
    "data": null
}

[ 回到顶部 ]

使用默认代码作为整数

return api_response(304);

返回代码 200

{
    "data": 304
}

[ 回到顶部 ]

使用默认代码作为字符串

return api_response('qwerty');

返回代码 200

{
    "data": "qwerty"
}

[ 回到顶部 ]

使用代码作为字符串

return api_response('qwerty', 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "qwerty"
    }
}

[ 回到顶部 ]

使用代码作为整数

return api_response(304, 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": 304
    }
}

[ 回到顶部 ]

作为数组

$data = [
    [
        'title' => 'Title #1',
        'description' => 'Description #1',
    ],
    [
        'title' => 'Title #2',
        'description' => 'Description #2',
    ],
];

[ 回到顶部 ]

作为错误

return api_response($data, 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": [
            {
                "title": "Title #1",
                "description": "Description #1"
            },
            {
                "title": "Title #2",
                "description": "Description #2"
            }
        ]
    }
}

[ 回到顶部 ]

作为成功

return api_response($data);

返回代码 200

{
    "data": [
        {
            "title": "Title #1",
            "description": "Description #1"
        },
        {
            "title": "Title #2",
            "description": "Description #2"
        }
    ]
}

如果第一个参数是数字，则将按代码解密错误并返回。在其他情况下，将返回传递变量的值。

[ 回到顶部 ]

包含附加内容

// php 7.4 and below
return api_response('title', 200, ['foo' => 'bar']);
// or
return api_response('title', null, ['foo' => 'bar']);

// php 8.0
return api_response('title', with: ['foo' => 'bar']);

返回代码 200

{
    "data": "title",
    "foo": "bar"
}

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "ok"
    },
    "foo": "bar"
}
return api_response(['data' => 'foo', 'bar' => 'baz']);

返回代码 200

{
    "data": "foo",
    "bar": "baz"
}

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "foo"
    },
    "bar": "baz"
}

[ 回到顶部 ]

使用时不包含 data 键

由于该包的目标是统一所有答案，我们将变量定义移动到了静态函数中。因此，例如，要启用或禁用 data 键中的内容包装，您需要调用 wrapped 或 withoutWrap 方法

use DragonCode\ApiResponse\Services\Response;

Response::withoutWrap();

使用代码和不含 data 键表示为 NULL

// php 7.4 and below
return api_response(null, 304);

// php 8.0
return api_response( status_code: 304 );

返回代码 304

[]

[ 回到顶部 ]

使用默认代码和不含 data 键表示为整数

return api_response(304, 200);

返回代码 200

304

[ 回到顶部 ]

使用默认代码和不含 data 键表示为字符串

return api_response('qwerty', 200);

返回代码 200

"qwerty"

[ 回到顶部 ]

使用代码和不含 data 键表示为字符串

return api_response('qwerty', 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "qwerty"
    }
}

[ 回到顶部 ]

使用代码和不含 data 键表示为整数

return api_response(304, 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": 304
    }
}

[ 回到顶部 ]

使用数组且不含 data 键

$data = [
    [
        'title' => 'Title #1',
        'description' => 'Description #1',
    ],
    [
        'title' => 'Title #2',
        'description' => 'Description #2',
    ],
];

使用错误信息且不含 data 键

return api_response($data, 400);

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": [
            {
                "title": "Title #1",
                "description": "Description #1"
            },
            {
                "title": "Title #2",
                "description": "Description #2"
            }
        ]
    }
}

[ 回到顶部 ]

使用成功信息且不含 data 键

return api_response($data, 200);
// or
return api_response($data);

返回代码 200

[
    {
        "title": "Title #1",
        "description": "Description #1"
    },
    {
        "title": "Title #2",
        "description": "Description #2"
    }
]

如果第一个参数是数字，则将按代码解密错误并返回。在其他情况下，将返回传递变量的值。

[ 回到顶部 ]

包含附加内容且不含 data 键

// php 7.4 and below
return api_response('title', 200, ['foo' => 'bar']);

// php 8.0
return api_response('title', with: ['foo' => 'bar']);

返回代码 200

{
    "data": "title",
    "foo": "bar"
}

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "ok"
    },
    "foo": "bar"
}
return api_response(['data' => 'foo', 'bar' => 'baz']);

返回代码 200

{
    "data": "foo",
    "bar": "baz"
}

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "foo"
    },
    "bar": "baz"
}

[ 回到顶部 ]

无额外数据

在某些情况下，返回答案时，您还必须提供额外的数据。例如堆栈跟踪。

为了防止这些数据出现在生产环境的响应中，您可以全局设置一个标签来显示或隐藏这些数据

use DragonCode\ApiResponse\Services\Response;

env('APP_DEBUG')
    ? Response::allowWith()
    : Response::withoutWith();

现在所有响应将不会包含传递的额外数据。

例如

// php 7.4 and below
return api_response('title', 200, ['foo' => 'bar']);
// or
return api_response('title', null, ['foo' => 'bar']);

// php 8.0
return api_response('title', with: ['foo' => 'bar']);

返回代码 200

{
    "data": "title"
}

返回代码 400

{
    "error": {
        "type": "Exception",
        "data": "ok"
    }
}

服务器错误

注意：$with 参数还负责显示服务器端错误消息。

在这种情况下，Http 错误将直接显示，而不进行掩码。

例如

use DragonCode\ApiResponse\Services\Response;

Response::allowWith();

$e = new Exception('Foo', 0);

return api_response($e);

返回代码 500

{
    "error": {
        "type": "Exception",
        "data": "Foo"
    }
}

和

use DragonCode\ApiResponse\Services\Response;

Response::withoutWith();

$e = new Exception('Foo', 0);

return api_response($e);

返回代码 500

{
    "error": {
        "type": "Exception",
        "data": "Whoops! Something went wrong."
    }
}

如果代码 >=400 且 < 500，则返回

{
    "error": {
        "type": "Exception",
        "data": "Foo"
    }
}

[ 回到顶部 ]

返回异常实例

class FooException extends \Exception
{
    public function __construct()
    {
        parent::__construct('Foo', 405);
    }
}

class BarException extends \Exception
{
    public function __construct()
    {
        parent::__construct('Bar');
    }
}

$foo = new FooException();
$bar = new BarException();
return api_response($foo);

返回代码 405

{
    "error": {
        "type": "FooException",
        "data": "Foo"
    }
}
return api_response($foo, 408);

返回代码 408

{
    "error": {
        "type": "FooException",
        "data": "Foo"
    }
}
return api_response($bar);

返回代码 400

{
    "error": {
        "type": "BarException",
        "data": "Bar"
    }
}
return api_response($bar, 408);

返回代码 408

{
    "error": {
        "type": "BarException",
        "data": "Bar"
    }
}

您还可以添加额外的数据

return api_response($foo, 405, ['foo' => 'Bar']);
// or
return api_response($foo, 0, ['foo' => 'Bar']);

返回代码 405

{
    "error": {
        "type": "FooException",
        "data": "Foo"
    },
    "foo": "Bar"
}

[ 回到顶部 ]

在 Laravel 和 Lumen 框架中的最佳实践使用

如果您使用 Laravel 或 Lumen 框架，则可以根据您的应用程序版本和需求更新 app\Exceptions\Handler.php 文件中的 extends

版本 \ 类型 API + WEB 仅 API
9.x DragonCode\ApiResponse\Exceptions\Laravel\Nine\Handler as ExceptionHandler DragonCode\ApiResponse\Exceptions\Laravel\Nine\ApiHandler as ExceptionHandler
8.x DragonCode\ApiResponse\Exceptions\Laravel\Eight\Handler as ExceptionHandler DragonCode\ApiResponse\Exceptions\Laravel\Eight\ApiHandler as ExceptionHandler
7.x DragonCode ApiService 异常处理类 ExceptionHandler DragonCode ApiService 异常处理类 ApiHandler as ExceptionHandler

如果你没有向此文件添加任何内容，那么请删除所有属性和方法。

例如，结果是一个干净的文件，看起来像这样

<?php

namespace App\Exceptions;

use DragonCode\ApiResponse\Exceptions\Laravel\Nine\Handler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    //
}

更多示例

<?php

namespace App\Exceptions;

// use DragonCode\ApiResponse\Exceptions\Laravel\Nine\Handler as ExceptionHandler;
use DragonCode\ApiResponse\Exceptions\Laravel\Nine\ApiHandler as ExceptionHandler;

// use DragonCode\ApiResponse\Exceptions\Laravel\Eight\Handler as ExceptionHandler;
// use DragonCode\ApiResponse\Exceptions\Laravel\Eight\ApiHandler as ExceptionHandler;

// use DragonCode\ApiResponse\Exceptions\Laravel\Seven\Handler as ExceptionHandler;
// use DragonCode\ApiResponse\Exceptions\Laravel\Seven\ApiHandler as ExceptionHandler;

class Handler extends ExceptionHandler
{
    //
}

[ 回到顶部 ]

JSON 资源

现在，如果你传递一个资源对象或验证器对象，它也将被精美地渲染

use Illuminate\Http\Resources\Json\JsonResource;

/** @mixin \Tests\Fixtures\Laravel\Model */
final class Resource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'foo' => $this->foo,
            'bar' => $this->bar,
        ];
    }

    public function with($request)
    {
        return ['baz' => 'Baz'];
    }
}
$model = Model::first();
$resource = MyResource::make($model);

return api_response($resource);

返回代码 200

{
    "data": {
        "foo": "Foo",
        "bar": "Bar"
    },
    "baz": "Baz"
}

如果 Response::withoutWrap()

{
    "foo": "Foo",
    "bar": "Bar",
    "baz": "Baz"
}

如果 Response::withoutWith()

{
    "data": {
        "foo": "Foo",
        "bar": "Bar"
    }
}

如果 Response::withoutWith() 和 Response::withoutWrap()

{
    "foo": "Foo",
    "bar": "Bar"
}

[ 回到顶部 ]

验证

$data = [
    'foo' => 'Foo',
    'bar' => 123,
    'baz' => 'https://foo.example'
];

$rules = [
    'foo' => ['required'],
    'bar' => ['integer'],
    'baz' => ['sometimes', 'url'],
];
$validator = Validator::make($data, $rules);

return $validator->fails()
    ? new ValidationException($validator)
    : $validator->validated();

如果成功

{
    "data": {
        "foo": "Foo",
        "bar": 123,
        "baz": "https://foo.example"
    }
}

如果失败

{
    "error": {
        "type": "ValidationException",
        "data": {
            "foo": ["The foo field is required."],
            "bar": ["The bar must be an integer."],
            "baz": ["The baz format is invalid."]
        }
    }
}

[ 回到顶部 ]

许可证

此软件包采用MIT 许可证授权。

[ 回到顶部 ]