golang-normas / projeto-layout

Traduções:

  • 한국어 문서
  • 简体中文
  • 正體中文
  • 简体中文 – ???
  • Français
  • 日本 日
  • português
  • Español

visão geral

esta é uma disposição básica para projetos de Aplicação Go. Não é um padrão oficial definido pela equipe do núcleo Go dev; no entanto, é um conjunto de padrões históricos e emergentes de layout de projetos comuns no ecossistema Go. Alguns destes padrões são mais populares do que outros. Ele também tem uma série de pequenas melhorias, juntamente com vários diretórios de suporte comum a qualquer aplicação grande o suficiente no mundo real.

Se você está tentando aprender Go ou se você está construindo um PoC ou um projeto de brinquedo para si mesmo este layout do projeto é um exagero. Comece com algo realmente simples (um único main.go arquivo é mais do que suficiente). À medida que o seu projeto cresce, tenha em mente que será importante certificar-se de que o seu código está bem estruturado, caso contrário você vai acabar com um código confuso com muitas dependências escondidas e estado global. Quando você tem mais pessoas trabalhando no projeto você vai precisar de ainda mais estrutura. É quando é importante introduzir uma forma comum de gerenciar pacotes/bibliotecas. Quando você tem um projeto de código aberto ou quando você sabe que outros projetos importam o código de seu repositório de projeto que é quando é importante ter pacotes e códigos privados (aka internal). Clonar o repositório, manter o que você precisa e excluir tudo o resto! Lá porque está lá, não significa que tenhas de usar tudo. Nenhum desses padrões são usados em cada projeto. Mesmo o padrãovendor não é universal.

com Go 1.14 Go Modules estão finalmente prontos para a produção. Use Go Modules a menos que você tenha uma razão específica para não usá-los e se você fizer isso, então você não precisa se preocupar com $GOPATH e onde você colocar seu projeto. O arquivo básico go.mod no repo assume que seu projeto está hospedado no GitHub, mas não é um requisito. O caminho do módulo pode ser qualquer coisa, embora o componente do Caminho do primeiro módulo deva ter um ponto no seu nome (a versão actual do Go já não o obriga mais, mas se estiver a usar versões ligeiramente mais antigas não se surpreenda se as suas compilações falharem sem ele). See Issues 37554 and 32819 if you want to know more about it.

esta disposição do projecto é intencionalmente genérica e não tenta impor uma estrutura específica do pacote Go.este é um esforço comunitário. Abra um problema se você ver um novo padrão ou se você acha que um dos padrões existentes precisa ser atualizado.

If you need help with naming, formatting and style style start by running gofmt and golint. Também certifique-se de ler estas orientações do estilo de código Go e recomendações:

  • https://talks.golang.org/2014/names.slide
  • https://golang.org/doc/effective_go.html#names
  • https://blog.golang.org/package-names
  • https://github.com/golang/go/wiki/CodeReviewComments
  • Estilo de orientação para Ir pacotes (rakyll/JBD)

Veja Go Project Layout para obter informações adicionais.

More about naming and organizing packages as well as other code structure recommendations:

  • gophercon EU 2018: Peter Bourgon – Best Practices for Industrial Programming
  • GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen – Go best practices.

  • GopherCon 2017: Edward Muller – Go Anti-Padrões
  • GopherCon 2018: Kat Zien – Como Você Estrutura o Seu Go Aplicativos

Um Chinês Post sobre o Pacote Orientado-as diretrizes de Design e Arquitetura da camada

  • 面向包的设计和架构分层

Ir Diretórios

/cmd

aplicações Principais para este projeto.

o nome de diretório para cada aplicação deve corresponder ao nome do executável que você deseja ter (por exemplo, /cmd/myapp).

não coloque um monte de código no diretório da aplicação. Se você acha que o código pode ser importado e usado em outros projetos, então ele deve viver no diretório /pkg. Se o código não for reutilizável ou se não quiser que outros o reutilizem, coloque esse código no diretório /internal. Você vai se surpreender com o que os outros farão, então seja explícito sobre suas intenções!

