Visão geral de funções de backend

As funções de backend permitem que você execute código customizado de backend em um ambiente seguro e isolado. Use funções para implementar lógica de negócio que não deve rodar no navegador, conectar a APIs de terceiros com credenciais protegidas, processar webhooks ou estender seu app com endpoints customizados. As funções de backend rodam no Deno, um runtime moderno de TypeScript. Chame funções do seu frontend usando o SDK, que cuida da autenticação automaticamente. Cada função também recebe seu próprio endpoint HTTP para webhooks e integrações externas. As funções também podem rodar automaticamente usando automations. Agende funções para rodar em horários específicos ou dispare-as em resposta a eventos do banco de dados como criar, atualizar ou excluir registros.

Observe o seguinte:

Implantar funções uma de cada vez não é limitado a 50. Uma única requisição que substitui todas as funções do seu projeto ainda tem o limite de 50.
Funções de backend têm um tempo máximo de execução de 5 minutos, aplicado da mesma forma seja quando a função é chamada diretamente, disparada por uma automação ou invocada como um passo de workflow. Requisições que excedem esse limite são encerradas.

Criar funções

Crie funções de backend como arquivos TypeScript no diretório de funções do seu projeto. Por padrão o diretório de funções é base44/functions/, mas você pode personalizar o caminho na configuração do seu projeto. Cada função fica em seu próprio subdiretório com um arquivo entry.ts ou entry.js:

functions

<function-name>

entry.ts

A CLI usa o caminho do diretório relativo à raiz de funções como o nome da função. Por exemplo, functions/sendWelcomeEmail/entry.ts cria uma função chamada sendWelcomeEmail. Você também pode aninhar funções em subdiretórios para organização. functions/email/send/entry.ts cria uma função chamada email/send.

Adicionando um arquivo de configuração

Para necessidades avançadas como nomes customizados de função ou automations, adicione um arquivo function.jsonc:

functions

<function-name>

entry.ts

function.jsonc

O arquivo de configuração define o nome e o entry point da função:

{
  "name": "sendWelcomeEmail",
  "entry": "entry.ts",
}

Propriedade	Descrição
`name`	Opcional. Identificador único da função. Usado ao invocar pelo SDK ou HTTP. O padrão é o caminho do diretório relativo à raiz de funções.
`entry`	O arquivo contendo o código da função.
`automations`	Opcional. Array de configurações de automation para executar a função em um cronograma ou em resposta a eventos do banco de dados. Veja Automations para detalhes.

entry.ts

O arquivo de código contém a lógica da sua função. Uma função processa uma requisição recebida e retorna um objeto Response. Exporte seu handler como export padrão:

import { createClientFromRequest } from "npm:@base44/sdk";

export default async function (req: Request): Promise<Response> {
  try {
    const base44 = createClientFromRequest(req);
    const user = await base44.auth.me();

    if (!user) {
      return Response.json({ error: "Unauthorized" }, { status: 401 });
    }

    const { name } = await req.json();

    return Response.json({
      message: `Hello, ${name || user.full_name}!`,
    });
  } catch (error) {
    return Response.json({ error: error.message }, { status: 500 });
  }
}

Vários arquivos por função

Uma função não se limita a um único entry.ts. Divida a lógica em vários arquivos dentro do diretório da função e importe-os com caminhos relativos. Todo arquivo .js, .ts, .json e .jsonc no diretório da função é implantado com a função.

functions

process-order

entry.ts

validate.ts

types.ts

// entry.ts
import { validate } from "./validate.ts";

Importações relativas são resolvidas quando você faz o deploy. Uma importação que aponta para um arquivo que não é implantado com a função, como um arquivo no diretório de outra função, falha no momento do deploy.

Compartilhe código entre funções

Para reutilizar código entre funções, coloque-o em um diretório shared dentro da sua pasta base44/. Quando você implanta uma função, a CLI envia o diretório shared junto com ela, e o servidor empacota apenas os arquivos compartilhados que essa função importa. Cada função é implantada com sua própria cópia do código compartilhado que usa. Isso significa que:

