Este repositório apresenta um Laboratório de Desenvolvimento focado em resolver problemas de Dívida Técnica e Fricção de Setup no time de desenvolvimento, especialmente em ambientes legados ou com infraestrutura compartilhada.
A solução principal demonstra como padronizar o ambiente de desenvolvimento para garantir segurança, consistência e alta Experiência do Desenvolvedor, utilizando ferramentas modernas em conjunto com código Go.
A principal dívida técnica abordada é a dificuldade em disponibilizar um ambiente de desenvolvimento de fácil acesso, rápido e seguro para o desenvolvedor. Projetos legados frequentemente exigem versões específicas de linguagens, bibliotecas de sistema ou ferramentas de terceiros, tornando o onboarding e o desenvolvimento diário lentos e frustrantes.
Os caminhos tradicionais para contornar essa fricção (configuração manual de ambiente local) são geralmente longos, cheios de bloqueios (dependência de outras equipes ou administradores), parciais (o ambiente local nunca é 100% igual ao de produção) e inseguros (poluindo a máquina do desenvolvedor). Nosso objetivo é eliminar esse atrito inteiramente.
Disponibilizar uma imagem Docker focada estritamente em desenvolvimento, contendo todas as dependências necessárias, e emparelhá-la com o plugin Dev Containers (ms-vscode-remote.remote-containers) do Visual Studio Code.
Isso garante:
- Plug-and-Play: O desenvolvedor clona o repo e inicia o desenvolvimento em segundos.
- Produtividade: Utilização do Language Server gopls na versão correta dentro do contêiner, garantindo autocomplete, navegação e refatoração inteligentes e seguras.
- Debug Transparente: Capacidade de usar o debugger nativo do VS Code (
delve) como se o código estivesse local, mas executando com as dependências exatas do ambiente contêinerizado.
Esta técnica de ambiente é agnóstica à linguagem e requer apenas a existência de um arquivo de gerenciamento de pacote (ex: go.mod para Go) e acesso às configurações mínimas de ambiente (ex: variáveis de ambiente, URLs de APIs) para gerar a imagem Docker de desenvolvimento.
Embora o foco principal seja o ambiente de desenvolvimento, o código da aplicação alvo (cloud-native-dev-lab) adere a padrões avançados de engenharia de software para garantir longevidade e manutenibilidade, minimizando a dívida técnica futura.
-
🐳 VS Code Dev Containers: A configuração
devcontainer.jsongarante que o desenvolvedor provisione automaticamente um espaço de trabalho isolado com a versão exata de Go legada necessária. -
⚙️ Flexibilidade na Gestão de Configuração:
- O arquivo
devcontainer.jsonpermite a passagem de variáveis de ambiente diretamente para o ambiente de desenvolvimento contêinerizado. - Isso permite que a configuração da aplicação permaneça em uma camada externa, concedendo a flexibilidade de replicar cenários de produção no ambiente de desenvolvimento de forma segura e fácil, adaptando-se a várias necessidades corporativas.
- O arquivo
-
🧠
goplsOtimizado para Código Legado: O ambiente configura explicitamente uma versão compatível dogopls, garantindo recursos modernos de IDE para o runtime Go legado. -
🐞 Debug Transparente: O debugger do VS Code se integra de forma transparente com o Dev Container para uma experiência de máquina local.
- Arquitetura Limpa (Ports & Adapters): A lógica de negócio (pacote
service) é estritamente desacoplada de detalhes de infraestrutura (pacoteclient). - Erros Tipados: O Adaptador traduz erros técnicos de infraestrutura para Erros Tipados em Go (
client.ErrNotFound). A Camada de Serviço usaerrors.Is()para identificar o erro e responder com um status de negócio seguro. - Propagação de Contexto: Uso obrigatório de
context.Contextpara propagar sinais de timeout e cancelamento em toda a cadeia de execução. - Design de Interface: Crucialmente, o Design de Interface Go (Port) adere ao Princípio da Segregação de Interfaces (ISP). Ao definir um contrato enxuto e intencional (
PokemonProvider), garantimos máxima testabilidade e evitamos que o domínio dependa de métodos ou dados que ele não exija estritamente.
O Makefile serve como o motor de automação crucial para o projeto. Sua importância reside na padronização de tarefas comuns de desenvolvimento e QA, garantindo que cada desenvolvedor execute os mesmos comandos da mesma maneira, seja localmente ou dentro do Dev Container. Essa consistência é vital para a garantia de qualidade reprodutível.
| Alvo do Makefile | Descrição |
|---|---|
make install |
Instala as ferramentas Go necessárias (linters, static analyzers) dentro do ambiente. |
make test |
Executa todos os testes unitários com saída verbosa e relatório de cobertura. |
make cover |
Abre o relatório de cobertura de teste no navegador para análise visual. |
make lint |
Executa todas as verificações de análise estática e linters configurados (ex: golangci-lint). |
make build |
Compila o binário da aplicação Go. |
make clean |
Remove binários compilados e arquivos intermediários. |
Mesmo que a conformidade arquitetural não tenha sido o foco principal, as decisões de design tomadas (Go, containers, injeção de dependência) alinham a aplicação com os princípios essenciais da metodologia Twelve-Factor App. Isso garante que, além da ótima Experiência do Desenvolvedor, a aplicação resultante seja inerentemente escalável, portátil e resiliente em um ambiente Cloud-Native.
| Fator | Status no Projeto |
|---|---|
| I. Código Base | Contemplado |
| II. Dependências | Contemplado |
| III. Configuração | Contemplado |
| IV. Serviços de Apoio | Implícito |
| V. Build, Release, Run | Implícito |
| VI. Processos | Implícito |
| VII. Ligação de Porta | Implícito |
| VIII. Concorrência | Contemplado |
| IX. Descartabilidade | Contemplado |
| X. Paridade Dev/Prod | Contemplado |
| XI. Logs | Parcialmente |
| XII. Processos de Administração | N/A |
A arquitetura da aplicação (Ports & Adapters) e o uso disciplinado de Interfaces Go fornecem forte conformidade com os princípios fundamentais de design orientado a objetos (SOLID), resultando em código altamente manutenível e testável.
| Princípio | Status no Projeto |
|---|---|
| Single Responsibility (SRP) | Contemplado |
| Open/Closed (OCP) | Contemplado |
| Liskov Substitution (LSP) | Contemplado |
| Interface Segregation (ISP) | Contemplado |
| Dependency Inversion (DIP) | Contemplado |
- Validação de Erro Orientada a Testes: Todos os componentes utilizam Testes Orientados a Tabela (TDT). Os testes afirmam o tipo de erro usando
errors.Is. - Alta Cobertura: A implementação atinge 100% de cobertura de teste no Adaptador (
client), validando a lógica abrangente de tradução de erros.
Este laboratório foi construído em um contexto deliberadamente reduzido e simplificado para ilustrar os conceitos arquiteturais centrais. Cenários do mundo real provavelmente exigirão configurações e alterações adicionais com base em padrões corporativos específicos, infraestrutura existente e nuances operacionais.
Nota sobre Ferramentas de Garantia de Qualidade: As versões e configurações específicas de ferramentas automatizadas de QA (linters, analisadores estáticos) podem exigir ajustes com base em requisitos de validação externos, como o Git flow definido por uma empresa ou padrões de Integração Contínua (CI). O engenheiro de software responsável deve avaliar e adaptar o uso dessas ferramentas às necessidades específicas do projeto.
Aceitamos contribuições! Se você identificar alguma correção, melhoria ou abordagem alternativa de melhores práticas, teremos o prazer de receber sua contribuição via Pull Request.
Este documento foi criado pelo Google Gemini.