Como hospedar uma API Java (Spring) ou .NET

Uma API Java ou .NET costuma funcionar na sua máquina porque ela tem o JDK ou o SDK, a porta livre e as variáveis certas. Em produção, três coisas mudam: em vez do código-fonte, você envia um artefato compilado; a porta vem do ambiente; e o processo precisa aceitar conexões de fora do container.

Este guia usa Spring Boot para Java e ASP.NET Core Minimal API para .NET. O caminho é o mesmo nos dois: compilar, parametrizar a porta, rodar localmente como em produção, subir e verificar. Para a visão geral de qualquer API, veja como hospedar uma API.

O que você precisa antes de hospedar?#

• Java: um JDK que atenda ao mínimo da sua versão do Spring Boot, conforme os requisitos de sistema. Para um projeto novo, use uma LTS atual do Java (calendário de suporte da Oracle). Para o build, uma versão recente do Maven ou do Gradle; a mesma página traz o mínimo de cada um.
• .NET: o SDK da LTS atual do .NET. A política de suporte da Microsoft mostra qual versão é essa e até quando cada uma recebe correções.
• Um endpoint de saúde (/health) para testar o deploy sem depender de banco ou de autenticação.
• Um lugar para rodar com o runtime correspondente. Se você ainda compara opções, veja VPS vs plataforma de nuvem.

Como criar e compilar a API em Java com Spring Boot?#

Gere o projeto em start.spring.io com a dependência Spring Web. Esta é a classe principal, já com o endpoint de saúde:

package com.example.demo;

import java.util.Map;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }

    @GetMapping("/health")
    public Map<String, String> health() {
        return Map.of("status", "ok");
    }
}

No src/main/resources/application.properties, deixe a porta configurável:

server.port=${PORT:8080}

• server.port=${PORT:8080}: lê a variável PORT e usa 8080 quando ela não existe. A documentação do Spring Boot também aceita SERVER_PORT direto no ambiente, por causa do relaxed binding. O padrão do framework é 8080.
• Encerramento: o graceful shutdown já vem ligado por padrão no Spring Boot: ao receber o sinal de parada, o servidor termina as requisições em andamento antes de encerrar. Não precisa de configuração extra.

Compile e rode o JAR como será em produção:

./mvnw -DskipTests package
PORT=9090 java -jar target/demo-0.0.1-SNAPSHOT.jar
curl http://localhost:9090/health

O spring-boot-maven-plugin já vem no projeto gerado e empacota um JAR executável com tudo dentro (um fat JAR). Com Gradle o equivalente é ./gradlew bootJar. O nome do arquivo vem do artifactId e da versão. Renomeie para algo curto, como app.jar, antes de subir: fica mais fácil apontar o arquivo principal.

Como criar e publicar a API em .NET?#

Crie o projeto e troque o Program.cs:

dotnet new web -n MinhaApi
cd MinhaApi

var builder = WebApplication.CreateBuilder(args);

var port = Environment.GetEnvironmentVariable("PORT") ?? "8080";
builder.WebHost.UseUrls($"http://0.0.0.0:{port}");

var app = builder.Build();

app.MapGet("/health", () => Results.Ok(new { status = "ok" }));

app.Run();

O ASP.NET Core não lê a variável PORT sozinho, por isso o código faz essa leitura. O Kestrel escuta só em localhost por padrão, e 0.0.0.0 faz ele aceitar conexões de fora do container. A alternativa sem código é definir ASPNETCORE_URLS=http://0.0.0.0:8080 no ambiente.

Publique em modo Release e teste a pasta de saída:

dotnet publish -c Release -o out
PORT=9090 dotnet out/MinhaApi.dll
curl http://localhost:9090/health

O que sobe para o servidor é o conteúdo da pasta out: a DLL principal, as dependências e os arquivos .json de configuração. Não envie as pastas bin e obj.

Por que a API escuta em 0.0.0.0 e lê a porta do ambiente?#

