A Tríade da Lógica Backend: Server Actions vs Route Handlers vs Supabase Edge Functions

No desenvolvimento web moderno com Next.js App Router e Supabase, nós temos à disposição três ambientes servidores distintos para executar código de backend:

1. Server Actions ("use server") no Next.js.
2. Route Handlers (app/api/.../route.ts) no Next.js.
3. Supabase Edge Functions (Deno) coladas ao banco de dados Postgres.

Muitas equipes inexperientes cometem um erro crasso: tentar usar uma única ferramenta para resolver tudo. Criam Route Handlers manuais para salvar um formulário simples da própria tela, ou tentam receber Webhooks de pagamento dentro da Vercel em vez de processá-los diretamente no banco.

O resultado é um sistema com latência desnecessária, faturas inchadas de funções serverless e brechas de segurança.

Neste manual arquitetural, vamos esclarecer a Regra da Tríade de Execução corporativa em 2026: onde cada linha de código deve residir para garantir segurança máxima, latência mínima e custos previsíveis.

---

1. Server Actions ("use server"): Mutações de Interface

As Server Actions foram projetadas para resolver o problema clássico de mutações de dados acopladas à interface gráfica.

Elas operam como uma Remote Procedure Call (RPC) invisível. O Next.js compila a função no servidor e permite que componentes React a executem diretamente, sem a necessidade de criar rotas REST manuais com fetch('/api/...').

[Componente React / Form] 
       │
       ▼ (RPC POST invisível com Payload serializado)
[Server Action ("use server")]
       │
       ├── 1. Validação estrita de entrada com Zod
       ├── 2. Sessão do Usuário (Cookies lidos automaticamente)
       ├── 3. Mutação no Supabase sob permissões de RLS
       └── 4. revalidatePath() / revalidateTag()
       │
       ▼ (Retorno tipado direto para a UI)
[Feedback em tela / useActionState / Toast]

Quando USAR Server Actions (Obrigatório):

• Formulários e Mutações de Tela (CRUD): Atualizar perfil, cadastrar cliente, alterar status de pedido.
• Ações no Contexto do Usuário Logado: Como o Next.js gerencia automaticamente os cookies de sessão no cabeçalho HTTP, a Server Action já sabe exatamente quem é o usuário autenticado via Supabase Auth, sem repasse manual de tokens JWT.
• Validação de Entrada com Zod: A Server Action atua como a primeira linha de defesa antes de qualquer comunicação com o banco.
• Atualização Atômica de Cache: Disparo de revalidatePath('/dashboard') imediatamente após a gravação.

Exemplo: Server Action de Atualização Cadastral

// app/actions/update-profile.ts
"use server";

import { z } from "zod";
import { revalidatePath } from "next/cache";
import { createServerClient } from "@/lib/supabase/server";

// Schema de validacao com Zod
const ProfileSchema = z.object({
  fullName: z.string().min(3, "O nome deve ter pelo menos 3 caracteres"),
  department: z.string().min(2, "Departamento obrigatorio"),
});

export type ActionResponse = {
  success: boolean;
  message: string;
  errors?: Record<string, string[]>;
};

export async function updateProfileAction(
  _prevState: ActionResponse,
  formData: FormData
): Promise<ActionResponse> {
  // 1. Validacao rigorosa dos dados
  const validatedFields = ProfileSchema.safeParse({
    fullName: formData.get("fullName"),
    department: formData.get("department"),
  });

  if (!validatedFields.success) {
    return {
      success: false,
      message: "Dados invalidos informados.",
      errors: validatedFields.error.flatten().fieldErrors,
    };
  }

  // 2. Client do Supabase com contexto de cookies de sessao
  const supabase = await createServerClient();
  const { data: { user }, error: authError } = await supabase.auth.getUser();

  if (authError || !user) {
    return {
      success: false,
      message: "Sessao expirada. Faca login novamente.",
    };
  }

  // 3. Mutacao protegida por Row Level Security (RLS)
  const { error: dbError } = await supabase
    .from("profiles")
    .update({
      full_name: validatedFields.data.fullName,
      department: validatedFields.data.department,
      updated_at: new Date().toISOString(),
    })
    .eq("id", user.id);

  if (dbError) {
    return {
      success: false,
      message: "Erro ao gravar dados no banco.",
    };
  }

  // 4. Invalida o cache dos Server Components na Vercel
  revalidatePath("/configuracoes/perfil");

  return {
    success: true,
    message: "Perfil atualizado com sucesso.",
  };
}

---

2. Supabase Edge Functions (Deno): Webhooks e Lógica de Banco

Diferente do Next.js, que hospeda a interface visual, as Supabase Edge Functions rodam em Deno dentro da infraestrutura do Supabase, coladas fisicamente ao banco de dados Postgres.

Por essa razão, qualquer processamento de eventos do sistema ou integrações com terceiros deve residir aqui, e NUNCA em rotas da Vercel.

Por que Webhooks de Pagamento Moram no Supabase?

1. Sub-milissegundo de Latência: A Edge Function se comunica com o Postgres via rede interna de baixíssima latência. Um Route Handler na Vercel precisaria abrir conexões externas pela internet pública.
2. Economia de Recursos Serverless: Na Vercel, cada chamada a um Route Handler queima invocações da cota mensal. No Supabase, as Edge Functions contam com milhões de execuções inclusas no plano Pro.
3. Isolamento da Service Role Key: A chave mestre de administrador (SUPABASE_SERVICE_ROLE_KEY) fica contida com segurança dentro do ambiente de dados, sem circular pelas variáveis de ambiente da aplicação web.

