README

使用Laravel API Response Builder简化您的API响应！ 此包帮助您轻松创建JSON和XML格式的结构化API响应。它提供可定制的状态码、消息和数据处理，是一个适用于管理API响应的灵活工具，包括错误处理、日志记录和广泛的配置选项。

📚 目录

🔍 使用方法
常用方法和其简要描述的概述。

特性
要求
安装
翻译
技术
概念与模式
文档
链接
贡献
许可证
联系

🚀 特性

结构化响应： 无需费力即可轻松创建一致的JSON和XML响应。
可定制的状态码与消息： 适应响应以符合您的需求。
错误处理与日志记录： 详细记录响应和请求。
灵活配置： 调整数据包装、响应语言等设置。

⚙️ 要求

在使用此包之前，请确保您的项目满足以下要求

Laravel框架： 版本8.12或更高。
PHP： 版本7.3或更高。
Composer： PHP依赖管理器。

具备这些特性后，让我们深入了解安装过程！

📦 安装

要将Laravel API Response Builder集成到您的Laravel项目中，请按照以下步骤操作

通过Composer安装

在您的终端中运行以下命令

composer require danilowa/laravel-api-response-builder

发布配置（可选）

安装后，发布配置文件

php artisan vendor:publish --provider="Danilowa\LaravelResponseBuilder\Providers\ResponseBuilderServiceProvider"

这将创建一个位于 config/responsebuilder.php 的配置文件，您可以在其中自定义包设置。

配置

打开 config/responsebuilder.php 文件，并根据项目需求调整设置。配置选项包括数据包装器、API密钥头和日志记录偏好设置。

配置就绪后，您的包即可使用！

🌍 翻译

Laravel API Response Builder 支持多种语言进行API响应。默认情况下，它包括英语（en）和巴西葡萄牙语（pt_BR）。要使用项目中的翻译，请按照以下步骤操作

发布翻译文件（可选）

如果您希望自定义或添加新语言，可以通过运行以下命令将翻译文件发布到项目中

php artisan vendor:publish --tag=lang

这将创建一个resources/lang/vendor/responsebuilder目录，您可以在其中修改或添加新的翻译文件（例如，es，fr）。

使用现有翻译文件

如果您不需要自定义翻译，该包将自动使用来自vendor/danilowa/laravel-api-response-builder/resources/lang目录的默认语言文件。

🧰 技术栈

Laravel API Response Builder利用以下技术

Laravel 框架：一个用于Web应用程序的PHP框架。
PHP：服务器端脚本语言。
JSON：API响应的数据格式。
XML：API响应的数据格式（目前处于开发中）。
日志：用于记录响应细节的Laravel日志功能。

📚 概念与模式

Laravel API Response Builder包集成了多个高级概念和模式，旨在增强API响应管理

响应包装：该模式将您的响应数据包装在统一格式中，确保所有API响应的一致性。它包括可自定义的数据包装器，可以通过config/responsebuilder.php配置文件进行调整。这种方法简化了响应处理，并为成功和错误响应提供了清晰的架构。
详细日志记录：该包提供了对响应和请求的全面日志记录功能。使用Laravel内置的日志功能，它捕获关键细节，如响应状态、头和内容。此功能支持各种日志级别，并允许您指定日志文件路径，以便有效地调试和监控您的API交互。

示例：您可以在配置文件下的logging.channels中指定的日志文件中查看响应日志。例如，状态码为500的响应将被记录为错误，帮助您跟踪和调试关键问题。
灵活的配置管理：利用Laravel的配置系统，该包提供了广泛的自定义响应结构的选项。您可以轻松配置数据包装器、API密钥头、默认状态码和响应语言。这种灵活性允许您根据项目的特定需求调整包的行为。
标准化的错误处理：该包标准化了错误消息和状态生成的方式。它提供了一致的错误响应方法，便于故障排除并改善了用户体验。配置选项可用于调整错误消息格式和响应代码，确保错误处理符合您的应用程序要求。

📝 如何使用

在本节中，我们重点介绍了包中两个最常用的方法（成功和错误），以供快速参考。有关所有可用方法的全面概述和详细说明，包括附加功能和使用场景，请参阅完整文档。

成功 - 返回带有可选数据和默认消息的标准成功响应。
SuccessWithMeta - 返回带有数据和额外元数据的成功响应。
SuccessWithHeaders - 返回带有数据和自定义头部的成功响应。
SuccessWithPagination - 返回带有数据和分页详情的成功响应。
错误 - 返回指定状态码和消息的错误响应。
ErrorWithTrace - 返回带有调试目的额外跟踪的错误响应。
ErrorWithSuggestions - 返回带有解决问题的建议的错误响应。