Em container ou em plataforma de hospedagem, quem decide a porta e o endereço de entrada é o servidor, não o seu código. Escutar em localhost (127.0.0.1) só aceita conexões de dentro do próprio container, então o proxy na frente nunca chega ao seu processo. Fixar a porta no código funciona só até o servidor pedir outra. Por isso os dois exemplos têm um valor padrão para desenvolvimento e aceitam a troca por variável de ambiente. Para entender o conceito, veja o que são variáveis de ambiente.

Segredos como string de conexão e chaves de API seguem a mesma regra: vêm do ambiente, nunca do repositório. No Spring Boot, DB_URL vira ${DB_URL} no application.properties. No .NET, builder.Configuration["DB_URL"] já lê variáveis de ambiente.

Como verificar que o deploy deu certo?#

1. Logs: procure a linha de inicialização, com a porta configurada. No Spring: Tomcat started on port 8080. No .NET: Now listening on: http://0.0.0.0:8080.
2. Endpoint de saúde: curl -i https://seu-dominio/health deve devolver 200 e {"status":"ok"}.
3. Reinício: reinicie a aplicação e confirme que ela volta sozinha e que os logs não mostram requisições interrompidas no meio.
4. Memória: acompanhe o consumo depois de algumas requisições. A JVM e o runtime .NET reservam memória além do que o seu código usa, então o primeiro valor medido costuma ser maior que o esperado.

Quais são os erros mais comuns?#

• Port 8080 was already in use: outro processo usa a porta, ou a plataforma espera outra. Defina PORT e confirme que o código a lê.
• Aplicação sobe, mas o site não abre: o servidor escuta em localhost. No .NET, use 0.0.0.0 em UseUrls.
• no main manifest attribute, in app.jar: o JAR não é executável. Rode o build com o spring-boot-maven-plugin (ou bootJar no Gradle), não com o plugin padrão de JAR.
• UnsupportedClassVersionError: o JAR foi compilado com uma versão do Java mais nova que a do runtime. Use a mesma versão no build e em produção.
• The framework 'Microsoft.AspNetCore.App', version '10.0.0' (x64) was not found: o servidor não tem o ASP.NET Core Runtime dessa versão, ou tem um mais antigo que o TargetFramework do projeto.
• OutOfMemoryError ou o processo morto por falta de RAM: a memória alocada é menor que a necessária. Aumente a RAM da aplicação antes de mexer em flags da JVM.

Antes de abrir para o público, passe pelo checklist de produção de uma API.

Como fazer isso na Square Cloud#

Na Square Cloud o deploy é self-service: você compila, envia e controla tudo. Java e .NET estão entre os diversos runtimes da plataforma, ao lado de Node.js, Python e Go; compile o JAR com a mesma versão do Java do runtime para não esbarrar no UnsupportedClassVersionError. O deploy pode ser por ZIP no painel, pela CLI, pelo GitHub (um push dispara o deploy) ou pela extensão do VS Code.

O arquivo principal é definido no painel ou no squarecloud.app, que guarda nome, arquivo principal, memória e versão. O squarecloud.app é opcional: o painel o gera no deploy, e escrevê-lo na raiz do projeto é a alternativa. As variáveis de ambiente, como a string de conexão do banco, são definidas por aplicação, e a mudança vale no próximo restart, sem rebuild. Quem define a PORT é a plataforma: a aplicação web escuta em 0.0.0.0 nessa porta, como nos dois exemplos. Não há etapa de build na plataforma, então envie o JAR ou a pasta publicada, ou compile num CI externo.

A aplicação roda em um container sempre ligado, sem modo de suspensão. Com o reinício automático (ligado por padrão no deploy pelo painel), ela volta sozinha quando o processo encerra com erro. A RAM do plano é um pool compartilhado entre suas aplicações, com mínimo de 512 MB para uma aplicação web. Toda aplicação web ganha um subdomínio *.squareweb.app com HTTPS, e o domínio personalizado está disponível a partir do plano Standard.

Veja como hospedar APIs na página de APIs, os runtimes na página de runtimes e a API REST e os SDKs oficiais em SDKs.