Como resolver o ciclo de importação em Go

Gabriel Santos — Tue, 20 Jan 2026 18:34:32 +0000

Estava modularizando um projeto pequeno em go e me deparei pela primeira vez com uma mensagem "import cycle not allowed". Passei um bom tempo procurando soluções para esse problema e quebrando a cabeça com os vários níveis de complexidade que esse problema pode ter. Então hoje vou demonstrar as soluções que encontrei, minha opinião sobre cada uma e porque o go está na verdade nos dando uma lição.

O Problema

O erro de "import cycle not allowed" ocorre quando dois ou mais pacotes importam módulos entre si, levando a um ciclo infinito e circular de importações. O compilador go nativamente bloqueia esse comportamento porque com import cycle ele não saberia qual arquivo deve ser renderizado primeiro, uma vez que a ordem de inicialização dos pacotes é determinada pelo grafo de dependências, mas se um depende do outro, por onde começar?

Go nos dando uma lição

O compilador go não bloqueia import cycle apenas porque ele não saberia como lidar (Bom... Talvez esse seja o principal motivo). Mas também porque a linguagem go preza pela simplicidade, clareza, desempenho de compilação e construção de sistemas modulares robustos. Em outras linguagens (como Java ou Python), ciclos de importação são permitidos ou tratados de forma mais permissiva, o que muitas vezes leva ao chamado "Big Ball of Mud" (Grande Bola de Lama). Ao proibir que você compile código com import cycle ele está empurrando pra dentro do seu código o princípio do Directed acyclic graph, ou DAG, que nesse contexto, determina que em uma árvore de arquivos as importações só podem ocorrer de um arquivo para o outro, nunca nos dois sentidos, a fim de garantir que um ciclo não ocorra.

O conceito de DAG é usado em outros âmbitos sociais como da matemática, biologia (evolução, Árvores Genealógicas , epidemiologia) e em ciência da informação. Para a biologia, toda árvore genealógica é uma representação do conceito de DAG, e a consanguinidade é comprovadamente um risco real para más formações nos seres humanos que viessem a seguir (Assim como nosso código se go deixasse compilar!). Poderia citar mais exemplos da implementação de DAG, mas isso se estenderia demais. O fato é que Go não apenas está nos dando uma limitação técnica, está nos ensinando uma lei fundamental para a vida.

Soluções

Tendo em vista o problema e suas causas, vamos falar sobre as soluções para garantir a continuidade do código de acordo com os princípios do Go, e em ordem decrescente de complexidade.

Inversão de Dependências.

Para este caminho, a intenção é "enganar" um dos módulos a fim de substituir o que deveria ser importado. Esse método é um dos mais complexos de se entender inicialmente, mas depois de pensar um bocado se torna fácil de compreender.

Nesse exemplo, package 1 necessita de uma função do package 2, que depende de uma struct do pacote 1 para fazer a tipagem da mesma, resultando em um import cycle. Para resolver, criamos um segundo arquivo do package 2 (ou pode ser no mesmo arquivo), e introduzimos uma interface que define o comportamento esperado da struct do package 1.

Também criamos um Map, do tipo que recebe como chave uma string e como valor uma função, a mesma que o package 1 irá usar. Para que o package 1 use a função do package 2, basta apenas que ele importe o map do package 2 e acesse a função, passando como parâmetro a struct com os métodos corretos. Assim package 2 não depende mais do package 1 para tipagem, apenas de si mesmo, resultando em uma inversão de dependências.

Essa solução só é possível porque em go uma interface pode ser satisfeita por qualquer tipo concreto (struct, int, string, etc..) que implemente todos os métodos definidos nessa interface, sem a necessidade de uma declaração explícita. Isso significa que você não precisa dizer "esta struct x implementa a interface y". Se x tiver os mesmos métodos de y, ela já é um y.

Desvantagens

Implementar em uma interface os mesmos métodos de outra struct pode ser complicado uma vez que esses métodos, sejam complexos demais para ser implementados, ou não compensem o esforço. Nesse caso, outras soluções podem ser mais convenientes para resolver o problema.

Injeção de Dependência

Nesse modo, a ideia é usar outro caminho além da importação, os argumentos de funções.

Neste exemplo, a função do package 2 não é mais importada para ser usada no package 1, o que causaria um import cycle, mas é o package 2 que importa o método que iria usar sua função do package 1. Depois de fazer isso, o package 2 injeta sua função como parâmetro do método, e a distribui para o resto do código, ocasionando assim, uma injeção de dependência. Esse fluxo pode ocorrer de outras formas e direções dentro do código, mas a ideia de injeção de dependência permanece a mesma.

Desvantagem da injeção de Dependência

Essa solução na maioria das vezes pode parecer confusa, bagunçada e até um pouco de over engineering, mas ainda é uma das soluções para resolver o problema de import cycle.

Fusão

Esse método é o mais simples e rápido de todos, sendo a solução que encontrei e julguei melhor para o caso de import cycle que estava enfrentando.