自定义响应设置

您可以在包配置文件中自定义响应结构和行为。以下是一些关键选项

自定义响应结构：修改默认响应键（status，message，data），以适应您的API需求。

/*
|--------------------------------------------------------------------------
| Custom Response Structure
|--------------------------------------------------------------------------
| Define a custom structure for responses. The example below includes
| 'status', 'message', and 'data', but you can modify these as needed.
|
*/
'custom_response_structure' => [
    'status' => 'status',
    'message' => 'message',
    'data' => 'data',
],

响应数据包装器：启用或禁用在额外的data键中包装响应数据。这有助于保持一致的响应结构。

/*
|--------------------------------------------------------------------------
| Response Data Wrapper
|--------------------------------------------------------------------------
| If enabled, the response data will be wrapped in an additional 'data'
| key. This is useful if you want a consistent structure for all responses.
|
*/
'wrap_data' => true,

响应数据包装键：自定义用于包装响应数据的键。默认键是 data，但您可以根据您的API结构进行更改。

/*
|--------------------------------------------------------------------------
| Response Data Wrapper Key
|--------------------------------------------------------------------------
| This value sets the key used to wrap the response data. By default, it is
| 'data', but you can customize it according to your API structure.
|
*/
'wrap_data_key' => 'items',

这些配置选项允许您根据应用程序的需求调整响应结构，并确保API响应的一致性。

success()

描述

success() 方法返回一个包含成功状态码（200）和成功信息的JSON响应。这有助于在您的API中标准化成功响应。

参数

mixed $data:
- 可选
- 类型： array 或 object
- 描述： 要包含在响应中的数据。这可以是您想返回给客户端的任何数据结构。
- 示例： ['user' => $user] 或 new User($userId)。
string|null $message:
- 可选
- 类型： string 或 null
- 描述： 要包含在响应中的成功信息。如果不提供，将使用默认信息。此参数为可选。
- 示例： 'User fetched successfully.' 或 null。
bool|null $wrap:
- 可选
- 类型： bool 或 null
- 描述： 确定是否将数据包装在包装对象中。如果为 true，则数据将根据配置进行包装。如果为 false，则不应用包装。如果为 null，则包装行为将遵循默认配置设置。此参数为可选。
- 示例： true | false 或 null。
string|null $wrapKey:
- 可选
- 类型： string 或 null
- 描述： 包装数据的键。如果指定，则数据将根据此键进行包装。如果不提供，则使用配置中的默认键。此参数为可选。
- 示例： 'items' 或 null。
int $statusCode:
- 可选
- 类型： int
- 描述： 响应的HTTP状态码。默认为 200，但如有需要可以更改。
- 示例： 200（表示成功请求）。

IlluminateJsonResponse：包含提供数据和信息的JSON响应对象。

使用示例

默认成功响应

$response = JsonResponse::success();

描述： 返回包含用户数据和默认成功信息的JSON响应。

示例输出

{
  "status": "success",
  "message": "Operation completed successfully.",
  "data": null
}

基本成功响应

$response = JsonResponse::success(['user' => $user]);

描述： 返回包含用户数据和默认成功信息的JSON响应。

示例输出

{
  "status": "success",
  "message": "Operation successful.",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}

包含自定义信息的成功响应

$response = JsonResponse::success(['user' => $user], 'User fetched successfully.');

描述： 返回包含用户数据和自定义成功信息的JSON响应。

示例输出

{
  "status": "success",
  "message": "User fetched successfully.",
  "data": {
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "john.doe@example.com"
    }
  }
}

包含包装的成功响应

$response = JsonResponse::success(['user' => $user], 'User fetched successfully.', true);

描述： 返回默认将用户数据包装在键 'items' 下并包含自定义成功信息的JSON响应。

示例输出

