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 存储库页面上的 Use this template 按钮。

Git Clone

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://127.0.0.1:APP_EXTERNAL_PORT

默认情况下，APP_EXTERNAL_PORT 为 8000

https://127.0.0.1:8000

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

https://127.0.0.1:SWAGGER_EXTERNAL_PORT

默认情况下，SWAGGER_EXTERNAL_PORT的值为8080。

https://127.0.0.1:8080

应用程序结构

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

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

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

创建模块

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

make art ARGS="make:module NAME"

这将创建一个与其它模块相同结构的模块，默认情况下该模块是禁用的。要启用它，请将新模块名称添加到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 Resources一起使用。
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

维护者

详细信息