Go reclama "undefined" para função de outro arquivo? Entendendo

Função "Indefinida" em Go: como fazer os arquivos se entenderem e não enlouquecer

Imagine: você está escrevendo um programa em Go, divide o código em arquivos lógicos (por exemplo, main.go e helper.go), executa go run main.go — e o compilador exibe um gelado: "undefined: MyFunction". Familiar? Esta pergunta é uma das mais populares no Stack Overflow (milhares de visualizações!), e hoje vamos entendê-la de uma vez por todas.

Por que o Go, que é famoso por sua simplicidade, de repente não vê uma função de um arquivo vizinho? Não é mágica, mas sim regras estritas de organização de código. Vamos percorrer todos os cenários — desde o erro clássico de iniciante até o trabalho correto com módulos.

Cenário 1: Clássico — esqueceu de especificar todos os arquivos ao executar

O caso mais comum. Você escreve:

// main.go\npackage main\n\nfunc main() {\n    printHello() // Erro: undefined: printHello\n}\n

// helper.go\npackage main\n\nimport "fmt"\n\nfunc printHello() {\n    fmt.Println("Hello!")\n}\n

E executa apenas go run main.go. O Go não vê helper.go, porque você não o especificou explicitamente. A solução correta:

go run main.go helper.go\n// ou mais simples:\ngo run .\n

Por que isso acontece? O Go não escaneia o diretório automaticamente — você deve listar todos os arquivos do pacote. O comando go run . executa toda a pasta atual como um único pacote.

Cenário 2: Pacotes diferentes — invisibilidade por padrão

Outra armadilha popular é tentar chamar uma função de outro pacote sem importação e exportação.

// main.go\npackage main\n\nfunc main() {\n    helper.DoSomething() // Erro: undefined: helper\n}\n

// helper/helper.go\npackage helper\n\nfunc DoSomething() {\n    // ...\n}\n

Aqui há dois problemas:

\n
• Os arquivos estão em pacotes diferentes (main e helper).
\n
• A função DoSomething não foi exportada (começa com letra minúscula).
\n

Versão corrigida:

// main.go\npackage main\n\nimport "yourmodule/helper"\n\nfunc main() {\n    helper.DoSomething() // Funciona!\n}\n

// helper/helper.go\npackage helper\n\nfunc DoSomething() { // Letra maiúscula!\n    // ...\n}\n

Lembre-se: Em Go, apenas entidades com letra maiúscula são exportadas. Letra minúscula significa privado para o pacote.

Cenário 3: Problemas com módulos e GOPATH

Se você está usando o estilo antigo (GOPATH) ou inicializou o módulo incorretamente, o Go pode não encontrar seus arquivos, mesmo na mesma pasta.

Verifique:

\n
1. Existe um arquivo go.mod na raiz do projeto? Se não, crie: go mod init nome_do_modulo.
\n
2. Você não está armazenando o projeto dentro de $GOPATH/src sem um módulo? Isso é um modo legado que pode causar confusão.
\n
3. Certifique-se de que todos os arquivos na pasta têm o mesmo package (exceto arquivos de teste com o sufixo _test).
\n

Exemplo de estrutura correta:

myproject/\n├── go.mod          # module myproject\n├── main.go         # package main\n└── helper.go       # package main\n

Cenário 4: Nomes de arquivos com sublinhados e arquivos de teste

O Go ignora arquivos que começam com _ ou . (por exemplo, _hidden.go). E arquivos com o sufixo _test.go são compilados apenas ao executar testes (go test). Se você acidentalmente nomeou um arquivo de trabalho como helper_test.go — suas funções não serão visíveis no código principal.

Cenário 5: Dependências cíclicas

Às vezes, o erro "undefined" pode ser consequência de uma importação cíclica. Por exemplo, o pacote A importa B, e B importa A. O Go proíbe esses ciclos e m