{
  "status": "success",
  "message": "User fetched successfully.",
  "data": {
    "items": {
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  }
}

包含自定义包装键的成功响应

$response = JsonResponse::success(['user' => $user], 'User fetched successfully.', true, 'customWrap');

描述： 返回将用户数据包装在自定义键 'customWrap' 下并包含自定义成功信息的JSON响应。

示例输出

{
  "status": "success",
  "message": "User fetched successfully.",
  "data": {
    "customWrap": {
      "user": {
        "id": 1,
        "name": "John Doe",
        "email": "john.doe@example.com"
      }
    }
  }
}

`error()`

描述

error() 方法返回包含错误状态码和错误信息的JSON响应。这有助于在您的API中标准化错误响应。

参数

int $statusCode:
- 必需
- 类型： int
- 描述： 指示错误类型的HTTP状态码（例如，400表示错误请求，404表示未找到，500表示内部服务器错误）。
- 示例： 404。
string|null $message:
- 可选
- 类型： string 或 null
- 描述： 要包含在响应中的错误信息。如果不提供，将使用默认错误信息。此参数为可选。
- 示例： 'Resource not found.' 或 null。
mixed $data:
- 可选
- 类型： array 或 object 或 null
- 描述： 要包含在响应中的数据。这可以用于提供有关错误的额外信息（例如，验证错误）。如果不提供，则不包含任何额外数据。此参数为可选。
- 示例: ['field' => 'username', 'error' => 'Username is required.'] 或 null。
bool|null $wrap:
- 可选
- 类型： bool 或 null
- 描述: 决定是否将错误数据包裹在包装对象中。如果 true，数据将根据配置进行包装。如果 false，则不进行包装。如果 null，则包装行为将遵循默认配置设置。此参数是可选的。
- 示例: true | false 或 null。
string|null $wrapKey:
- 可选
- 类型： string 或 null
- 描述: 包装错误数据的键。如果指定，数据将在这个键下进行包装。如果没有提供，则使用配置中的默认键。此参数是可选的。
- 示例: 'error' 或 null。

IlluminateJsonResponse: 包含提供的状态码、消息和数据的一个JSON响应对象。

使用示例

默认错误响应

$response = JsonResponse::error(404);

描述: 返回一个具有 404 状态码和默认错误消息的JSON响应。

示例输出

{
  "status": "error",
  "message": "The requested resource could not be found.",
  "data": null
}

基本错误响应

$response = JsonResponse::error(404, 'Resource not found.');

描述: 返回一个具有 404 状态码和默认错误消息的JSON响应。

示例输出

{
  "status": "error",
  "message": "Resource not found.",
  "data": null
}

带自定义消息和数据的错误响应

$response = JsonResponse::error(400, 'Bad request', ['field' => 'username', 'error' => 'Username is required.']);

描述: 返回一个具有 400 状态码、自定义错误消息以及描述验证错误的附加数据的JSON响应。

示例输出

{
  "status": "error",
  "message": "Bad request",
  "data": {
    "field": "username",
    "error": "Username is required."
  }
}

带包装的错误响应

$response = JsonResponse::error(500, 'Internal server error', null, true);

描述: 返回一个具有 500 状态码，并且默认情况下错误数据在键 'items' 下进行包装的JSON响应。

示例输出

{
  "status": "error",
  "message": "Internal server error",
  "data": {
    "items": null
  }
}

带自定义包装键的错误响应

$response = JsonResponse::error(500, 'Internal server error', null, true, 'error');

描述: 返回一个具有 500 状态码，并且错误数据在自定义键 'error' 下进行包装的JSON响应。

示例输出

{
  "status": "error",
  "message": "Internal server error",
  "data": {
    "error": null
  }
}

🌐 文档

JSON响应

成功 - 描述 | 示例
SuccessWithMeta - 描述 | 示例
SuccessWithHeaders - 描述 | 示例
SuccessWithPagination - 描述 | 示例
错误 - 描述 | 示例
ErrorWithTrace - 描述 | 示例
ErrorWithSuggestions - 描述 | 示例

配置

自定义响应结构 - 详情 - 数据包装器 - API密钥头 - 响应语言 - 默认状态码 - JSON选项
日志 - 详情 - 记录响应 - 请求记录 - 响应时间记录 - 记录级别 - 日志文件路径

🔗 链接

🤝 贡献

您可以通过分支仓库并提交拉取请求来做出贡献。

📝 许可证

此软件包根据MIT许可证授权。

📬 联系

对于任何问题或反馈，请通过以下方式联系

Danilo Oliveira: daniloworkdev@gmail.com
网站: daniloo.dev

注意：此软件包目前正在开发中，XML支持仍在进行中。作为一个早期发布版本，可能存在错误或不完整的功能。我们感谢您的耐心和反馈。

danilowa / laravel-api-response-builder

维护者

详情

README

📚 目录

🚀 特性

⚙️ 要求

📦 安装

🌍 翻译

🧰 技术栈

📚 概念与模式

📝 如何使用

自定义响应设置

success()

`error()`

🌐 文档

JSON响应

配置

🔗 链接

🤝 贡献

📝 许可证

📬 联系