Quando USAR Supabase Edge Functions (Obrigatório):

• Webhooks Externos de Terceiros: Notificações de pagamento (Stripe, Asaas, Mercado Pago), webhooks do WhatsApp Business e integrações de ERP.
• Database Webhooks e Triggers: Disparos automáticos originados pelo Postgres (via pg_net) quando uma linha é inserida ou modificada.
• Rotinas com Privilégio Máximo (Service Role): Ações administrativas que precisam contornar o RLS porque não possuem um usuário humano logado na sessão.

---

3. Next.js Route Handlers (app/api/...): A Malha de Entrega da Vercel

Se as Server Actions cuidam dos formulários da tela e as Supabase Edge Functions cuidam dos Webhooks externos e do banco de dados, qual é o papel legítimo dos Route Handlers no Next.js?

Na nossa arquitetura limpa, os Route Handlers não são uma API REST genérica de banco de dados. Eles atuam exclusivamente como adaptadores de infraestrutura e delivery da Vercel:

1. On-Demand ISR Cache Revalidation (/api/revalidate)

O banco de dados Supabase avisa a Vercel que um registro mudou (ex: um produto do catálogo foi editado). O Supabase faz uma requisição HTTP silenciosa para o Route Handler /api/revalidate, que purga a página estática na CDN da Vercel instantaneamente.

// app/api/revalidate/route.ts
import { NextRequest, NextResponse } from "next/server";
import { revalidatePath, revalidateTag } from "next/cache";

export async function POST(request: NextRequest) {
  const secret = request.nextUrl.searchParams.get("secret");

  // Validacao do token secreto compartilhado entre Supabase e Vercel
  if (secret !== process.env.REVALIDATION_SECRET_TOKEN) {
    return NextResponse.json(
      { message: "Token de revalidacao invalido" },
      { status: 401 }
    );
  }

  const body = await request.json().catch(() => null);
  const tag = body?.tag;
  const path = body?.path;

  if (tag) {
    revalidateTag(tag);
    return NextResponse.json({ revalidated: true, tag, now: Date.now() });
  }

  if (path) {
    revalidatePath(path);
    return NextResponse.json({ revalidated: true, path, now: Date.now() });
  }

  return NextResponse.json(
    { message: "Parametro tag ou path ausente" },
    { status: 400 }
  );
}

2. Auth Callback de OAuth (/auth/callback/route.ts)

Quando o usuário faz login social (Google, GitHub, Apple), o provedor redireciona para esse endpoint HTTP com um code. O Route Handler troca o código pela sessão no Supabase e grava os cookies seguros no navegador.

3. Geração Dinâmica de Metadados e OG Images (/api/og/route.ts)

Geração de imagens dinâmicas para redes sociais (WhatsApp, Twitter, LinkedIn) renderizadas em HTML/CSS na Edge da Vercel com ImageResponse.

4. Modo de Rascunho / CMS Preview (/api/draft/route.ts)

Habilita visualização de rascunhos de conteúdo não publicados gravando cookies de bypass com draftMode().enable().

---

4. Matriz Comparativa da Tríade de Execução

Critério Arquitetural	Server Actions (Next.js)	Supabase Edge Functions (Deno)	Route Handlers (Next.js)
Objetivo Principal	Mutações originadas na tela (UI)	Eventos de sistema e Webhooks de parceiros	Delivery, Cache e Auth Callback da Vercel
Público Chamador	Componente React no navegador	Gateways (Stripe, WhatsApp, ERPs)	Supabase Triggers, Provedores OAuth
Contexto de Sessão	Cookies automáticos do usuário	Token Bearer ou Service Role Key	Cabeçalhos HTTP e Cookies de redirecionamento
Segurança no Banco	Row Level Security (RLS)	Service Role Key (Admin) ou RLS	Não deve acessar o banco diretamente
Invalidação de Cache	revalidatePath direto na ação	Chama o webhook /api/revalidate	Executa revalidatePath / revalidateTag
Protocolo de Chamada	RPC invisível do React	Requisição HTTP REST pura	Requisição HTTP REST pura

---

5. E Quando a Rotina Dura Minutos ou Dias?

Nem Server Actions, nem Route Handlers e nem Edge Functions foram feitas para suportar processos que demoram horas ou dias para concluir (como réguas de e-mail espaçadas, retentativas com backoff de 24h ou pipelines de agentes de IA).

Para esses fluxos de longa duração, a solução moderna é o Vercel Workflows ("use workflow"). Ele permite pausar a função (sleep) sem consumir nenhum milissegundo de CPU ociosa, dispensando filas complexas de Redis ou RabbitMQ.

---

Conclusão: Arquitetura Limpa Sem Gambiarras

Em um SaaS corporativo de alta demanda construído sobre a stack híbrida:

• Server Actions pertencem à Interface e ao Usuário.
• Supabase Edge Functions pertencem aos Dados e aos Sistemas Externos.
• Route Handlers pertencem à Infraestrutura e ao Caching da Vercel.

Respeitar essa separação elimina 100% dos conflitos arquiteturais, blinda sua aplicação contra vazamento de credenciais e garante um código preparado para suportar milhões de acessos.

Se a sua empresa precisa reestruturar sistemas para alta escalabilidade, migrar arquiteturas legadas ou auditar a segurança de sua stack Next.js e Supabase, conheça nossos serviços de desenvolvimento sob medida ou solicite um diagnóstico de arquitetura.