Aula 1 de 2 · 45 min

Como uma aplicação Go funciona

Siga a inicialização de um programa Go até uma requisição HTTP chegar ao handler e receber uma resposta.

Etapa 1 de 6

De onde o programa começa?

Em Go, um executável começa em um pacote chamado main, que declara uma função main sem parâmetros e sem retorno. Quando você executa go run ./cmd/api, o comando compila os pacotes necessários e inicia o processo. Depois da inicialização do runtime, a execução chega à função main.

A função main é o ponto em que a aplicação monta suas dependências e inicia o trabalho principal. Neste exemplo, ela vai criar um roteador HTTP, registrar uma rota e iniciar um servidor.

Etapa 2 de 6

Como organizar os arquivos

A organização abaixo separa o ponto de entrada da rota HTTP. O diretório cmd/api contém o executável. internal/health agrupa o código da rota de saúde. O arquivo go.mod declara o módulo e a versão da linguagem usada pelo projeto.

cmd e internal são convenções de organização. A regra especial é internal: o Go impede que pacotes fora do diretório pai que contém esse internal importem os pacotes que estão dentro dele.

Estrutura do projeto · text
go.mod
cmd/
└── api/
    └── main.go
internal/
└── health/
    └── routes.go

O nome learning.local/gohealth usado no go.mod é o caminho do módulo deste exemplo. O import de internal/health usa esse mesmo prefixo. Em um projeto próprio, o caminho deve corresponder ao módulo declarado pelo repositório.

Etapa 3 de 6

O handler recebe a requisição

Um handler HTTP recebe dois valores: http.ResponseWriter, por onde escreve a resposta, e *http.Request, que descreve a requisição recebida. O * indica um ponteiro para uma requisição; a biblioteca entrega esse objeto ao handler.

RegisterRoutes recebe o roteador e registra o caminho /health. A função health aceita somente GET. Para outro método, define o cabeçalho Allow, responde com status 405 e encerra a função com return.

Na resposta de sucesso, o cabeçalho precisa ser definido antes de WriteHeader: a primeira escrita envia os cabeçalhos e o status ao cliente. fmt.Fprintln escreve ok seguido de uma quebra de linha e informa se houve erro ao escrever.

internal/health/routes.go · go
package health

import (
	"fmt"
	"log"
	"net/http"
)

func RegisterRoutes(mux *http.ServeMux) {
	mux.HandleFunc("/health", health)
}

func health(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodGet {
		w.Header().Set("Allow", http.MethodGet)
		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
		return
	}

	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	w.WriteHeader(http.StatusOK)
	if _, err := fmt.Fprintln(w, "ok"); err != nil {
		log.Printf("write health response: %v", err)
	}
}

http.Handler é uma interface da biblioteca padrão cujo contrato exige o método ServeHTTP(http.ResponseWriter, *http.Request). ServeMux implementa esse contrato para encaminhar requisições. HandleFunc recebe uma função com a assinatura do handler e a registra no roteador.

Consulte handlers HTTP em Go e métodos e tipos para ver os contratos e as regras de métodos com mais detalhe.

Quiz da etapa

Atividade educativa; respostas e resultado ficam apenas neste navegador.

O que `http.Handler` exige de um tipo?

Etapa 4 de 6

Conectando as partes em main

O pacote main importa internal/health, cria o roteador e pede ao pacote de saúde que registre sua rota. Assim, main decide quais componentes participam da aplicação; o pacote health conhece a rota que implementa.

O campo Handler do servidor recebe o roteador porque *http.ServeMux implementa a interface http.Handler. O servidor não precisa conhecer os detalhes de cada rota.

go.mod · text
module learning.local/gohealth

go 1.22
cmd/api/main.go · go
package main

import (
	"errors"
	"log"
	"net/http"

	"learning.local/gohealth/internal/health"
)

func main() {
	mux := http.NewServeMux()
	health.RegisterRoutes(mux)

	server := &http.Server{
		Addr:    ":8080",
		Handler: mux,
	}

	log.Println("servidor iniciado em :8080")
	if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}

O & cria um ponteiro para o valor http.Server{...}. Por isso, a variável server tem o tipo *http.Server. ListenAndServe tem receptor ponteiro, e Go permite chamar o método com server.ListenAndServe() sem escrever (*server).ListenAndServe().

O literal configura Addr e Handler; os demais campos permanecem com seus valores zero. O ponteiro não significa que o valor será necessariamente alocado no heap: o compilador decide onde ele deve viver. Veja ponteiros e endereços e literais compostos.

ListenAndServe inicia a escuta e bloqueia a execução enquanto o servidor atende conexões. Se ocorrer um erro de encerramento, errors.Is compara o erro com http.ErrServerClosed; erros inesperados são registrados por log.Fatal.

Etapa 5 de 6

O caminho de uma requisição

Depois que o servidor começa a escutar, uma requisição percorre estas partes:

  1. O cliente envia GET /health para a porta 8080.
  2. O servidor HTTP transforma os dados recebidos em um *http.Request.
  3. O ServeMux compara o caminho com as rotas registradas.
  4. O handler health verifica o método e escreve status, cabeçalhos e corpo.
  5. O servidor envia a resposta ao cliente.

O fluxo ajuda a localizar responsabilidades: main conecta o servidor ao roteador, ServeMux escolhe o handler, e o handler produz a resposta da rota. A função main fica parada dentro de ListenAndServe enquanto o servidor está ativo.

Etapa 6 de 6

Desafio: verifique o estado do servidor

Quiz final

Atividade educativa; respostas e resultado ficam apenas neste navegador.

Qual declaração marca o ponto de entrada de um executável Go?
Qual é o papel de `ServeMux` neste exemplo?
O que `&http.Server{Addr: ":8080"}` produz?