É comum ter uma pequena main função que importa e invoca o código de /internal e /pkg diretórios e nada mais.

veja o diretório /cmd para exemplos.

/interno

aplicação privada e código de biblioteca. Este é o código que você não quer que outros importem em suas aplicações ou bibliotecas. Note que este padrão de layout é aplicado pelo próprio compilador Go. Ver o Go 1.4 release notes para mais detalhes. Note que você não está limitado ao nível superior internal diretório. Você pode ter mais de um diretório internal em qualquer nível de sua árvore de projeto.

pode, opcionalmente, adicionar um pouco de estrutura extra aos seus pacotes internos para separar o seu código interno partilhado e não partilhado. Não é necessário (especialmente para projetos menores), mas é bom ter pistas visuais mostrando o uso de pacote pretendido. O actual código do aplicativo pode ir /internal/app diretório (por exemplo, /internal/app/myapp) e o código compartilhado por aqueles apps /internal/pkg diretório (por exemplo, /internal/pkg/myprivlib).

/pkg

código de biblioteca que pode ser usado por aplicações externas (e.g., /pkg/mypubliclib). Outros projetos irão importar essas bibliotecas esperando que elas funcionem, então pense duas vezes antes de colocar algo aqui: -) Note que o diretório internal é uma maneira melhor de garantir que seus pacotes privados não são importáveis, porque é forçado pelo Go. O diretório /pkg ainda é uma boa maneira de comunicar explicitamente que o código nesse diretório é seguro para uso por outros. TheI'll take pkg over internal blog post by Travis Jeffery provides a good overview of thepkg andinternal directories and when it might make sense to use them.

É também uma forma de grupo de código em um único lugar, o seu diretório raiz contém muitos não Vá componentes e diretórios, tornando mais fácil para executar várias ferramentas (como mencionado nestas palestras: Best Practices for Industrial Programming a partir de GopherCon UE 2018, GopherCon 2018: Kat Zien – Como Você Estrutura o Seu Go Apps e GoLab 2018 – Massimiliano Pippi – Projeto de padrões de layout na Go).

veja a pasta /pkg se quiser ver quais os repos de Go populares que usam este padrão de disposição do projecto. Este é um padrão de layout comum, mas não é universalmente aceito e alguns na Comunidade Go não recomendam.

está ok não o usar se o seu projecto da aplicação for realmente pequeno e onde um nível extra de nidificação não adiciona muito valor (a menos que você realmente queira :-)). Pense sobre isso quando ele está ficando grande o suficiente e seu diretório de raiz fica muito ocupado (especialmente se você tem um monte de componentes não-Go app).

/vendor

dependências da aplicação (geridas manualmente ou pela sua ferramenta de gestão de dependências favorita, como a nova funcionalidade embutida emGo Modules). O comando go mod vendor criará o directório /vendor para si. Lembre-se que poderá ter de adicionar o comando -mod=vendor flag ao seu go build se não estiver a usar o comando Go 1.14 onde está por omissão.

não cometa as suas dependências de aplicação se estiver a construir uma biblioteca.

