Referência v3
Voltar à plataforma

Rotas e Middlewares

Como definir endpoints e protegê-los.

Definindo rotas

O arquivo Routes/web.php do módulo é carregado automaticamente. A variável $router é injetada pelo kernel via include — declare o @var no topo para ter autocomplete na IDE e deixar o contrato explícito:

php
<?php

/** @var \Src\Kernel\Contracts\RouterInterface $router */

// Métodos disponíveis
$router->get('/api/recurso',          [Controller::class, 'listar']);
$router->post('/api/recurso',         [Controller::class, 'criar']);
$router->put('/api/recurso/{uuid}',   [Controller::class, 'atualizar']);
$router->patch('/api/recurso/{uuid}', [Controller::class, 'parcial']);
$router->delete('/api/recurso/{uuid}',[Controller::class, 'deletar']);
Por que o $router aparece "do nada"?

O kernel carrega o arquivo de rotas com include, injetando $router no escopo. É o mesmo padrão do Laravel (Route::), Express (app.get) e Slim. O @var documenta o contrato e ativa o autocomplete — sem ele o código funciona, mas fica implícito.

Parâmetros de rota

php
// Definição
$router->get('/api/usuario/{uuid}', [UsuarioController::class, 'buscar']);

// No Controller
public function buscar(Request $request): Response
{
    $uuid = $request->param('uuid'); // captura {uuid}
    // ...
}

Middlewares disponíveis

MiddlewareQuando usar
AuthHybridMiddlewareQualquer rota que exige usuário logado.
AdminOnlyMiddlewareRotas exclusivas para admin_system.
RateLimitMiddlewareLimitar requisições por IP/usuário.
CircuitBreakerMiddlewareRotas que dependem de banco ou serviços externos.
ApiTokenMiddlewareRotas acessadas por tokens de API (integrações).

Configurando Rate Limit

php
$loginLimit = [RateLimitMiddleware::class, [
    'limit'      => 10,   // max requisições
    'window'     => 60,   // janela em segundos
    'key'        => 'auth.login',  // chave única para este limite
    'user_limit' => 5,    // limite por usuário autenticado (opcional)
]];

$router->post('/api/login', [AuthController::class, 'login'], [$loginLimit]);

Rotas nativas do sistema

Os módulos Auth e Usuario já vêm com as seguintes rotas registradas:

Módulo Auth

MétodoRotaAcessoDescrição
POST/api/auth/loginPúblicaLogin. Rate limit: 10/min.
POST/api/loginPúblicaAlias de login.
POST/api/auth/refreshPúblicaRenova access token via refresh token. Rate limit: 20/min.
GET/api/auth/meAuthDados do usuário autenticado.
POST/api/auth/logoutAuthLogout — revoga tokens.
POST/api/auth/recuperacao-senhaPúblicaSolicita reset de senha. Rate limit: 5/min.
POST/api/auth/resetar-senhaPúblicaRedefine senha com token.
GET/api/recuperar-senha/validar/{token}PúblicaValida token de recuperação.
GET/api/auth/verify-emailPúblicaVerifica e-mail via token.
GET/api/auth/email-verificationAuthPolítica de verificação de e-mail.

Módulo Usuario

MétodoRotaAcessoDescrição
POST/api/registrarPúblicaRegistro de novo usuário. Rate limit: 5/min.
GET/api/perfilAuthDados do perfil autenticado.
PUT/api/perfilAuthAtualiza perfil.
PUT/api/perfil/emailAuthAltera e-mail.
PUT/api/perfil/senhaAuthAltera senha.
POST/api/perfil/uploadAuthUpload de avatar/capa.
DELETE/api/perfilAuthDeleta a própria conta.
GET/api/perfil/{username}PúblicaPerfil público. Rate limit: 30/min.
GET/api/usuariosAdminLista todos os usuários.
GET/api/usuario/{uuid}AdminBusca usuário por UUID.
PUT/api/usuario/atualizar/{uuid}AdminAtualiza usuário.
DELETE/api/usuario/deletar/{uuid}AdminRemove usuário.
PATCH/api/usuario/{uuid}/ativarAdminAtiva usuário.
PATCH/api/usuario/{uuid}/desativarAdminDesativa usuário.