Entenda essa solução como se o Go estivesse te dizendo o seguinte: "Ei, você não acha que está exagerando na modularização? Que tal juntar esses pacotes?". Esse caminho costuma ser o melhor quando o aviso de import cycle ocorre em projetos extremamente pequenos (Como é o caso do meu), e você pretende manter a integridade do código. Aqui basta juntar os dois pacotes conflitantes, e talvez refatorar alguns nomes para manter a legibilidade e manutenção do código.

Desvantagens da fusão

Se feito nos módulos errados, pode gerar acoplamento no código e acabar se tornando um problema para o seu eu futuro! Tome cuidado com esse método.

Conclusão

O erro de import cycle not allowed não deve ser visto como um obstáculo, mas como um mecanismo de feedback do compilador sobre a saúde do seu design de software. Quando Go nos impede de seguir com um ciclo, ele nos força a parar e perguntar: "Essas duas coisas são realmente distintas ou deveriam ser uma só?" ou "Quem realmente deve mandar em quem aqui?".

Resolver um ciclo de importação quase sempre resulta em um código mais testável, desacoplado e fácil de entender. Seja através da inversão de dependências, da injeção ou da simples fusão de pacotes, o objetivo final é o mesmo: manter o fluxo de dependências claro e unidirecional. Da próxima vez que o compilador reclamar, agradeça a ele; ele está impedindo que você crie um "nó" que seria muito mais difícil de desatar no futuro.

Essas são apenas algumas das soluções que existem para esse problema, espero que tenham gostado das que mostrei aqui, obrigado!

Referências

Fixing import cycle in Go. Pergunta. Stack Overflow, 20 jul. 2018. Disponível em: https://stackoverflow.com/questions/50986022/fixing-import-cycle-in-go. Acesso em: 20 jan. 2026.

DIRECTED acyclic graph. In: WIKIPEDIA, the free encyclopedia. [S. l.]: Wikimedia Foundation, 2023. Disponível em: https://en.wikipedia.org/wiki/Directed_acyclic_graph. Acesso em: 20 jan. 2026.

ATWOOD, Jeff. The Big Ball of Mud and Other Architectural Disasters. Coding Horror, 26 out. 2007. Disponível em: https://blog.codinghorror.com/the-big-ball-of-mud-and-other-architectural-disasters/. Acesso em: 20 jan. 2026.

How I Reduced Friction in My Studies Using AI, Rust, and Obsidian.

Gabriel Santos — Fri, 09 Jan 2026 22:15:44 +0000

Every student knows: note-taking is fundamental for retention, but the act of formatting notes often consumes more energy than the learning itself. I found myself stuck in a cycle where research flowed smoothly, but documentation in Obsidian was a manual bottleneck.

Initially, I researched, practiced, and took notes manually. I tried using AI to generate summaries, but the "Copy from Chat -> Open Obsidian -> Create File -> Paste" process was still too slow. When I had 10 topics to study, I ended up giving up on the notes halfway through.

With that, I had the idea to further automate the note-taking process. I decided to create an application that does this automatically, and all I need to do for it to work is give it the name of the subject I want to summarize. Thus, noteap was born.

The Solution: The Noteap Ecosystem

To automate this, I divided the problem into three layers:

The Interface (React Native): A simple app where I just type the topic (e.g., "Rust Ownership"). No distractions.
The Brain (Node.js + Gemini AI): A server that receives the topic, uses prompt engineering to generate a structured Markdown with code examples, and saves everything in a MongoDB database.
The Synchronizer (Rust): Here's the key difference. I developed a Rust client that runs on my desktop. It retrieves pending notes from the server, converts them into .md files, and injects them directly into my "New Notes" folder in Obsidian.

Why Rust in the Client?

I chose Rust for its performance and the ease of generating a single binary. It starts with the system, consumes irrelevant resources, and ensures that when I open my computer to review, my notes from the previous session are already there, waiting for me. Why not choose C, C++, or Go? Both generate a single binary and are good languages, and the answer lies in the cost-complexity-performance ratio. Of these languages, I believe Rust is the one that maintains the most user-friendly syntax despite being low-level, and with good performance, which is why it was chosen.

Deployment

To keep the server always online, I put it running inside a Docker container on my AWS EC2 server, so I just need to grab the URL to use it with the other applications in the project.

Beyond Cognitive Load

According to Annie Piolat, in her study "Cognitive effort during note taking," note-taking is one of the most demanding mental tasks, consuming immense cognitive effort. Often, the act of formatting notes and organizing files consumes more energy than the learning itself, creating what I call "documentation friction."

By automating this workflow, I'm not just "saving time," I'm preserving my mental energy.

Automation has given me back the time I used to spend on formatting, allowing me to apply the effort that Piolat describes to active review and practical application, and not to the bureaucracy of paper (or the .md file).

And you? How do you manage your time and your notes? Have you ever tried to automate this process?

References

PIOLAT, A.; OLIVE, T.; KELLOGG, R. T. Cognitive effort during note taking. Applied Cognitive Psychology, 2005. (Base article on mental effort in note taking).

Forem: Gabriel Santos