README

此包是一个用于使用Laravel创建API网关或微服务的库。它侧重于一种架构，其中API网关是应用程序的唯一入口点，并且还负责验证权限、身份验证和用户管理。API网关可以直接通过HTTP请求或通过RabbitMq作为API网关和微服务之间通信的服务在后台与微服务通信。服务只能通过API网关相互通信。

安装

要安装此包，请执行以下Composer命令

composer require jose-1805/laravel-microservices

API网关

API网关配置

要配置您的API网关，请按照以下步骤进行，以建立必要的配置

步骤 #1

使用以下命令之一发布配置文件

1. 如果您想使用UUIDS实现模型

php artisan vendor:publish --tag=laravel-microservices-config-api-gateway

1. 如果您想不使用UUIDS实现模型

php artisan vendor:publish --tag=laravel-microservices-config-api-gateway-no-uuids

将在项目的config目录中发布一个名为laravel_microservices.php的配置文件，以及一个以laravel_microservices_create_users_table.php结尾的用户表迁移文件。在用户表中添加您需要的额外字段，并删除默认用户表的迁移。以下是对配置文件值的描述。

use_uuid 确定是否应在包中的模型中使用uuids，不要编辑此值，因为它将根据发布配置文件时执行的命令自动设置。

background 此项包含解决后台请求的配置，其中包含events键，它负责将一个事件（事件是分配给后台请求的名称）与将执行该事件的类的名称相关联。随着事件的创建，应填写此值，尽管在API网关中通常不添加事件。通常，API网关只会接收background_request_result事件，该事件引用后台请求的执行结果。包负责此操作，并在后台请求的数据库记录中执行必要的更改。如果想要更改此类，请确保在background_requests表的output_data列中注册请求结果，并更改状态为1在state列。在API网关的命令部分中解释了如何创建事件和相关类。

is_api_gateway 此值允许包识别它应该在何种模式下设置配置，以正确运行所有组件。此值不应编辑。

microservices 包含一个数组，其中包含可以连接到API网关的微服务的配置。基于此配置，将创建连接到每个微服务的必要元素，这将在后面进一步说明。此数组中的值可以随着每个微服务的发展而创建，并且每个微服务的名称应该是小写。

roles 存储在执行 lm:sync-roles-and-permissions 命令时在数据库中存储的配置角色数组，此命令逐个存储在 permissions 项目中找到的所有权限名称，然后创建或同步与定义的团队及其权限一起配置的角色。

php artisan lm:sync-roles-and-permissions

步骤 #2

如果需要使用团队来管理角色和权限，请使用以下命令发布 laravel-permission 的配置文件：

php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag=permission-config

将在项目的 config 目录下发布一个名为 permission.php 的配置文件，将 teams 键的值设置为 true。

步骤 #3

在其 .env 文件中配置以下环境变量

连接到 rabbit mq 的配置

RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USER
RABBITMQ_PASSWORD
RABBITMQ_VHOST

可选地，您还可以配置以下内容

RABBITMQ_EXCHANGE               // Por defecto se asigna 'microservices.topic'
RABBITMQ_EXCHANGE_TYPE          // Por defecto se asigna 'topic'
RABBITMQ_INTERVAL_CONNECTION    // Por defecto se asigna 5

此包包含 predis/predis 的安装，用于连接 Redis，请使用连接 Redis 的最小变量配置 .env 文件

REDIS_HOST // Url del servidor o nombre del contenedor donde se encuentra instalado Redis
REDIS_PASSWORD // Contraseña de acceso al redis
REDIS_PORT // Puerto habilitado para la conexión con redis
REDIS_CLIENT // Cliente para manejo de conexiones, si no tiene instalada la extensión de phpredis puede utilizar predis/predis que es un paquete que no requiere la instalación de la extensión phpredis

现在您已经配置了 Redis 连接，可以将 Redis 配置为缓存、会话和/或队列的驱动程序

CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis

配置数据库访问的环境变量

步骤 #4

将以下配置添加到 config/app.php 文件的别名列表中，用于 Rabbit Mq 管理类

'Amqp' => Bschmitt\Amqp\Facades\Amqp::class

步骤 #5

将 laravel permission 的中间件添加到 app\Http\Kernel.php 文件的 $middlewareAliases 变量中

'role' => \Spatie\Permission\Middlewares\RoleMiddleware::class,
'permission' => \Spatie\Permission\Middlewares\PermissionMiddleware::class,
'role_or_permission' => \Spatie\Permission\Middlewares\RoleOrPermissionMiddleware::class,

步骤 #6

如果您要使用单页应用程序 (SPA) 的身份验证，请在 app\Http\Kernel.php 文件的 api 键中启用或添加以下中间件

\Laravel\Sanctum\Http\Middleware\EnsureFrontendRequestsAreStateful::class,

步骤 #7

将 ApiResponser trait 和 renderExceptions 函数添加到 app/Exceptions/Hanlder.php 类中，用于标准化的响应处理。在类声明之前

use Jose1805\LaravelMicroservices\Traits\ApiResponser;

在类声明之后

use ApiResponser;

public function render($request, Throwable $exception)
{
    return $this->renderExceptions($request, $exception);
}

步骤 #8

配置您的 User 模型，使其扩展 Jose1805\LaravelMicroservices\Models\(User 或 UserUuid)。这些类已经扩展了 Laravel 的 Model，并使用了对该包正常运行所需的实现和 traits。

步骤 #9

如果使用 uuid 配置，在个人访问令牌迁移中将 $table->morphs("tokenable"); 改为 $table->uuidMorphs("tokenable");

步骤 #10

使用以下命令运行数据库迁移

php artisan migrate

步骤 #11

您可以使用 teams 中间件将所有路由或您希望的路由分组，该中间件负责验证认证用户的请求是否包含 Team-Id 标头，以在当前会话中设置与用户关联的团队

API 网关命令

此包包含一些在项目开发和部署过程中有用的 artisan 命令

角色和权限

php artisan lm:sync-roles-and-permissions

此命令在数据库中同步配置的角色和权限，配置文件的 roles 和 permissions 字段为 config/laravel_microservices.php。

RabbitMQ 工作器

php artisan lm:consume-amqp queue-name

此命令将连接到 queue-name 中指定的队列（对于 API 网关通常使用 api_gateway_queue.default），并根据接收的事件执行关联事件的类的 handle 方法。如果不存在事件，将在日志中记录一条消息。在生产环境中（如果需要在开发中也是如此），您必须在 supervisord 等进程管理器中运行此包，配置如下所示

[program:amqp_consumer]
process_name=%(program_name)s_%(process_num)02d
command=php -d variables_order=EGPCS /var/www/html/artisan consume:amqp api_gateway_queue.default
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

后台任务

php artisan lm:make-resolver NombreTarea --event=event-name

执行此命令以创建和配置一个后台任务，通常在API网关中不需要这样做，因为事件background_request_result已经包含了在包中定义的实现，该实现会更新数据库中（表background_requests）的请求信息。该命令将创建一个文件app/Background/NombreTarea.php，在包含的类中，您将找到一个handle方法，它接收事件名称和后台请求的数据，执行所需的任务，并返回将被发送给请求该操作的服务的响应。该命令还将配置文件config/background.php，以便在--event中接收的事件与类NombreTarea关联。

连接到微服务

php artisan lm:sync-microservice-connections MicroserviceName1 MicroserviceName2 ... MicroserviceNameN

此命令创建建立与一个或多个微服务的连接所需的资源和配置，可以传递0、1或更多微服务的名称。您也可以通过安装laravel-microservices包来预先创建微服务的代码基础，因为将生成一个访问令牌，该令牌需要在微服务中存储以在API网关中进行身份验证。