Note que, uma vez que 1.13 Go também activou a funcionalidade de ‘proxy’ do módulo (usando https://proxy.golang.org como servidor ‘proxy’ do módulo por omissão). Leia mais sobre ele here para ver se ele se encaixa todos os seus requisitos e restrições. Se o fizer, então você não precisará do diretório vendor.

Service Application Directories

/ api

OpenAPI / Swagger specs, JSON schema files, protocol definition files.

veja o diretório /api para exemplos.

directórios de aplicações web

/web

componentes específicos de aplicações Web: activos estáticos da web, modelos do servidor e SPAs.

directórios de aplicações comuns

/configus

modelos de ficheiros de configuração ou configurações predefinidas.

P > Put your confdorconsul-template template files here.

/init

System init (systemd, upstart, sysv) e process manager / supervisor (runit, supervisord) configures.

/scripts

Scripts para executar várias operações de compilação, instalação, análise, etc.

estes scripts mantêm o Makefile de nível raiz pequeno e simples (por exemplo, https://github.com/hashicorp/terraform/blob/master/Makefile).

veja o diretório /scripts para exemplos.Embalagem e Integração Contínua.

Put your cloud( AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the /build/package directory.

coloque as configurações e programas do seu CI (travis, circle, drone) no directório/build/ci. Note que algumas das ferramentas de IC (e.g., Travis CI) são muito exigentes sobre a localização de seus arquivos config. Tente colocar os ficheiros de configuração no /build/ci directório ligando-os ao local onde as ferramentas de IC os esperam (quando possível).

/ deployments

IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, mesos, terraform, bosh). Note que em alguns repos (especialmente aplicativos implantados com kubernetes) este diretório é chamado /deploy.aplicações de ensaio externas adicionais e dados de ensaio. Sinta-se à vontade para estruturar a pasta /test à vontade. Para projetos maiores faz sentido ter um subdiretório de dados. Por exemplo, você pode ter /test/data ou /test/testdata se você precisa Ir para ignorar o que está no diretório. Note que Go também irá ignorar diretórios ou arquivos que começam com “.”ou”_”, então você tem mais flexibilidade em termos de como você nomeia seu diretório de dados de teste.

veja o diretório /test para exemplos.

outras pastas

/docs

Design e documentos de utilizador (para além da documentação gerada por godoc).

veja o diretório /docs para exemplos.

/ferramentas

ferramentas de apoio para este projecto. Note que estas ferramentas podem importar código a partir dos diretórios /pkg e /internal.

veja o diretório para exemplos.

/exemplos

exemplos para as suas aplicações e / ou bibliotecas públicas.

veja o diretório /examples para exemplos.

/third_party

ferramentas auxiliares externas, código bifurcado e outros utilitários de terceiros (por exemplo, Swagger UI).ganchos.

/ activos

outros activos para acompanhar o seu repositório (imagens, logotipos, etc.).

/ website

Este é o lugar para colocar os dados do site do seu projeto se você não estiver usando páginas GitHub.

veja o diretório /website para exemplos.

diretórios Você não deveria ter

/src

alguns projetos Go têm umsrc, mas geralmente acontece quando os devs vieram do mundo Java, onde é um padrão comum. Se você pode ajudar a si mesmo a tentar não adotar este padrão Java. Você realmente não quer que o seu código Go ou projectos Go se pareçam com Java: -)

não confunda o nível do projecto /src directory com o /src directory Go usa para os seus espaços de trabalho, como descrito em How to Write Go Code. The $GOPATH environment variable points to your (current) workspace (by default it points to $HOME/go on non-windows systems). Este espaço de trabalho inclui o nível superior /pkg/bin e /src diretórios. O seu projecto actual acaba por ser um sub-directório sob /src, por isso, se tiver o /src directório no seu projecto, a localização do projecto será semelhante a esta: /some/path/to/workspace/src/your_project/src/your_code.go. Note que com Go 1.11 é possível ter o seu projecto fora do seu GOPATH, mas ainda não significa que seja uma boa ideia usar este padrão de layout.

Emblemas

  • Ir Report Card – Ele irá verificar seu código com gofmtgo vetgocyclogolintineffassignlicense e misspell. Substituir github.com/golang-standards/project-layout pela referência do seu projecto.

    Go Report Card

  • GoDoc – It will provide online version of your GoDoc generated documentation. Mude o link para apontar para o seu projeto.

    Go Doc

  • Pkg.Vá.dev-Pkg.Vá.dev is a new destination for Go discovery & docs. Você pode criar um crachá usando a ferramenta de geração de badge.

    Pkgodev

  • Release – It will show the latest release number for your project. Mude o link do github para apontar para o seu projeto.

    Release

Notes

a more opinionated project template with sample / reusable configus, scripts and code is a WIP.

Deixe uma resposta

O seu endereço de email não será publicado.