Qualquer função pode importar de shared com um caminho relativo.
Funções diferentes podem acabar executando versões diferentes do mesmo arquivo compartilhado. Alterar um arquivo compartilhado e implantar uma única função atualiza apenas a cópia dessa função. As outras mantêm a versão antiga até você implantá-las novamente. Para aplicar uma mudança compartilhada em todas, execute base44 functions deploy sem argumentos para reimplantar todas as funções de uma vez.

base44

shared

response.ts

functions

greet

entry.ts

farewell

entry.ts

// base44/functions/greet/entry.ts
import { ok } from "../../shared/response.ts";

export default async function (req: Request): Promise<Response> {
  const { name } = await req.json();
  return ok({ message: `Hello, ${name}!` });
}

Importações relativas podem alcançar base44/shared/, mas não podem sair de base44/. Para usar código de fora de base44/, mova-o para base44/shared/ ou importe-o com um especificador npm: ou jsr:.

Teste localmente

Execute suas funções localmente com base44 dev para testar mudanças sem fazer deploy. Veja Desenvolvimento local para detalhes.

Implante funções

Implante funções com functions deploy ou deploy para enviar todos os recursos do projeto de uma vez. Você pode implantar funções específicas pelo nome com functions deploy <names...>, ou usar --force para remover funções remotas não encontradas localmente. Para baixar funções implantadas para seu projeto local, use functions pull. Para ver o que está implantado atualmente, use functions list.

Chamar funções

Chame funções de backend do seu frontend usando o SDK, ou via HTTP para webhooks e integrações externas.

Pelo SDK

Use base44.functions.invoke() para chamar funções do seu frontend. O SDK cuida da autenticação automaticamente, passando as credenciais do usuário atual para sua função.

import { base44 } from "@/api/base44Client";

const response = await base44.functions.invoke("sendWelcomeEmail", {
  name: "Alice",
});

Via HTTP

Cada função implantada recebe um endpoint HTTP em:

https://<your-app-domain>/functions/<function-name>

Isso é útil para:

Webhooks: Receba callbacks de serviços externos como Stripe ou GitHub.
Integrações externas: Permita que outros sistemas interajam com seu app.
Testes: Chame funções diretamente com ferramentas como cURL ou Postman.

Exemplo de uso

curl -X POST https://your-app.base44.app/functions/sendWelcomeEmail \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}'

Ao chamar funções via HTTP direto (como cURL ou webhooks), não há contexto de usuário autenticado. Use asServiceRole para todas as operações nesses casos.

Use o SDK em funções

Dentro das suas funções de backend, você pode acessar os dados, autenticação e integrações do seu app através do SDK da Base44. Use createClientFromRequest() para criar um cliente a partir da requisição recebida. O contexto de autenticação depende de como a função foi chamada:

Quando chamada pelo SDK do seu frontend: A autenticação do usuário é passada automaticamente. Você pode acessar o usuário atual com base44.auth.me() e realizar operações com suas permissões. Para ler ou gravar dados sem que as regras de acesso das entidades se apliquem, use asServiceRole.
Quando chamada via HTTP direto (cURL, webhooks, serviços externos): Não há usuário autenticado, então use asServiceRole para todas as operações.

Runtime API

A Base44 oferece um módulo integrado base44:runtime com utilitários da plataforma para suas funções. Importe-o diretamente, sem precisar de instalação:

import { waitUntil, secrets } from "base44:runtime";

O módulo exporta dois utilitários:

waitUntil(): mantém a função ativa para concluir trabalho em segundo plano depois que você retorna uma resposta.
secrets: lê os secrets do seu app em tempo de execução com secrets.get().

Execute trabalho em segundo plano depois de responder

