Ir para o conteúdo
Promovaweb

Rotas, API e ações de servidor no Next.js

StayCloudVPS Agêntica

Uma VPS para os seus agentes trabalharem dia e noite

Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.

Montar minha VPS Agêntica

Link de parceiro da Promovaweb.

Black Friday até 30/11

30%off

nos 2 primeiros meses do plano mensal da VPS

  • Backup diário grátis para sempre
  • Servidores em São Paulo no datacenter da Ascenty
  • Datacenter Tier III manutenção sem parada
  • Acesso root com disco SSD NVMe
  • Réplica do backup em Ashburn, nos EUA

Route Handlers definem endpoints HTTP dentro do App Router e podem devolver respostas para outras aplicações. Server Actions executam alterações no servidor a partir das interações da interface.

Sumário da página

  1. Uma página e um endpoint têm funções diferentes
  2. Route Handlers trabalham com HTTP
  3. Server Actions ligam a interface à alteração
  4. Consultar no servidor evita uma chamada desnecessária
  5. Publicação altera o ambiente disponível

Uma página e um endpoint têm funções diferentes

Uma página Next.js produz a interface que você visita no navegador. Um endpoint HTTP recebe uma requisição e devolve uma resposta para um consumidor, que pode ser o navegador ou outro sistema. O App Router oferece Route Handlers para esse segundo papel. Eles ficam em arquivos route e usam as APIs de requisição e resposta da plataforma web.

Um catálogo pode ter o endereço de um produto e um endpoint que apresenta informações desse produto em JSON. Na interface visual, você lê o nome, consulta o preço e altera a quantidade. O endpoint atende uma integração ou uma consulta programática. A estrutura do endereço precisa respeitar as convenções do framework, inclusive a separação entre page e route no mesmo segmento.

Uma requisição pode chegar diretamente ao endpoint, por fora dos botões do painel. O código precisa conferir a identidade quando necessário, validar a entrada e verificar o acesso ao registro. Esse cuidado vale tanto para a leitura de uma compra quanto para a alteração de um preço.

Route Handlers trabalham com HTTP

Os métodos HTTP representam tipos de operação que o handler pode tratar. GET costuma servir à leitura de uma representação. POST recebe conteúdo para processamento. Outros métodos podem participar conforme a interface oferecida pelo projeto. O framework fornece o ponto de execução, enquanto a aplicação define o contrato de entrada e saída.

Um handler pode ler cabeçalhos, parâmetros e corpo da requisição. Ele pode devolver JSON, texto e outros tipos de resposta suportados. Isso permite receber um webhook ou apresentar uma interface para outro serviço. A assinatura de um webhook precisa ser validada conforme o contrato da integração antes de aceitar uma alteração baseada no conteúdo recebido.

Os endpoints também precisam tratar respostas inválidas e falhas de consulta. Um identificador ausente não deve virar uma alteração silenciosa. Uma tentativa sem permissão precisa receber a resposta apropriada. O endereço público do handler deve ser considerado uma interface acessível pela rede, mesmo quando a documentação da aplicação só mostra o formulário do painel.

  1. Requisição

    O consumidor envia um método, um endereço e o conteúdo.

  2. Handler

    A aplicação valida a entrada e o acesso ao registro.

  3. Resposta

    O servidor informa o resultado com corpo e status HTTP.

O Route Handler recebe a requisição HTTP e devolve o resultado após a validação e a autorização.

Server Actions ligam a interface à alteração

Server Actions são funções de servidor usadas para alterações a partir da interface. Um formulário de edição de produto pode enviar o preço e receber o resultado da operação. O framework oferece a ligação entre o componente e a função. A aplicação continua responsável por validar o valor, conferir a sessão e autorizar a edição daquele produto.

A diretiva use server identifica funções executadas no servidor. A documentação trata essas ações como interfaces que precisam das mesmas verificações de uma operação de servidor. A função confere a sessão mesmo quando o botão de edição está fora da tela.

O resultado de uma ação pode atualizar a interface e participar dos mecanismos de revalidação. Depois de editar um preço, a aplicação precisa evitar que a tela continue mostrando a versão anterior. A ligação entre alteração, invalidação e nova leitura faz parte do fluxo. Um retorno de sucesso da gravação confirma o registro; a atualização das páginas depende do cache e da revalidação do conteúdo relacionado.

Consultar no servidor evita uma chamada desnecessária

Um Server Component pode consultar diretamente um banco ou serviço apropriado. Ele não precisa fazer uma chamada HTTP ao Route Handler do próprio projeto apenas para obter o mesmo produto. Acrescentar essa volta pode criar trabalho desnecessário e exigir um endereço acessível durante fases que não têm um servidor da aplicação disponível.

Um endpoint faz sentido quando existe um consumidor HTTP real. A consulta direta faz sentido quando o componente já está no ambiente capaz de acessar a origem. A escolha acompanha a interface necessária e as permissões disponíveis. Compartilhar uma função de consulta pode manter o comportamento coerente sem obrigar toda leitura interna a atravessar a rede.

A documentação também apresenta limites do uso do Next.js como Backend for Frontend, a camada de servidor associada à interface. Um processo de longa duração, uma fila de trabalhos e uma integração com requisitos próprios podem exigir outros serviços e outra forma de execução.

Publicação altera o ambiente disponível

Um servidor Node.js e uma plataforma de funções podem ter limites diferentes de tempo, memória e manutenção de conexões. O handler continua sendo código da aplicação, mas o ambiente define por quanto tempo e de que forma ele pode executar. Um processamento que funciona no desenvolvimento precisa ser avaliado no destino real da publicação.

Numa exportação estática, os arquivos são servidos sem um servidor Next.js em execução. Os recursos usados pelo projeto precisam caber no modo escolhido. A hospedagem deve ser lida junto com as rotas oferecidas, evitando publicar uma interface que depende de uma função ausente naquele ambiente.

As condições de uso do código estão na licença MIT. Para acompanhar uma operação, identifique o consumidor, a entrada, a autorização, a alteração e a resposta. Essa sequência mostra o papel do framework e os pontos que continuam definidos pelo código da aplicação.