如果您发送微服务名称，请确保这些名称已在文件config/laravel_microservices.php中配置，或者在microservices键中至少出现。如果微服务名称未在文件中找到，则命令不会执行任何操作。如果没有发送微服务名称，则命令将创建连接到所有在文件中找到的微服务名称所需的所有元素。

一旦执行了此命令，就会创建控制器、访问路由，将微服务存储在数据库中，并为每个新的微服务创建一个访问令牌。您必须将此令牌存储在各自的微服务中，以允许微服务向API网关发送请求。

API网关路由

该包包含一些执行项目所需的重要路由

(POST) /api/token

此路由用于通过用户凭据获取系统访问令牌。它接收参数email, password 和 device_name。如果数据正确，该路由将在token键中返回用户的令牌，在user键中返回用户的基本数据，如果启用了角色和权限管理，还将收到在teams键中与客户关联的团队标识符，在每次请求中，都必须发送一个包含应用于查询用户信息的团队ID的Team-Id标题。

(POST) /api/logout

此路由通过删除请求中发送的token来关闭用户会话。

(GET) /api/background-request-result/{id}/{event}

此路由允许查询后台请求的当前状态，接收请求ID和相关事件名称。用户必须经过身份验证，并且只能查询他已注册的请求。一旦任务完成，一旦执行了其新状态的第一次查询，它将自动删除。

(GET) /api/user-data

此路由允许查询用户完整信息。

微服务

微服务配置

要配置微服务，请执行以下步骤以设置必要的配置

步骤 #1

使用以下命令发布配置文件

php artisan vendor:publish --tag=laravel-microservices-config-microservice

将名为 laravel_-_microservices.php 的配置文件发布到项目的 config 目录中。目前不要修改此文件，但需要添加环境变量以配置对 API 网关的访问（API_GATEWAY_PUBLIC_URL, API_GATEWAY_BASE_URI 和 API_GATEWAY_ACCESS_TOKEN）。以下将描述可以使用的数组元素进行配置。

background 此项包含处理后台请求的配置，在其中您可以找到负责将事件（事件是分配给后台请求的名称）与将在接收到该事件时运行的类名关联的 events 键。随着事件的创建，该值应逐步填写。在微服务命令部分解释了如何创建事件和相关的类。

is_api_gateway 此值允许包识别它应该在何种模式下设置配置，以正确运行所有组件。此值不应编辑。

access_tokens 存储访问令牌，用于验证从 API 网关到微服务的 HTTP 请求。不需要编辑此值，也不需要在 .env 文件中添加 ACCESS_TOKENS 环境变量。稍后将解释如何使用 lm:make-access-token 命令管理这些令牌。

api_gateway API 网关访问配置。在您的 .env 文件中，必须定义环境变量 API_GATEWAY_PUBLIC_URL, API_GATEWAY_BASE_URI 和 API_GATEWAY_ACCESS_TOKEN

API_GATEWAY_PUBLIC_URL: Esta es la url pública del api gateway, se utiliza para agregarla en la paginación de los modelos.

API_GATEWAY_BASE_URI: Esta es la url que se utiliza para que los micro servicios creados realicen solicitudes a api gateway.

API_GATEWAY_ACCESS_TOKEN: Este es el token de acceso al api gateway desde el micro servicio, este token se obtiene en el api gateway cuando se registra el micro servicio en la base de datos.

步骤 #2

在其 .env 文件中配置以下环境变量

连接到 rabbit mq 的配置

RABBITMQ_HOST
RABBITMQ_PORT
RABBITMQ_USER
RABBITMQ_PASSWORD
RABBITMQ_VHOST

可选地，您还可以配置以下内容

RABBITMQ_EXCHANGE               // Por defecto se asigna 'microservices.topic'
RABBITMQ_EXCHANGE_TYPE          // Por defecto se asigna 'topic'
RABBITMQ_INTERVAL_CONNECTION    // Por defecto se asigna 5

