Nomenclatura de Pacotes e Diretórios internal/

Nomes de pacotes e layout de diretórios Go comunicam a intenção antes que um leitor abra um arquivo.

Nomes curtos e consistentes, mais diretórios internal/, mantêm as APIs públicas honestas e permitem que o compilador imponha limites.

Resumo

Nomes de pacotes devem ser em minúsculas, concisos e descritivos, sem repetição redundante.

Caminhos de importação carregam o prefixo do módulo; cláusulas de pacote nomeiam a unidade compilada.

O nome especial internal restringe importações a diretórios ancestrais dentro da mesma árvore de módulos.

Essa combinação reduz o acoplamento acidental e torna os refators mais seguros para autores de bibliotecas.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

// example.com/widget/internal/parser/parser.go
package parser // não package widgetparser
 
import "strings"
 
func Parse(raw string) (string, error) {
    return strings.TrimSpace(raw), nil
}

// example.com/widget/api/handler.go
package api
 
import "example.com/widget/internal/parser"
 
func Handle(raw string) (string, error) {
    return parser.Parse(raw)
}

Quando usar isso:

• Ao nomear um novo pacote com base em sua função (auth, store, parser), não no nome do repositório.
• Ao colocar detalhes de implementação em internal/ quando módulos externos não devem importá-los.
• Ao dividir binários de cmd/ de pacotes reutilizáveis no mesmo módulo.
• Ao revisar importações em CI com go list ou linters que sinalizam caminhos repetitivos.

Exemplo de Trabalho

example.com/checkout/
  go.mod
  cmd/checkoutd/main.go
  checkout/          // tipos de domínio - o caminho de importação termina em /checkout
    checkout.go
  internal/
    tax/
      tax.go
    payment/
      payment.go
  api/
    http.go

// checkout/checkout.go
package checkout
 
type Cart struct {
    Items []string
}

// internal/tax/tax.go
package tax
 
func Rate(region string) float64 {
    if region == "CA" {
        return 0.0725
    }
    return 0
}

// api/http.go
package api
 
import (
    "example.com/checkout/checkout"
    "example.com/checkout/internal/tax"
)
 
func Quote(c checkout.Cart, region string) float64 {
    return tax.Rate(region) * float64(len(c.Items))
}

O que isso demonstra:

• Tipos de domínio públicos vivem em um pacote de nível superior com um nome claro.
• internal/tax pode ser chamado de api/ porque api está sob o pai internal example.com/checkout.
• Módulos externos podem importar checkout e api, mas não internal/tax.

Mergulho Profundo

Como Funciona

• Nomes de pacotes aparecem em identificadores qualificados (tax.Rate).

Nomes curtos são fáceis de ler nos locais de chamada porque o caminho de importação já fornece contexto.

• O compilador permite internal apenas quando o pacote importador está abaixo do diretório que contém a pasta internal.

Para .../checkout/internal/tax, os importadores devem residir sob .../checkout/.

• Múltiplos pacotes em um módulo recebem seu próprio subdiretório; você não pode misturar package foo e package bar na mesma pasta.

Regras de Nomenclatura em Resumo

internal/ vs pkg/

pkg/ não oculta símbolos.

Se você precisar de garantias fortes, use internal/.

Notas Go

// Ruim: repetição no local de chamada quando a importação é renomeada incorretamente
import checkoutinternal "example.com/checkout/internal/checkout"
 
// Bom: detalhe interno com nome de pacote curto
import "example.com/checkout/internal/tax"

// internal/ aninhado ainda mais fundo funciona - a regra é por diretório internal
// example.com/checkout/internal/payment/gateway/gateway.go
package gateway

Armadilhas

• Caminho de importação vs. nome do pacote: a incompatibilidade confunde os leitores. Mantenha-os alinhados, exceto para main e casos bem conhecidos da biblioteca padrão.
• internal é baseado em caminho, não em visibilidade. Identificadores em minúsculas já são privados do pacote; internal/ bloqueia importações entre módulos completamente.
• Mover código de público para internal/ é uma alteração que quebra a compatibilidade para quem importou o caminho antigo.
• Nomes de pastas genéricos (utils) se tornam gavetas de bagunça. Divida por responsabilidade em vez disso.
• Pacotes de teste package foo_test ficam ao lado de foo e são um pacote separado para testes de caixa preta.

Alternativas

• Múltiplos módulos - Limites de lançamento mais fortes do que internal/ quando as equipes precisam de semver separado.
• Workspaces Go - Desenvolvimento local entre módulos sem expor pacotes privados.
• Pacotes públicos apenas com interfaces - Superfície exportada pequena com implementação em tipos não exportados (ainda não é um substituto para internal/ entre módulos).

FAQs

Relacionados

• Pacotes e Módulos: A Unidade de Distribuição do Go - Caminhos de módulo e caminhos de importação
• Layout Padrão de Projetos para Serviços e Bibliotecas - Posicionamento de cmd, internal, pkg
• Ciclos de Importação, Importações Vazias e Importações de Ponto - Padrões de importação e ciclos
• Noções Básicas de Pacotes e Módulos - Exemplos executáveis de nomenclatura e internal

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).