README

LARAPI

使用 Laravel 创建的具有意见的 API 框架

配置项目

composer create-project --prefer-dist wendelladriel/larapi my-app && cd my-app && sh ./tools/configure.sh

这将

• 创建项目
• 安装依赖项
• 将 .env.example 复制到项目根目录下的 .env；
• 生成 APP_KEY
• 生成 JWT_SECRET
• 配置项目的 Git 钩；

根据需要更新您的 .env 文件；

运行迁移和种子文件

php artisan migrate && php artisan db:seed

配置您的本地虚拟主机。之后访问主机 URL，您将看到如下 JSON 响应

{
    "application": "LarAPI",
    "environment": "local",
    "status": 200
}

应用架构

在 app 文件夹内只存放其他文件夹，根目录不允许有文件。基本架构由四个主要文件夹组成

Core：仅放置基本架构文件

• 异常处理程序和自定义异常；
• 内核文件；
• 提供者；
• 中间件；
• 基础文件，如 BaseController 和 BaseRepository；

Models：所有应用程序 Model 类都放置在此处，但目录根不允许有类。所有模型都应放入一个根据其目的的命名空间中，除此之外，还有两个其他文件夹

• 模型特定特质；
• 自定义关系类；

Repositories：所有应用程序 Repository 类都放置在此处，但目录根不允许有类。所有仓库都应放入一个根据其目的的命名空间中，除此之外，还有一个 Traits 文件夹用于仓库特定特质。如果您为特定的 Model 类创建仓库，请使用您为 Model 类提供的相同命名空间，例如 Models\Auth\User 仓库 必须 是 Repositories\Auth\UserRepository。 始终 放置后缀 Repository。所有仓库 必须 扩展 LarAPI\Core\Repositories\BaseRepository；

Modules：所有应用程序模块都放置在此处，例如 Auth 模块。目录根不允许有类。

通用模块：这是一个 模块文件夹（所有模块文件夹 必须 具有相同的文件夹和文件结构）。此模块是为了创建 仅 包含通用和通用目的类的模块

• 命令：此模块的命令文件；
• 控制器：此模块的控制器文件。 不要 使用复数形式，并且 始终 放置后缀 Controller。例如：UserController，ProductController。所有控制器 必须 扩展 LarAPI\Core\Http\BaseController；
• 事件：此模块的事件文件。尽量使用动词作为名称，并且 始终 放置后缀 Event。例如：ActivateUserEvent；
• 监听器：此模块的监听器文件。尽量使用名词作为名称，并且 始终 放置后缀 Listener。例如：对于 ActivateUserEvent 使用 UserActivatedListener；
• 请求：此模块的自定义请求文件。尽量使用动词作为名称，并且 始终 放置后缀 Request。例如：ActivateUserRequest。所有请求 必须 扩展 LarAPI\Core\Http\BaseRequest；
• 响应：本模块的自定义响应文件。尽量使用名词命名，并且始终使用后缀 Response。例如：UserActivatedResponse;
• 路由：本模块的路由文件。每个文件都是API的一个版本。遵循格式：v1.php、v2.php 等；
• 服务：本模块的服务文件。 始终使用后缀 Service；
• 支持：本模块的辅助文件；
• 特质：本模块的特质文件；

当你在 app/Modules 文件夹中创建一个新的 模块 时，将模块名称添加到 config/modules.php 文件中。此配置文件还用于在您的API中启用和禁用模块。列出的模块将被启用。

创建计划命令

将在 Console/Kernel 上计划的所有命令必须从 LarAPI\Core\Console\ApiTaskCommand 扩展；

在计划命令时，所有命令必须使用 ->runInBackground(); 方法进行计划；

功能

API 文档

LarAPI 使用 Swagger 为您的API提供API文档。您可以通过访问 HOST_URL/swagger 来检查API文档。

认证

LarAPI 提供了开箱即用的 JWT 认证、用户设置 和 用户角色。您可以在API的 Swagger 文档 中检查默认的认证端点。

控制器

LarAPI\Core\Http\BaseController 类提供了三个用于从API返回数据的辅助方法

• apiSimpleSuccessResponse(int $code = Response::HTTP_CREATED): JsonResponse

• apiSuccessResponse($data, int $code = Response::HTTP_OK): JsonResponse

• apiErrorResponse(string $message, Throwable $exception = null, $code = Response::HTTP_INTERNAL_SERVER_ERROR): JsonResponse

DTOs

LarAPI 提供了两个通用的DTO类，这些类对于数据表请求非常有用。查看 LarAPI\Modules\Common\Support\DTOs\CommonTableDTO 和 LarAPI\Modules\Common\Support\DTOs\DateRangeDTO

异常

LarAPI 提供了一个配置好的异常处理器，该处理器将只返回JSON响应，并提供一个基接口，供您识别将被自定义异常处理器处理的自定义异常。它还提供了一个自定义异常示例。

格式化器

LarAPI\Modules\Common\Support\Formatter 类提供了许多用于格式化数据和用于在代码中使用的辅助常数的函数。

Git 插件

该项目有一些Git插件，用于使用 Swagger 更新API文档、使用 PHP-CS-FIXER 检查PHP代码以及使用 PHPUnit 运行测试。

健康检查路由

LarAPI 提供了一个健康检查路由，如果您需要检查API是否处于运行状态。

模块管理

您可以使用以下命令在您的API中创建一个新的模块

php artisan make:module test

使用 config/modules.php 文件，您可以启用和禁用API的模块。

请求

LarAPI 提供了两个通用的请求类，这些类对于数据表请求非常有用。查看 LarAPI\Modules\Common\Requests\CommonTableRequest 和 LarAPI\Modules\Common\Requests\DateRangeRequest

仓库

LarAPI\Core\Repositories\BaseRepository 类提供了一些通用的目的利用函数，因此您不需要浪费时间去创建简单的查询函数

计划命令管理器

LarAPI 提供了一个自定义的计划命令管理器，这将帮助您防止运行重叠，并使调试计划命令更容易。查看以下类： LarAPI\Core\Console\ApiTaskCommand、LarAPI\Models\Common\ApiTask 和 LarAPI\Repositories\Common\ApiTaskRepository。

Slack 集成

LarAPI\Modules\Common\Services\SlackClient 类提供了一种简单的方法来向 Slack 发送通知。要启用此集成，您需要提供 SLACK_NOTIFICATIONS_WEBHOOK 环境变量。

致谢

• 文德尔·阿德里亚尔
• 所有贡献者

特别感谢Caneco为我们的标志✨