Use waitUntil() para manter sua função ativa para trabalho em segundo plano depois de retornar uma resposta. Passe uma promise, e a função continua rodando até essa promise ser concluída. Assim você responde rápido e conclui depois tarefas como logs, notificações ou webhooks de saída.

import { waitUntil } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  waitUntil(fetch("https://hooks.example.com/ping", { method: "POST" }));

  return Response.json({ status: "accepted" });
}

waitUntil() retorna a mesma promise que você passa, então você pode compô-la ou aguardá-la mais tarde no mesmo handler.

O trabalho em segundo plano é de melhor esforço. Não há garantia de que ele seja concluído ou repetido, então não dependa dele para operações críticas que não podem ser perdidas.

Leia secrets

Use secrets.get() para ler as variáveis de ambiente do seu app em tempo de execução. Ele retorna o valor como string, ou undefined quando o secret não está definido:

import { secrets } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  const apiKey = secrets.get("API_KEY");

  const res = await fetch("https://api.example.com/data", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  return Response.json(await res.json());
}

Chame secrets.get() dentro do seu handler, não no nível superior do módulo. Os secrets são resolvidos por requisição, então uma leitura no carregamento do módulo, antes de qualquer requisição, retorna undefined. Configure secrets pela CLI com secrets set.

Conectar a APIs de terceiros

As funções de backend são uma das várias formas de conectar a APIs de terceiros. Elas são ideais quando você precisa de controle total sobre as requisições ou quer armazenar API keys com segurança como variáveis de ambiente. Use secrets set para configurar variáveis de ambiente pela CLI.

Veja logs

Durante o desenvolvimento local, a saída da função é impressa diretamente no seu terminal sem precisar do comando logs. Para funções implantadas, veja logs com o comando logs. Os logs incluem saída do console, erros e informações de tempo. Você pode filtrar por nome da função ou intervalo de tempo. Se você está usando um agente de codificação de IA, a skill base44-troubleshooter pode buscar e analisar esses logs automaticamente.

Tipos TypeScript

Gere tipos TypeScript a partir das configurações das suas funções para obter segurança de tipo e autocomplete para nomes de função no seu código do SDK. Saiba mais sobre tipos dinâmicos.

Veja também

Automations: Agende funções ou dispare-as em eventos do banco de dados
Módulo functions: Referência do SDK para invocar funções
createClientFromRequest: Criando um cliente em funções de backend
functions deploy: Implante funções locais na Base44
functions pull: Baixe funções implantadas para seu projeto local
functions list: Liste todas as funções implantadas
functions delete: Delete funções implantadas
logs: Veja logs de função
exec: Teste funções de forma isolada a partir de scripts autônomos

Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a versão em inglês.

Visão geral

Início rápido

Projeto

Ferramentas de Desenvolvimento com IA

Recursos

Criar funções

Adicionando um arquivo de configuração

entry.ts

Vários arquivos por função

Compartilhe código entre funções

Teste localmente

Implante funções

Chamar funções

Pelo SDK

Via HTTP

Use o SDK em funções

Runtime API

Execute trabalho em segundo plano depois de responder

Leia secrets

Conectar a APIs de terceiros

Veja logs

Tipos TypeScript

Veja também

​Criar funções

​Adicionando um arquivo de configuração

​entry.ts

​Vários arquivos por função

​Compartilhe código entre funções

​Teste localmente

​Implante funções

​Chamar funções

​Pelo SDK

​Via HTTP

​Use o SDK em funções

​Runtime API

​Execute trabalho em segundo plano depois de responder

​Leia secrets

​Conectar a APIs de terceiros

​Veja logs

​Tipos TypeScript

​Veja também

Criar funções

Adicionando um arquivo de configuração

entry.ts

Vários arquivos por função

Compartilhe código entre funções

Teste localmente

Implante funções

Chamar funções

Pelo SDK

Via HTTP

Use o SDK em funções

Runtime API

Execute trabalho em segundo plano depois de responder

Leia secrets

Conectar a APIs de terceiros

Veja logs

Tipos TypeScript

Veja também