README

ExA

Laravel 的有观点模块化 API 框架

功能

您的 API 在 Laravel 和 PHP 的最新版本上运行
带有 PHP、Nginx、MySQL、Redis 和 Mailpit 的 Docker 配置
带有 Swagger 的 API 文档
Laravel Pint 配置（非常具有观点性）
Pest v2 用于测试
类型覆盖率测试，具有 100% 类型覆盖率
基础类以加快开发速度
使用 Laravel Validated DTO 的 DTO
用于通知的 Slack 客户端
模块化结构的 API
JWT 进行认证
具有简单角色系统的开箱即用的用户管理
用户登录和模型上执行的操作的数据库日志
使用 Strictus 强制本地变量类型
默认使用软删除的从 BaseModel 继承的模型
使用 created_by、updated_by 和 deleted_by 字段记录用户执行的操作。在您的迁移中，使用 $table->userActions() 添加这些字段。

使用模板

使用此模板有三种方法

Composer（推荐）

composer create-project --prefer-dist wendelladriel/laravel-exa my-app

GitHub 模板

点击 GitHub 仓库页面上的“使用此模板”按钮。

Git 克隆

git clone git@github.com:WendellAdriel/laravel-exa.git my-app && cd my-app && rm -rf .git

配置应用程序

使用以下命令构建 Docker 服务

make build

运行此命令进行初始应用程序配置

make configure

数据库配置

使用以下命令启动 DB 容器

make db-start

运行迁移

make art ARGS="migrate"

在 database/seeders/DatabaseSeeder.php 文件中更新管理员用户并运行种子

make art ARGS="db:seed"

使用以下命令停止 DB 容器

make db-stop

M1/2 处理器配置

如果您使用的是带有 M1/2 处理器 的 Mac，则需要将 M1_PROCESSOR 环境变量更新为 true

XDebug 配置

默认情况下，将安装 XDebug，如果您想禁用它，请将 XDEBUG_ENABLED 环境变量更新为 false

您还可以通过更新 docker/app/config/xdebug.ini 文件来配置 XDebug

更新服务端口

您可以通过更新 .env 文件中的这些变量来更新服务连接到您的机器的端口

APP_EXTERNAL_PORT
APP_EXTERNAL_PORT_SSL
SWAGGER_EXTERNAL_PORT
DB_EXTERNAL_PORT
REDIS_EXTERNAL_PORT
MAILPIT_EXTERNAL_PORT_SMTP
MAILPIT_EXTERNAL_PORT_HTTP

运行应用程序

运行此命令以启动应用程序

make start

完成后，您可以在以下位置访问应用程序

https://:APP_EXTERNAL_PORT

默认情况下，APP_EXTERNAL_PORT 为 8000

https://:8000

您可以在以下位置检查Swagger文档：

https://:SWAGGER_EXTERNAL_PORT

默认情况下，SWAGGER_EXTERNAL_PORT 的值为 8080

https://:8080

应用程序结构

app 文件夹仅包含默认 Laravel 安装的文件。

exa 文件夹包含此骨架提供的所有基类，以帮助您开发 API。

modules 文件夹包含您的应用程序代码。默认情况下，您有一个 Auth 模块用于 身份验证，以及 开箱即用的用户管理。它还提供了一个通用模块，您可以将其共享逻辑放在应用程序中。

创建模块

要创建新的模块，您可以使用以下命令：

make art ARGS="make:module NAME"

这将在 modules 文件夹中创建一个新的模块，其结构与其他模块相同。默认情况下，该模块将被禁用。要启用它，请将新模块名称添加到 config/modules.php 文件中。

可用命令

要在整个代码库中运行Pint，请使用：

make lint

要运行测试套件，请使用：

make test

使用此命令查看所有可用命令：

make

ExA 类

在 exa 文件夹中，有很多由此骨架提供的类，以帮助您开发 API。

DTOs（数据传输对象）

DatatableDTO - 此 DTO 提供了用于从数据表中获取数据的基本过滤器。
DateRangeDTO - 这是 DatatableDTO 的扩展，提供了额外的日期过滤器参数。

异常

ExaException - 所有自定义异常都应扩展的基本类，以便它可以通过 app/Exceptions/Handler 正确处理。
AccessDeniedException - 用于用户不允许执行的操作的异常。

Http

中间件

BlockViewerUsers - 此中间件应用于所有路由，阻止任何具有 VIEWER 角色的用户访问任何非 GET 路由。
HasRole - 此中间件可以应用于只能由具有特定角色或具有完全访问权限的 ADMINS 用户访问的路由。

响应

ApiErrorResponse - 用于返回任何错误响应的类，配置为通过 app/Exceptions/Handler 使用。
ApiSuccessResponse - 用于返回任何成功响应的类，配置为与 JSON 资源 一起使用。
NoContentResponse - 用于返回空响应的类。

模型

BaseModel - 所有模型都应扩展的基本类，已配置 CommonQueries、LogChanges、SoftDeletes 和 UserActions 特性。
ChangeLog - 记录对其他模型所做的所有更改的表模型。
CommonQueries - 此特性提供许多可用于模型中的常见查询方法。
HasUuidField - 此特性为不想将 UUID 作为主键的模型提供 UUID 字段支持。
LogChanges - 此特性提供模型上的更改监听器。检查该类了解如何使用此特性的属性自定义模型。
UserActions - 此特性提供用户对模型进行更改的监听器，填充 created_by、updated_by 和 deleted_by 字段。检查该类了解如何使用此特性的属性自定义模型。

服务

SlackClient - 用于向 Slack 发送通知的类。您需要在 env 中添加所需的配置，检查 config/services.php 文件以了解如何配置 Slack 服务。

支持

Datatable - 提供分页、排序和过滤数据功能的类。
Formatter - 提供常量和方法的类，用于在您的应用程序中格式化数据。
ChangeAction - 由 LogChanges 特性使用的枚举。
SortOption - 由 DatatableDTO 使用的排序顺序枚举。

鸣谢

贡献

请查看贡献指南。

wendelladriel / laravel-exa

维护者

详细信息