Visão Geral do Backend

Visão Geral

O backend Rebase é um servidor Node.js construído sobre Hono que oferece:

• API REST — Endpoints CRUD auto-gerados para cada coleção
• Autenticação — Tokens JWT, Google OAuth, gestão de utilizadores/funções
• Armazenamento — Upload/download de ficheiros com sistema de ficheiros local ou S3
• WebSocket — Sincronização de dados em tempo real via PostgreSQL LISTEN/NOTIFY
• Histórico de Entidades — Trilha de auditoria para cada alteração de dados
• Ramificação de Base de Dados — Cópias de base de dados instantâneas e isoladas para dev/staging/testes
• Tarefas Cron — Tarefas em segundo plano agendadas com painel de monitorização

Tudo é inicializado com uma única função:

import { initializeRebaseBackend } from "@rebasepro/server";
import { createPostgresAdapter } from "@rebasepro/server-postgres";
import { env } from "./env";

const instance = await initializeRebaseBackend({
    app,
    server,
    collectionsDir: "./config/collections",
    database: createPostgresAdapter({
            connection: db,
            schema: { tables, enums, relations }
        }),
    auth: {
        jwtSecret: env.JWT_SECRET,
    },
    storage: { type: "local", basePath: "./uploads" },
    history: true,
    enableSwagger: env.NODE_ENV !== "production"
});

O Que É Criado

Após a inicialização, estas rotas são montadas:

Caminho	Propósito
/api/auth/*	Autenticação (registo, login, refresh, Google OAuth)
/api/admin/*	Gestão de utilizadores e funções (apenas para administradores)
/api/storage/*	Upload, download e eliminação de ficheiros
/api/data/collections	Endpoint de metadados de coleção
/api/data/:slug	Operações CRUD por coleção (GET, POST, PUT, DELETE)
/api/data/:slug/:id/history	Histórico de alterações de entidade (quando ativado)
/api/data/docs	Especificação OpenAPI (quando enableSwagger: true)
/api/data/swagger	Swagger UI (modo de desenvolvimento, quando enableSwagger: true)
/api/functions/*	Rotas de funções personalizadas (quando functionsDir está definido)
/api/cron/*	Gestão de tarefas cron (apenas para administradores, quando cronsDir está definido)
WebSocket on upgrade	Subscrições em tempo real

Referência de Configuração

interface RebaseBackendConfig {
    // HTTP framework
    app: Hono;               // Hono application instance
    server: Server;           // Node.js HTTP server (for WebSocket attachment)
    basePath?: string;        // Route prefix (default: "/api")

    // Collections
    collections?: CollectionConfig[];  // Your collection definitions
    collectionsDir?: string;  // Auto-load collections from a directory

    // Bootstrappers (Databases, Auth, Realtime, etc.)
    bootstrappers: BackendBootstrapper[];

    // Authentication
    auth?: AuthConfig;

    // File storage
    storage?: BackendStorageConfig | Record<string, BackendStorageConfig>;

    // Entity history
    history?: boolean | HistoryConfig;

    // OpenAPI/Swagger
    enableSwagger?: boolean;

    // Custom API endpoints
    functionsDir?: string;    // Auto-load Hono routes from a directory

    // Scheduled tasks
    cronsDir?: string;        // Auto-load cron jobs from a directory

    // Logging
    logging?: { level?: "error" | "warn" | "info" | "debug" };
}

A Instância do Backend

initializeRebaseBackend retorna uma RebaseBackendInstance com acesso a serviços internos:

const instance = await initializeRebaseBackend(config);

// Internal service access
instance.driver              // Default data driver
instance.driverRegistry      // All drivers (for multi-database)
instance.realtimeService     // Default realtime service
instance.auth?.userService       // User management
instance.auth?.roleService       // Role management
instance.storageController   // Default storage
instance.storageRegistry     // All storage backends
instance.collectionRegistry  // Collection metadata
instance.history?.historyService // Entity history
instance.cronScheduler       // Cron job scheduler (when cronsDir is set)

Nota: Embora a instância exponha estes serviços internos, o código da aplicação (como funções personalizadas e tarefas cron) deve usar o singleton global rebase de @rebasepro/server para interagir com a API do backend.

API REST

A API REST é auto-gerada a partir das suas coleções. Cada coleção obtém estes endpoints:

Método	Caminho	Descrição
GET	/api/data/:slug	Listar entidades (com filtro, ordenação, limite, pesquisa)
GET	/api/data/:slug/:id	Obter uma única entidade
POST	/api/data/:slug	Criar uma nova entidade
PUT	/api/data/:slug/:id	Atualizar uma entidade
DELETE	/api/data/:slug/:id	Eliminar uma entidade

Parâmetros de Consulta

Parâmetro	Descrição	Exemplo
filter	Condições de filtro codificadas em JSON	?filter={"active":["==",true]}
orderBy	Campo de ordenação	?orderBy=created_at
order	Direção de ordenação	?order=desc
limit	Tamanho da página	?limit=25
startAfter	Cursor para paginação	?startAfter=encodedCursor
search	Pesquisa de texto completo	?search=laptop

WebSocket

O servidor WebSocket anexa-se ao mesmo servidor HTTP e fornece subscrições em tempo real:

• Subscrever alterações de coleção — ser notificado quando qualquer entidade numa coleção é criada, atualizada ou eliminada
• Subscrever alterações de entidade — ser notificado quando uma entidade específica muda
• Tratamento automático de reconexão no SDK do cliente

O backend usa internamente PostgreSQL LISTEN/NOTIFY. Para implementações de múltiplas instâncias, forneça uma connectionString no seu PostgresBootstrapper para ativar a difusão entre instâncias.

Tratamento de Erros

O backend inclui um manipulador de erros que captura todas as exceções e retorna respostas de erro estruturadas:

{
    "error": {
        "message": "Entity not found",
        "code": "not-found",
        "status": 404
    }
}

Se a inicialização falhar (por exemplo, erro de conexão à base de dados), o servidor ainda inicia, mas retorna 503 para todos os pedidos da API, com uma mensagem de erro descritiva nos logs.

Próximos Passos

• Autenticação — JWT, Google OAuth, gestão de utilizadores
• Armazenamento — Armazenamento de ficheiros local e S3
• Callbacks de Entidade — Hooks de ciclo de vida e API context.data
• Histórico de Entidade — Trilha de auditoria
• Funções Personalizadas — Adicionar endpoints de API personalizados
• Tarefas Cron — Tarefas em segundo plano agendadas
• Ramificação de Base de Dados — Cópias de base de dados instantâneas para dev/staging