Como Organizar os Seus Projetos Go Como um Profissional

\ Quando comecei a aprender Go, uma das primeiras perguntas que tive foi:

"Como é que realmente estruturo o meu código?"

Em linguagens como C, é comum colocar tudo num único ficheiro, ou talvez separar os ficheiros de cabeçalho e implementação. Mas em Go, a estrutura do projeto é muito importante: afeta a facilidade com que pode escalar, testar e partilhar o seu código. Neste artigo, vou explicar por que a estrutura é importante, como aceder a funções de diferentes ficheiros e quais as melhores práticas que estou a aprender à medida que avanço.

O Programa Go Mais Simples

Um programa Go pode existir inteiramente num único ficheiro:

package main  import "fmt"  func main() {   fmt.Println("2 + 2 =", 2+2) } 

Isto funciona bem para "hello world" ou experiências rápidas.

Mas assim que adiciona mais funcionalidades (subtração, multiplicação, divisão...), o ficheiro fica confuso e dificilmente escalável.

É aqui que entram os pacotes e pastas do Go.

Introduzindo Pacotes

Em Go, cada ficheiro pertence a um pacote.

Por convenção:

• main → programa executável
• outros (como calculator, utils, etc.) → lógica reutilizável

Aqui está como dividi o projeto da calculadora:

calculator/ │ ├── main.go └── calculator/     └── operations.go 

\

• main.go → gere entrada/saída
• operations.go → define funções como Add, Subtract, etc.

Exemplo: operations.go

package calculator  func Add(a, b int) int {   return a + b }  func Subtract(a, b int) int {   return a - b }  func Multiply(a, b int) int {   return a * b }  func Divide(a, b int) (int, error) {   if b == 0 {     return 0, fmt.Errorf("cannot divide by zero")   }   return a / b, nil } 

Exemplo: main.go

package main  import (   "fmt"   "GoLang-progress/calculator" )  func main() {   fmt.Println("2 + 3 =", calculator.Add(2, 3))   fmt.Println("10 - 4 =", calculator.Subtract(10, 4))   fmt.Println("6 * 7 =", calculator.Multiply(6, 7))    result, err := calculator.Divide(8, 0)   if err != nil {     fmt.Println("Error:", err)   } else {     fmt.Println("8 / 0 =", result)   } } 

Repare como main.go está agora limpo: não se preocupa com a matemática em si, apenas com a forma de a utilizar.

Aceder a Funções de Diferentes Ficheiros

Uma pergunta comum de iniciantes:

"Como chamo uma função de outro ficheiro ou pasta?"

No meu repositório, estruturei-o assim:

calculator/ │ ├── main.go └── internal/     └── calc/         └── operations.go 

Aqui, as funções matemáticas estão em internal/calc.

operations.go (dentro de internal/calc)

\

package calc  import "fmt"  func Add(a, b int) int {   return a + b }  func Divide(a, b int) (int, error) {   if b == 0 {     return 0, fmt.Errorf("cannot divide by zero")   }   return a / b, nil } 

main.go (importando internal/calc)

\

package main  import (   "fmt"   "github.com/turman17/GoLang-progress/calculator/internal/calc" )  func main() {   fmt.Println("2 + 3 =", calc.Add(2, 3))    result, err := calc.Divide(10, 0)   if err != nil {     fmt.Println("Error:", err)   } else {     fmt.Println("10 / 2 =", result)   } } 

Por que este caminho de importação é necessário

A sua importação deve corresponder ao seu caminho do módulo do go.mod mais o caminho da pasta.

No seu repositório, go.mod contém:

module github.com/turman17/GoLang-progress 

O código da calculadora que quer usar está na pasta:

calculator/internal/calc 

Então o caminho completo de importação é:

github.com/turman17/GoLang-progress/calculator/internal/calc 

Algumas notas importantes

• Nome da pasta ≠ nome do pacote → A pasta é internal/calc, mas o pacote dentro é declarado como package calc.
• Importações usam o caminho do módulo → Comece sempre com github.com/... se isso estiver no seu go.mod.
• Internal é especial → Pacotes sob /internal só podem ser importados por código dentro do mesmo módulo.

Erros comuns e correções

❌ import "GoLang-progress/calculator/internal/calc"

→ Falta a organização/nome de utilizador do GitHub. Deve usar o caminho completo.

❌ import "github.com/turman17/GoLang-progress/internal/calc"

→ Falta o diretório calculator no caminho.

❌ go: module not found errors

→ Certifique-se de que go.mod tem module github.com/turman17/GoLang-progress e execute go mod tidy.

Lista de verificação rápida

• go.mod tem a linha de módulo correta
• O diretório é calculator/internal/calc com o pacote calc dentro
• main.go importa github.com/turman17/GoLang-progress/calculator/internal/calc
• Construa a partir da raiz do módulo:

\

go run ./calculator 

ou

go build ./calculator 

Escalando a Estrutura

À medida que os projetos crescem, verá frequentemente este padrão:

project-name/ │ ├── cmd/        → executables (main entrypoints) ├── internal/   → private code (not for external use) ├── pkg/        → reusable packages ├── api/        → API definitions (gRPC, OpenAPI, etc.) └── go.mod 

Para iniciantes, isto pode ser excessivo. Mas à medida que avança para aplicações web, serviços ou ferramentas MLOps, este layout torna-se essencial.

Melhores Práticas que Estou a Aprender

• Manter os pacotes pequenos e focados
• Usar nomes significativos (calc, parser, storage)
• Não fazer engenharia excessiva — comece simples, refatore depois
• Evitar dependências circulares (Go impõe isto)

Lições do Projeto da Calculadora

• Separar a lógica (operations.go) do ponto de entrada (main.go) facilita os testes.
• O tratamento de erros (como divisão por zero) deve ser explícito.
• Os caminhos de importação são realmente importantes — especialmente ao usar internal.

Continuarei a partilhar o que aprendo enquanto exploro Go para MLOps e desenvolvimento backend. A seguir: tratamento de erros e testes em Go.

\ 👉 Veja o meu repositório aqui: https://github.com/turman17/GoLang-progress

E fique atento ao próximo artigo!