# 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.

**Trilha:** [Go por Dentro — Entenda a linguagem além da sintaxe](../../go-por-dentro.md) · **Aula:** 1 · **Duração:** 45 minutos

## Etapas

## Etapa 1: 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.

> **Comando e diretório:** `go run ./cmd/api` espera que exista um pacote executável nessa pasta. Se o terminal já estiver dentro de `cmd/api`, o comando equivalente é `go run .`.

## Etapa 2: 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: 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](/reference/go/http-handlers-and-middleware) e [métodos e tipos](/reference/go/methods-and-types) para ver os contratos e as regras de métodos com mais detalhe.

### Quiz (100% para aprovação recomendada)

1. O que `http.Handler` exige de um tipo?
   - a) Um método ServeHTTP(http.ResponseWriter, *http.Request)
   - b) Uma função main com dois parâmetros
   - c) Um método chamado HandleFunc
   - **Resposta:** a
   - **Explicação:** `ServeHTTP` é o único método do contrato `http.Handler`. `HandleFunc` é um método de `ServeMux`, e `main` pertence ao ponto de entrada de um executável.

## Etapa 4: 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](/reference/go/pointers) e [literais compostos](/reference/go/composite-literals).

`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: 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: Desafio: verifique o estado do servidor

### Desafio: Teste GET e um método não permitido

Execute `go run ./cmd/api`. Faça uma requisição GET para `http://localhost:8080/health` e confirme status 200 com corpo `ok`. Depois envie POST para a mesma rota: a resposta deve ser 405 e incluir `Allow: GET`. Explique qual arquivo conecta o roteador ao servidor e qual função atende a rota.

<details>
<summary>Solução possível</summary>

O handler já implementa os dois casos em `internal/health/routes.go`. Depois de iniciar a aplicação, você pode conferir com:

```sh
curl -i http://localhost:8080/health
curl -i -X POST http://localhost:8080/health
```

A rota é registrada por `RegisterRoutes`. `cmd/api/main.go` cria o `ServeMux`, registra as rotas e fornece o mux ao `http.Server`.

</details>

### Quiz (70% para aprovação recomendada)

1. Qual declaração marca o ponto de entrada de um executável Go?
   - a) Um pacote main com uma função main sem parâmetros e sem retorno
   - b) Qualquer arquivo chamado main.go, mesmo sem package main
   - c) Uma função init dentro de qualquer pacote
   - **Resposta:** a
   - **Explicação:** O executável é declarado no pacote `main`, que precisa fornecer `func main()`. O nome do arquivo pode ser outro; `init` executa durante a inicialização dos pacotes e não substitui `main`.

2. Qual é o papel de `ServeMux` neste exemplo?
   - a) Selecionar o handler registrado para o caminho da requisição
   - b) Compilar o código Go ao receber cada requisição
   - c) Criar a resposta sem chamar um handler
   - **Resposta:** a
   - **Explicação:** `ServeMux` associa padrões a handlers e encaminha cada requisição compatível. A compilação ocorre antes do processo atender as requisições.

3. O que `&http.Server{Addr: ":8080"}` produz?
   - a) Um ponteiro para o valor criado pelo literal composto
   - b) Uma chamada automática ao construtor do servidor
   - c) A garantia de que o valor ficará no heap
   - **Resposta:** a
   - **Explicação:** `&` obtém o endereço do valor composto. Go não chama um construtor automaticamente nesse código, e a decisão de heap ou stack depende da análise de escape do compilador.