后台任务配置

BACKGROUND_EVENT_RESPONSE  // Por defecto se asigna 'background_request_result'
BACKGROUND_QUEUE_RESPONSE  // Por defecto se asigna 'api_gateway_queue.default'

此包包含 predis/predis 的安装，用于连接 Redis，请使用连接 Redis 的最小变量配置 .env 文件

REDIS_HOST // Url del servidor o nombre del contenedor donde se encuentra instalado Redis
REDIS_PASSWORD // Contraseña de acceso al redis
REDIS_PORT // Puerto habilitado para la conexión con redis
REDIS_CLIENT // Cliente para manejo de conexiones, si no tiene instalada la extensión de phpredis puede utilizar predis/predis que es un paquete que no requiere la instalación de la extensión phpredis

现在您已经配置了 Redis 连接，可以将 Redis 配置为缓存、会话和/或队列的驱动程序

CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis

配置数据库访问的环境变量

步骤 #3

将以下配置添加到 config/app.php 文件的别名列表中，用于 Rabbit Mq 管理类

'Amqp' => Bschmitt\Amqp\Facades\Amqp::class

步骤 #4

将 trait ApiResponser 和函数 renderExceptions 添加到 app/Exceptions/Hanlder.php 类中，以进行标准化的响应处理。在类之前添加

use Jose1805\LaravelMicroservices\Traits\ApiResponser;

在类之后

use ApiResponser;

public function render($request, Throwable $exception)
{
    return $this->renderExceptions($request, $exception);
}

步骤 #5

将中间件 \Jose1805\LaravelMicroservices\Http\Middleware\Service\AuthenticateAccessMiddleware::class 添加到 app\Http\Kernel.php 文件中的 $middleware 变量中，以验证所有请求是否包含来自 api_gateway 的认证。如果只想验证一些请求，请将中间件 auth_api_gateway 添加到需要验证的路线。

步骤 #6

使用以下代码编辑您的 User 模型，如果 API 网关的用户模型不使用 uuids，请从以下代码中删除包含 use HasUuids; 的行

<?php
namespace App\Models;
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Model;
class User extends Model
{
    use HasUuids;
}

微服务命令

此包包含一些在项目开发和部署过程中有用的 artisan 命令

RabbitMQ 工作器

php artisan lm:consume-amqp queue-name

此命令将连接到 queue-name（队列名称在创建服务时配置）中指定的队列，并根据接收的事件执行关联事件类的 handle 方法。如果不存在事件，则记录一条消息。在生产环境中（如果需要，在开发环境中也是如此），您必须在类似 supervisord 的进程管理器中运行此包，以下是一个配置示例

[program:amqp_consumer]
process_name=%(program_name)s_%(process_num)02d
command=php -d variables_order=EGPCS /var/www/html/artisan consume:amqp service_name_queue.default
autostart=true
autorestart=true
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

访问令牌

php artisan lm:make-access-token

此命令创建一个新的访问令牌并自动将其记录在您的 .env 文件中，以验证从 API 网关发出的 HTTP 请求。生成此令牌后，您必须将其添加到 API 网关中微服务的配置中。

后台任务

php artisan lm:make-resolver NombreTarea --event=event-name

执行以下命令以创建和配置一个用于后台处理的任务。该命令将创建一个 app/Background/NombreTarea.php 文件，其中包含一个类，该类包含一个接收事件名称和后台请求数据的 handle 方法。执行所需任务并返回一个将被发送到 API 网关的响应。该命令还配置了 config/laravel_microservices.php 文件中的 background 元素，以便接收到的 --event 事件与 NombreTarea 类关联。

创建服务资源

 php artisan lm:make-resource ResourceName --route=/example/example

此命令用于创建具有模型、请求、控制器和路由的资源。--route 参数不是必需的，如果不提供，系统将自动分配根据资源名称的路线。如果结果不是预期的，可以直接在路由文件中更改此设置。