├── .editorconfig ├── .gitattributes ├── .gitignore ├── LICENSE.md ├── Makefile ├── README.md ├── README_be.md ├── README_es.md ├── README_fa.md ├── README_fr.md ├── README_hi.md ├── README_id.md ├── README_it.md ├── README_ja.md ├── README_ko.md ├── README_ptBR.md ├── README_ro.md ├── README_ru.md ├── README_tr.md ├── README_ua.md ├── README_vi.md ├── README_zh-CN.md ├── README_zh-TW.md ├── README_zh.md ├── api └── README.md ├── assets └── README.md ├── build ├── README.md ├── ci │ └── .keep └── package │ └── .keep ├── cmd ├── README.md └── _your_app_ │ └── .keep ├── configs └── README.md ├── deployments └── README.md ├── docs └── README.md ├── examples └── README.md ├── githooks └── README.md ├── go.mod ├── init └── README.md ├── internal ├── README.md ├── app │ └── _your_app_ │ │ └── .keep └── pkg │ └── _your_private_lib_ │ └── .keep ├── pkg ├── README.md └── _your_public_lib_ │ └── .keep ├── scripts └── README.md ├── test └── README.md ├── third_party └── README.md ├── tools └── README.md ├── vendor └── README.md ├── web ├── README.md ├── app │ └── .keep ├── static │ └── .keep └── template │ └── .keep └── website └── README.md /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | charset = utf-8 5 | end_of_line = lf 6 | insert_final_newline = true 7 | trim_trailing_whitespace = true 8 | 9 | [{*.go,Makefile,.gitmodules,go.mod,go.sum}] 10 | indent_style = tab 11 | 12 | [*.md] 13 | indent_style = tab 14 | trim_trailing_whitespace = false 15 | 16 | [*.{yml,yaml,json}] 17 | indent_style = space 18 | indent_size = 2 19 | 20 | [*.{js,jsx,ts,tsx,css,less,sass,scss,vue,py}] 21 | indent_style = space 22 | indent_size = 4 23 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | * -text 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Mac OS X files 2 | .DS_Store 3 | 4 | # Binaries for programs and plugins 5 | *.exe 6 | *.exe~ 7 | *.dll 8 | *.so 9 | *.dylib 10 | 11 | # Test binary, build with `go test -c` 12 | *.test 13 | 14 | # Output of the go coverage tool, specifically when used with LiteIDE 15 | *.out 16 | 17 | # Project-local glide cache, RE: https://github.com/Masterminds/glide/issues/736 18 | .glide/ 19 | 20 | # Dependency directories (remove the comment below to include it) 21 | # vendor/ 22 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Hacker license! 2 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # note: call scripts from /scripts 2 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Standard Go Project Layout 2 | 3 | Translations: 4 | 5 | * [한국어 문서](README_ko.md) 6 | * [简体中文](README_zh.md) 7 | * [正體中文](README_zh-TW.md) 8 | * [简体中文](README_zh-CN.md) - ??? 9 | * [Français](README_fr.md) 10 | * [日本語](README_ja.md) 11 | * [Português](README_ptBR.md) 12 | * [Español](README_es.md) 13 | * [Română](README_ro.md) 14 | * [Русский](README_ru.md) 15 | * [Türkçe](README_tr.md) 16 | * [Italiano](README_it.md) 17 | * [Tiếng Việt](README_vi.md) 18 | * [Українська](README_ua.md) 19 | * [Indonesian](README_id.md) 20 | * [हिन्दी](README_hi.md) 21 | * [فارسی](README_fa.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## Overview 25 | 26 | This is a basic layout for Go application projects. Note that it's basic in terms of content because it's focusing only on the general layout and not what you have inside. It's also basic because it's very high level and it doesn't go into great details in terms of how you can structure your project even further. For example, it doesn't try to cover the project structure you'd have with something like Clean Architecture. 27 | 28 | This is **`NOT an official standard defined by the core Go dev team`**. This is a set of common historical and emerging project layout patterns in the Go ecosystem. Some of these patterns are more popular than others. It also has a number of small enhancements along with several supporting directories common to any large enough real world application. Note that the **core Go team provides a great set of general guidelines about structuring Go projects** and what it means for your project when it's imported and when it's installed. See the [`Organizing a Go module`](https://go.dev/doc/modules/layout) page in the official Go docs for more details. It includes the `internal` and `cmd` directory patterns (described below) and other useful information. 29 | 30 | **`If you are trying to learn Go or if you are building a PoC or a simple project for yourself this project layout is an overkill. Start with something really simple instead (a single `main.go` file and `go.mod` is more than enough).`** As your project grows keep in mind that it'll be important to make sure your code is well structured otherwise you'll end up with a messy code with lots of hidden dependencies and global state. When you have more people working on the project you'll need even more structure. That's when it's important to introduce a common way to manage packages/libraries. When you have an open source project or when you know other projects import the code from your project repository that's when it's important to have private (aka `internal`) packages and code. Clone the repository, keep what you need and delete everything else! Just because it's there it doesn't mean you have to use it all. None of these patterns are used in every single project. Even the `vendor` pattern is not universal. 31 | 32 | With Go 1.14 [`Go Modules`](https://go.dev/wiki/Modules) are finally ready for production. Use [`Go Modules`](https://blog.golang.org/using-go-modules) unless you have a specific reason not to use them and if you do then you don’t need to worry about $GOPATH and where you put your project. The basic `go.mod` file in the repo assumes your project is hosted on GitHub, but it's not a requirement. The module path can be anything though the first module path component should have a dot in its name (the current version of Go doesn't enforce it anymore, but if you are using slightly older versions don't be surprised if your builds fail without it). See Issues [`37554`](https://github.com/golang/go/issues/37554) and [`32819`](https://github.com/golang/go/issues/32819) if you want to know more about it. 33 | 34 | This project layout is intentionally generic and it doesn't try to impose a specific Go package structure. 35 | 36 | This is a community effort. Open an issue if you see a new pattern or if you think one of the existing patterns needs to be updated. 37 | 38 | If you need help with naming, formatting and style start by running [`gofmt`](https://golang.org/cmd/gofmt/) and [`staticcheck`](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck). The previous standard linter, golint, is now deprecated and not maintained; use of a maintained linter such as staticcheck is recommended. Also make sure to read these Go code style guidelines and recommendations: 39 | * https://talks.golang.org/2014/names.slide 40 | * https://golang.org/doc/effective_go.html#names 41 | * https://blog.golang.org/package-names 42 | * https://go.dev/wiki/CodeReviewComments 43 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 44 | 45 | See [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) for additional background information. 46 | 47 | More about naming and organizing packages as well as other code structure recommendations: 48 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 49 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 50 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 51 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 52 | 53 | A Chinese post about Package-Oriented-Design guidelines and Architecture layer 54 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 55 | 56 | ## Go Directories 57 | 58 | ### `/cmd` 59 | 60 | Main applications for this project. 61 | 62 | The directory name for each application should match the name of the executable you want to have (e.g., `/cmd/myapp`). 63 | 64 | Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions! 65 | 66 | It's common to have a small `main` function that imports and invokes the code from the `/internal` and `/pkg` directories and nothing else. 67 | 68 | See the [`/cmd`](cmd/README.md) directory for examples. 69 | 70 | ### `/internal` 71 | 72 | Private application and library code. This is the code you don't want others importing in their applications or libraries. Note that this layout pattern is enforced by the Go compiler itself. See the Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) for more details. Note that you are not limited to the top level `internal` directory. You can have more than one `internal` directory at any level of your project tree. 73 | 74 | You can optionally add a bit of extra structure to your internal packages to separate your shared and non-shared internal code. It's not required (especially for smaller projects), but it's nice to have visual clues showing the intended package use. Your actual application code can go in the `/internal/app` directory (e.g., `/internal/app/myapp`) and the code shared by those apps in the `/internal/pkg` directory (e.g., `/internal/pkg/myprivlib`). 75 | 76 | You use internal directories to make packages private. If you put a package inside an internal directory, then other packages can’t import it unless they share a common ancestor. And it’s the only directory named in Go’s documentation and has special compiler treatment. 77 | 78 | ### `/pkg` 79 | 80 | Library code that's ok to use by external applications (e.g., `/pkg/mypubliclib`). Other projects will import these libraries expecting them to work, so think twice before you put something here :-) Note that the `internal` directory is a better way to ensure your private packages are not importable because it's enforced by Go. The `/pkg` directory is still a good way to explicitly communicate that the code in that directory is safe for use by others. The [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) blog post by Travis Jeffery provides a good overview of the `pkg` and `internal` directories and when it might make sense to use them. 81 | 82 | It's also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools (as mentioned in these talks: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) and [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 83 | 84 | See the [`/pkg`](pkg/README.md) directory if you want to see which popular Go repos use this project layout pattern. This is a common layout pattern, but it's not universally accepted and some in the Go community don't recommend it. 85 | 86 | It's ok not to use it if your app project is really small and where an extra level of nesting doesn't add much value (unless you really want to :-)). Think about it when it's getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components). 87 | 88 | The `pkg` directory origins: The old Go source code used to use `pkg` for its packages and then various Go projects in the community started copying the pattern (see [`this`](https://twitter.com/bradfitz/status/1039512487538970624) Brad Fitzpatrick's tweet for more context). 89 | 90 | ### `/vendor` 91 | 92 | Application dependencies (managed manually or by your favorite dependency management tool like the new built-in [`Go Modules`](https://go.dev/wiki/Modules) feature). The `go mod vendor` command will create the `/vendor` directory for you. Note that you might need to add the `-mod=vendor` flag to your `go build` command if you are not using Go 1.14 where it's on by default. 93 | 94 | Don't commit your application dependencies if you are building a library. 95 | 96 | Note that since [`1.13`](https://golang.org/doc/go1.13#modules) Go also enabled the module proxy feature (using [`https://proxy.golang.org`](https://proxy.golang.org) as their module proxy server by default). Read more about it [`here`](https://blog.golang.org/module-mirror-launch) to see if it fits all of your requirements and constraints. If it does, then you won't need the `vendor` directory at all. 97 | 98 | ## Service Application Directories 99 | 100 | ### `/api` 101 | 102 | OpenAPI/Swagger specs, JSON schema files, protocol definition files. 103 | 104 | See the [`/api`](api/README.md) directory for examples. 105 | 106 | ## Web Application Directories 107 | 108 | ### `/web` 109 | 110 | Web application specific components: static web assets, server side templates and SPAs. 111 | 112 | ## Common Application Directories 113 | 114 | ### `/configs` 115 | 116 | Configuration file templates or default configs. 117 | 118 | Put your `confd` or `consul-template` template files here. 119 | 120 | ### `/init` 121 | 122 | System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs. 123 | 124 | ### `/scripts` 125 | 126 | Scripts to perform various build, install, analysis, etc operations. 127 | 128 | These scripts keep the root level Makefile small and simple (e.g., [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 129 | 130 | See the [`/scripts`](scripts/README.md) directory for examples. 131 | 132 | ### `/build` 133 | 134 | Packaging and Continuous Integration. 135 | 136 | Put your cloud (AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the `/build/package` directory. 137 | 138 | Put your CI (travis, circle, drone) configurations and scripts in the `/build/ci` directory. Note that some of the CI tools (e.g., Travis CI) are very picky about the location of their config files. Try putting the config files in the `/build/ci` directory linking them to the location where the CI tools expect them (when possible). 139 | 140 | ### `/deployments` 141 | 142 | IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, terraform). Note that in some repos (especially apps deployed with kubernetes) this directory is called `/deploy`. 143 | 144 | ### `/test` 145 | 146 | Additional external test apps and test data. Feel free to structure the `/test` directory anyway you want. For bigger projects it makes sense to have a data subdirectory. For example, you can have `/test/data` or `/test/testdata` if you need Go to ignore what's in that directory. Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory. 147 | 148 | See the [`/test`](test/README.md) directory for examples. 149 | 150 | ## Other Directories 151 | 152 | ### `/docs` 153 | 154 | Design and user documents (in addition to your godoc generated documentation). 155 | 156 | See the [`/docs`](docs/README.md) directory for examples. 157 | 158 | ### `/tools` 159 | 160 | Supporting tools for this project. Note that these tools can import code from the `/pkg` and `/internal` directories. 161 | 162 | See the [`/tools`](tools/README.md) directory for examples. 163 | 164 | ### `/examples` 165 | 166 | Examples for your applications and/or public libraries. 167 | 168 | See the [`/examples`](examples/README.md) directory for examples. 169 | 170 | ### `/third_party` 171 | 172 | External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI). 173 | 174 | ### `/githooks` 175 | 176 | Git hooks. 177 | 178 | ### `/assets` 179 | 180 | Other assets to go along with your repository (images, logos, etc). 181 | 182 | ### `/website` 183 | 184 | This is the place to put your project's website data if you are not using GitHub pages. 185 | 186 | See the [`/website`](website/README.md) directory for examples. 187 | 188 | ## Directories You Shouldn't Have 189 | 190 | ### `/src` 191 | 192 | Some Go projects do have a `src` folder, but it usually happens when the devs came from the Java world where it's a common pattern. If you can help yourself try not to adopt this Java pattern. You really don't want your Go code or Go projects to look like Java :-) 193 | 194 | Don't confuse the project level `/src` directory with the `/src` directory Go uses for its workspaces as described in [`How to Write Go Code`](https://golang.org/doc/code.html). The `$GOPATH` environment variable points to your (current) workspace (by default it points to `$HOME/go` on non-windows systems). This workspace includes the top level `/pkg`, `/bin` and `/src` directories. Your actual project ends up being a sub-directory under `/src`, so if you have the `/src` directory in your project the project path will look like this: `/some/path/to/workspace/src/your_project/src/your_code.go`. Note that with Go 1.11 it's possible to have your project outside of your `GOPATH`, but it still doesn't mean it's a good idea to use this layout pattern. 195 | 196 | 197 | ## Badges 198 | 199 | * [Go Report Card](https://goreportcard.com/) - It will scan your code with `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` and `misspell`. Replace `github.com/golang-standards/project-layout` with your project reference. 200 | 201 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 202 | 203 | * ~~[GoDoc](http://godoc.org) - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.~~ 204 | 205 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 206 | 207 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev is a new destination for Go discovery & docs. You can create a badge using the [badge generation tool](https://pkg.go.dev/badge). 208 | 209 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 210 | 211 | * Release - It will show the latest release number for your project. Change the github link to point to your project. 212 | 213 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 214 | 215 | ## Notes 216 | 217 | A more opinionated project template with sample/reusable configs, scripts and code is a WIP. 218 | -------------------------------------------------------------------------------- /README_es.md: -------------------------------------------------------------------------------- 1 | # Standard Go Project Layout 2 | 3 | Traducciones: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## Resumen 25 | 26 | Este es un diseño básico para proyectos de aplicaciones de Go. No es un estándar oficial definido por el equipo de desarrollo principal de Go; sin embargo, es un conjunto de patrones de diseño de proyectos históricos y emergentes comunes en el ecosistema Go. Algunos de estos patrones son más populares que otros. También tiene una serie de pequeñas mejoras junto con varios directorios de soporte comunes a cualquier aplicación del mundo real lo suficientemente grande. 27 | 28 | Si está tratando de aprender Go o si está construyendo un PoC o un proyecto de juguete para usted, este diseño del proyecto es excesivo. Comience con algo realmente simple (un solo archivo `main.go` es más que suficiente). A medida que su proyecto crezca, tenga en cuenta que será importante asegurarse de que su código esté bien estructurado, de lo contrario, terminará con un código desordenado con muchas dependencias ocultas y un estado global. Cuando tenga más personas trabajando en el proyecto, necesitará aún más estructura. Ahí es cuando es importante introducir una forma común de administrar paquetes / bibliotecas. Cuando tienes un proyecto de código abierto o cuando sabes que otros proyectos importan el código del repositorio de tu proyecto, es cuando es importante tener paquetes y código privados (también conocidos como `internal`). ¡Clona el repositorio, guarda lo que necesitas y elimina todo lo demás! El hecho de que esté allí no significa que tenga que usarlo todo. Ninguno de estos patrones se utiliza en todos los proyectos. Incluso el patrón `vendor` no es universal. 29 | 30 | Con Go 1.14, [`los módulos Go`](https://go.dev/wiki/Modules) están finalmente listos para la producción. Use [`los módulos Go`](https://blog.golang.org/using-go-modules) a menos que tenga una razón específica para no usarlos y, si lo hace, no debe preocuparse por $ GOPATH y dónde coloque su proyecto. El archivo `go.mod` básico en el repositorio asume que su proyecto está alojado en GitHub, pero no es un requisito. La ruta del módulo puede ser cualquier cosa, aunque el primer componente de la ruta del módulo debe tener un punto en su nombre (la versión actual de Go ya no lo aplica, pero si está utilizando versiones un poco más antiguas, no se sorprenda si sus compilaciones fallan sin eso). Consulte los problemas [`37554`](https://github.com/golang/go/issues/37554) y [`32819`](https://github.com/golang/go/issues/32819) si desea obtener más información al respecto. 31 | 32 | Este diseño de proyecto es intencionalmente genérico y no intenta imponer una estructura de paquete Go específica. 33 | 34 | Este es un esfuerzo comunitario. Abra un problema si ve un patrón nuevo o si cree que uno de los patrones existentes debe actualizarse. 35 | 36 | Si necesita ayuda con el nombre, el formato y el estilo, comience ejecutando `gofmt` y `golint`. También asegúrese de leer estas recomendaciones y pautas de estilo del código Go: 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Guía de estilo para paquetes Go](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | Consulte [`Diseño de proyecto de Go`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) para obtener información adicional sobre los antecedentes. 44 | 45 | Más sobre cómo nombrar y organizar paquetes, así como otras recomendaciones de estructura de código: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | Una publicación en idioma chino sobre las pautas de diseño orientado a paquetes y la capa de arquitectura 52 | 53 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 54 | 55 | ## Directorios en Go 56 | 57 | ### `/cmd` 58 | 59 | Principales aplicaciones de este proyecto. 60 | 61 | El nombre del directorio de cada aplicación debe coincidir con el nombre del ejecutable que desea tener (p.ej, `/cmd/myapp`). 62 | 63 | No pongas mucho código en el directorio de la aplicación. Si cree que el código se puede importar y utilizar en otros proyectos, entonces debería residir en el directorio `/pkg`. Si el código no es reutilizable o si no desea que otros lo reutilicen, coloque ese código en el directorio `/internal`. Se sorprenderá de lo que harán los demás, ¡así que sea explícito sobre sus intenciones! 64 | 65 | Es común tener una pequeña función `main` que importa e invoca el código de los directorios `/internal` y `/pkg` y nada más. 66 | 67 | Consulte el directorio [`/cmd`](cmd/README.md) para ver ejemplos. 68 | 69 | ### `/internal` 70 | 71 | Aplicación privada y código de biblioteca. Este es el código que no desea que otros importen en sus aplicaciones o bibliotecas. Tenga en cuenta que el propio compilador de Go aplica este patrón de diseño. Consulte [`las notas de la versión`](https://golang.org/doc/go1.4#internalpackages) Go 1.4 para obtener más detalles. Tenga en cuenta que no está limitado al directorio `internal` de nivel superior. Puede tener más de un directorio `internal` en cualquier nivel del árbol de su proyecto. 72 | 73 | Opcionalmente, puede agregar un poco de estructura adicional a sus paquetes internos para separar su código interno compartido y no compartido. No es necesario (especialmente para proyectos más pequeños), pero es bueno tener pistas visuales que muestren el uso previsto del paquete. Su código de aplicación real puede ir en el directorio `/internal/app` (p.ej, `/internal/app/myapp`) y el código compartido por esas aplicaciones en el directorio `/internal/pkg` (por ejemplo, `/internal/pkg/myprivlib`). 74 | 75 | ### `/pkg` 76 | 77 | Código de biblioteca que puede usar aplicaciones externas (por ejemplo, `/pkg/mypubliclib`). Otros proyectos importarán estas bibliotecas esperando que funcionen, así que piénselo dos veces antes de poner algo aquí :-) Tenga en cuenta que el directorio `internal` es la mejor manera de asegurarse de que sus paquetes privados no se puedan importar porque Go lo aplica. El directorio `/pkg` sigue siendo una buena forma de comunicar explícitamente que el código de ese directorio es seguro para que lo utilicen otros. La publicación del blog de Travis Jeffery, [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/), proporciona una buena descripción de los directorios `pkg` e `internal` y de cuándo podría tener sentido usarlos. 78 | 79 | También es una forma de agrupar el código de Go en un solo lugar cuando su directorio raíz contiene muchos componentes y directorios que no son de Go, lo que facilita la ejecución de varias herramientas de Go (como se menciona en estas charlas: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) de GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) y [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 80 | 81 | Consulte el directorio [`/pkg`](pkg/README.md) si desea ver qué repositorios Go populares utilizan este patrón de diseño de proyecto. Este es un patrón de diseño común, pero no se acepta universalmente y algunos miembros de la comunidad de Go no lo recomiendan. 82 | 83 | Está bien no usarlo si el proyecto de su aplicación es realmente pequeño y donde un nivel adicional de anidamiento no agrega mucho valor (a menos que realmente quiera :-)). Piénselo cuando sea lo suficientemente grande y su directorio raíz esté bastante ocupado (especialmente si tiene muchos componentes de aplicaciones que no son de Go). 84 | 85 | ### `/vendor` 86 | 87 | Dependencias de aplicaciones (administradas manualmente o mediante su herramienta de administración de dependencias favorita, como la nueva función de [`Módulos Go`](https://go.dev/wiki/Modules) integrada). El comando `go mod vendor` creará el directorio `/vendor` por usted. Tenga en cuenta que es posible que deba agregar la marca `-mod=vendor` a su comando `go build` si no está usando Go 1.14 donde está activado de forma predeterminada. 88 | 89 | No adicione las dependencias de su aplicación si está creando una biblioteca. 90 | 91 | Tenga en cuenta que desde [`1.13`](https://golang.org/doc/go1.13#modules) Go también habilitó la función de proxy del módulo (utilizando [`https://proxy.golang.org`](https://proxy.golang.org) como su servidor proxy del módulo de forma predeterminada). Lea más sobre esto [`aquí`](https://blog.golang.org/module-mirror-launch) para ver si se ajusta a todos sus requisitos y limitaciones. Si es así, no necesitará el directorio `vendor` en absoluto. 92 | 93 | ## Directorios de Aplicaciones de Servicio 94 | 95 | ### `/api` 96 | 97 | Especificaciones de OpenAPI/Swagger, archivos de esquema JSON, archivos de definición de protocolo. 98 | 99 | Consulte el directorio [`/api`](api/README.md) para ver ejemplos. 100 | 101 | ## Directorios de Aplicaciones Web 102 | 103 | ### `/web` 104 | 105 | Componentes específicos de la aplicación web: activos web estáticos, plantillas del lado del servidor y SPAs. 106 | 107 | ## Directorios de aplicaciones comunes 108 | 109 | ### `/configs` 110 | 111 | Plantillas de archivos de configuración o configuraciones predeterminadas. 112 | 113 | Ponga aquí sus archivos de plantilla `confd` o `consul-template`. 114 | 115 | ### `/init` 116 | 117 | Configuraciones de inicio del sistema (systemd, upstart, sysv) y administración de procesos (runit, supervisord). 118 | 119 | ### `/scripts` 120 | 121 | Scripts para realizar varias operaciones de construcción, instalación, análisis, etc. 122 | 123 | Estos scripts mantienen el Makefile de nivel raíz pequeño y simple (p.ej, [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 124 | 125 | Consulte el directorio `/scripts` para ver ejemplos. 126 | 127 | ### `/build` 128 | 129 | Empaquetado e Integración Continua. 130 | 131 | Coloque sus configuraciones de paquetes de nube (AMI), contenedor (Docker), SO (deb, rpm, pkg) y scripts en el directorio `/build/package`. 132 | 133 | Coloque sus configuraciones y scripts de CI (travis, circle, drone) en el directorio `/build/ci`. Tenga en cuenta que algunas de las herramientas de CI (p.ej, Travis CI) son muy exigentes con la ubicación de sus archivos de configuración. Intente poner los archivos de configuración en el directorio `/build/ci` vinculándolos a la ubicación donde las herramientas de CI los esperan (cuando sea posible). 134 | 135 | ### `/deployments` 136 | 137 | Configuraciones y plantillas de implementación de IaaS, PaaS, sistema y orquestación de contenedores (docker-compose, kubernetes/helm, mesos, terraform, bosh). Tenga en cuenta que en algunos repositorios (especialmente las aplicaciones implementadas con kubernetes) este directorio se llama `/deploy`. 138 | 139 | ### `/test` 140 | 141 | Aplicaciones de prueba externas adicionales y datos de prueba. Siéntase libre de estructurar el directorio `/test` como desee. Para proyectos más grandes, tiene sentido tener un subdirectorio de datos. Por ejemplo, puede tener `/test/data` o `/test/testdata` si necesita Go para ignorar lo que hay en ese directorio. Tenga en cuenta que Go también ignorará los directorios o archivos que comiencen con "." o "_", por lo que tiene más flexibilidad en términos de cómo nombrar su directorio de datos de prueba. 142 | 143 | Consulte el directorio [`/test`](test/README.md) para ver ejemplos. 144 | 145 | ## Otros Directorios 146 | 147 | ### `/docs` 148 | 149 | Diseño y documentos de usuario (además de su documentación generada por godoc). 150 | 151 | Consulte el directorio [`/docs`](docs/README.md) para ver ejemplos. 152 | 153 | ### `/tools` 154 | 155 | Herramientas de apoyo para este proyecto. Tenga en cuenta que estas herramientas pueden importar código de los directorios `/pkg` y `/internal`. 156 | 157 | Consulte el directorio [`/tools`](tools/README.md) para ver ejemplos. 158 | 159 | ### `/examples` 160 | 161 | Ejemplos para sus aplicaciones y / o bibliotecas públicas. 162 | 163 | Consulte el directorio [`/examples`](examples/README.md) para ver ejemplos. 164 | 165 | ### `/third_party` 166 | 167 | Herramientas de ayuda externas, código bifurcado y otras utilidades de terceros (p.ej, Swagger UI). 168 | 169 | ### `/githooks` 170 | 171 | Ganchos de Git. 172 | 173 | ### `/assets` 174 | 175 | Otros activos que acompañan a su repositorio (imágenes, logotipos, etc.). 176 | 177 | ### `/website` 178 | 179 | Este es el lugar para colocar los datos del sitio web de su proyecto si no está utilizando GitHub pages. 180 | 181 | Consulte el directorio [`/website`](website/README.md) para ver ejemplos. 182 | 183 | ## Directorios que No Deberías Tener 184 | 185 | ### `/src` 186 | 187 | Algunos proyectos de Go tienen una carpeta `src`, pero suele ocurrir cuando los desarrolladores vienen del mundo Java, donde es un patrón común. Si puede ayudarse a sí mismo, intente no adoptar este patrón de Java. Realmente no quieres que tu código Go o proyectos Go se parezcan a Java :-) 188 | 189 | No confunda el directorio `/src` de nivel de proyecto con el directorio `/src` que usa Go para sus áreas de trabajo, como se describe en [`How to Write Go Code`](https://golang.org/doc/code.html). La variable de entorno `$GOPATH` apunta a su área de trabajo (actual) (de forma predeterminada apunta a `$HOME/go` en sistemas que no son Windows). Este espacio de trabajo incluye los directorios de nivel superior `/pkg`, `/bin` y `/src`. Su proyecto real termina siendo un subdirectorio en `/src`, por lo que si tiene el directorio `/src` en su proyecto, la ruta del proyecto se verá así: `/some/path/to/workspace/src/your_project/src/your_code.go`. Tenga en cuenta que con Go 1.11 es posible tener su proyecto fuera de su `GOPATH`, pero aún así no significa que sea una buena idea utilizar este patrón de diseño. 190 | 191 | ## Badges 192 | 193 | * [Go Report Card](https://goreportcard.com/) - Escaneará su código con `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` y `misspell`. Cambie `github.com/golang-standards/project-layout` por la referencia de su proyecto. 194 | 195 | * ~~[GoDoc](http://godoc.org) - Proporcionará una versión en online de su documentación generada por GoDoc. Cambie el enlace para que apunte a su proyecto.~~ 196 | 197 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev es un nuevo destino para Go discovery & docs. Puede crear una insignia con [la herramienta de generación de insignias](https://pkg.go.dev/badge). 198 | 199 | * Release - mostrará el número de versión más reciente de su proyecto. Cambie el enlace de github para que apunte a su proyecto. 200 | 201 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 202 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 203 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 204 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 205 | 206 | ## Notas 207 | 208 | Una plantilla de proyecto con mayor criterio sobre configuraciones, scripts y códigos de ejemplos está en construcción (WIP). 209 | -------------------------------------------------------------------------------- /README_id.md: -------------------------------------------------------------------------------- 1 | # Standar Tata Letak Proyek Go 2 | 3 | Terjemahan: 4 | 5 | * [한국어 문서](README_ko.md) 6 | * [简体中文](README_zh.md) 7 | * [正體中文](README_zh-TW.md) 8 | * [简体中文](README_zh-CN.md) - ??? 9 | * [Français](README_fr.md) 10 | * [日本語](README_ja.md) 11 | * [Portuguese](README_ptBR.md) 12 | * [Español](README_es.md) 13 | * [Română](README_ro.md) 14 | * [Русский](README_ru.md) 15 | * [Türkçe](README_tr.md) 16 | * [Українська](README_ua.md) 17 | * [Indonesian](README_id.md) 18 | * [हिन्दी](README_hi.md) 19 | * [Беларуская](README_be.md) 20 | 21 | ## Ringkasan 22 | 23 | Berikut ini merupakan tata letak dasar untuk proyek aplikasi Go. Ini **`bukan standar resmi yang ditetapkan oleh tim pengembang inti Go`**; namun, ini merupakan sejumlah pola tata letak proyek historis dan terkini yang umumnya digunakan dalam ekosistem Go. Beberapa pola ini lebih populer daripada yang lain. Selain itu, terdapat beberapa pembaharuan kecil bersama dengan beberapa direktori pendukung yang umum ditemukan dalam aplikasi dunia nyata yang cukup besar. 24 | 25 | Jika kamu sedang belajar Go atau sedang membangun PoC atau proyek sederhana untuk dirimu sendiri, tata letak proyek ini terlalu berlebihan. Mulailah dengan sesuatu yang sederhana saja (sebuah file `main.go` tunggal dan `go.mod` sudah cukup). Ketika proyekmu berkembang, penting untuk memastikan kodemu terstruktur dengan baik, jika tidak, kamu akan berakhir dengan kode yang berantakan dengan banyak dependensi tersembunyi dan state global. Ketika ada lebih banyak orang yang bekerja pada proyekmu, kamu akan membutuhkan struktur yang lebih terorganisir. Itulah saat yang penting untuk memperkenalkan cara umum dalam mengelola paket/pustaka. Ketika kamu memiliki proyek open source atau ketika kamu tahu proyek lain mengimpor kode dari repositori proyekmu, saat itulah penting untuk memiliki paket dan kode pribadi (dikenal juga sebagai `internal`). Klon repositori tersebut, ambil yang kamu butuhkan, dan hapus sisanya! Hanya karena ada di sana, tidak berarti kamu harus menggunakan semuanya. Tidak satu pun dari pola-pola ini digunakan dalam setiap proyek. Bahkan pola `vendor` tidaklah universal. 26 | 27 | Dengan Go 1.14, [`Go Modules`](https://go.dev/wiki/Modules) akhirnya siap digunakan untuk produksi. Gunakan [`Go Modules`](https://blog.golang.org/using-go-modules) kecuali kamu memiliki alasan khusus untuk tidak menggunakannya. Jika kamu tidak menggunakan Go Modules, maka kamu tidak perlu khawatir tentang `$GOPATH` dan di mana kamu meletakkan proyekmu. File `go.mod` di dalam repositori ini mengasumsikan bahwa proyekmu di-host di GitHub, tetapi itu bukan menjadi persyaratan. Path modul dapat menjadi apa saja, meskipun komponen path modul pertama sebaiknya memiliki tanda titik dalam namanya (versi Go saat ini tidak lagi memaksakannya, tetapi jika kamu menggunakan versi yang sedikit lebih lama, jangan heran jika proses build tidak akan berhasil). Lihat isu [`37554`](https://github.com/golang/go/issues/37554) dan [`32819`](https://github.com/golang/go/issues/32819) jika kamu ingin tahu lebih banyak mengenai hal ini. 28 | 29 | Tata letak proyek ini sengaja dirancang secara generik dan tidak mencoba memaksakan struktur paket Go yang spesifik. 30 | 31 | Ini merupakan usaha komunitas. Buka sebuah isu jika kamu melihat pola baru atau jika kamu berpikir bahwa salah satu pola yang sudah ada perlu diperbarui. 32 | 33 | Jika kamu membutuhkan bantuan dalam hal penamaan, pemformatan, dan gaya penulisan, mulailah dengan menjalankan [`gofmt`](https://golang.org/cmd/gofmt/) dan [`golint`](https://github.com/golang/lint). Pastikan juga untuk membaca panduan dan rekomendasi gaya penulisan kode Go berikut ini: 34 | * https://talks.golang.org/2014/names.slide 35 | * https://golang.org/doc/effective_go.html#names 36 | * https://blog.golang.org/package-names 37 | * https://go.dev/wiki/CodeReviewComments 38 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 39 | 40 | Lihatlah [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) untuk informasi latar belakang tambahan. 41 | 42 | Lebih lanjut tentang penamaan dan pengorganisasian paket serta rekomendasi struktur kode lainnya: 43 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 44 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 45 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 46 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 47 | 48 | Sebuah postingan dalam bahasa Cina tentang pedoman Package-Oriented Design dan Architecture layer: 49 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 50 | 51 | ## Direktori Go 52 | 53 | ### `/cmd` 54 | 55 | Aplikasi utama untuk proyek ini. 56 | 57 | Nama direktori untuk setiap aplikasi harus sesuai dengan nama file eksekusi yang diinginkan (misalnya, `/cmd/myapp`). 58 | 59 | Jangan menempatkan banyak kode di dalam direktori aplikasi. Jika anda berpikir bahwa kode tersebut dapat diimpor dan digunakan dalam proyek lain, maka kode tersebut harus ditempatkan di dalam direktori `/pkg`. Jika kode tersebut tidak dapat digunakan kembali atau jika anda tidak ingin orang lain menggunakannya kembali, letakkan kode tersebut di dalam direktori `/internal`. Anda akan terkejut dengan apa yang orang lain lakukan, jadi tetap jelaskan niat anda! 60 | 61 | Biasanya, terdapat fungsi `main` kecil yang mengimpor dan memanggil kode dari direktori `/internal` dan `/pkg`, dan tidak ada yang lain. 62 | 63 | Lihat direktori [`/cmd`](cmd/README.md) untuk contoh-contoh lebih lanjut. 64 | 65 | ### `/internal` 66 | 67 | Kode aplikasi dan library privat. Ini adalah kode anda yang tidak ingin diimpor oleh aplikasi atau library lain. Perlu dicatat bahwa pola tata letak ini dipaksakan atau dijaga oleh kompiler Go itu sendiri. Lihat catatan rilis Go 1.4 [`di sini`](https://golang.org/doc/go1.4#internalpackages) untuk detailnya. Perhatikan bahwa anda tidak dibatasi pada direktori top level `internal` saja. Anda dapat memiliki lebih dari satu direktori `internal` di setiap tingkatan proyek anda. 68 | 69 | Secara opsional anda dapat menambahkan struktur tambahan ke paket internal anda, untuk memisahkan kode internal yang bersifat shared dan non-shared. Hal ini tidak diwajibkan (terutama untuk proyek-proyek kecil), tetapi bagus untuk memiliki petunjuk visual yang menunjukkan penggunaan paket yang dimaksudkan. Sebenarnya kode aplikasi dapat ditempatkan di direktori `/internal/app` (misalnya, `/internal/app/myapp`) dan kode yang dibagikan oleh aplikasi tersebut dapat ditempatkan di direktori `/internal/pkg` (misalnya, `/internal/pkg/myprivlib`). 70 | 71 | ### `/pkg` 72 | 73 | Kode library yang boleh digunakan oleh aplikasi eksternal (misalnya, `/pkg/mypubliclib`). Proyek lain akan mengimpor library ini dengan harapan dapat berfungsi, jadi berpikirlah dua kali sebelum anda meletakkan sesuatu di sini :-) Perlu dicatat bahwa direktori `internal` adalah cara yang lebih baik untuk memastikan paket pribadi anda tidak dapat diimpor karena dijaga oleh Go. Namun, direktori `/pkg` tetap cara yang baik untuk mengkomunikasikan secara eksplisit bahwa kode di dalam direktori tersebut aman digunakan oleh orang lain. Postingan [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) oleh Travis Jeffery memberikan gambaran yang baik tentang direktori `pkg` dan `internal` serta kapan waktu yang tepat untuk menggunakannya. 74 | 75 | Hal ini merupakan cara untuk mengelompokkan kode Go di satu tempat ketika direktori root anda berisi banyak komponen dan direktori non-Go, sehingga memudahkan dalam menjalankan berbagai tools Go (seperti yang disebutkan dalam presentasi-presentasi ini: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) dari GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0), dan [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 76 | 77 | Lihat direktori [`/pkg`](pkg/README.md) jika anda ingin melihat repositori Go populer yang menggunakan pola tata letak proyek seperti ini. Ini adalah pola tata letak yang umum digunakan, akan tetapi tidak diterima secara universal dan beberapa anggota komunitas Go tidak merekomendasikannya. 78 | 79 | Tidak masalah jika anda tidak menggunakannya, apabila proyek aplikasi anda benar-benar kecil dan tingkatan level tambahan tidak begitu penting (kecuali jika anda benar-benar menginginkannya :-)). Pikirkanlah hal tersebut ketika proyek anda cukup besar dan direktori root anda sudah cukup sibuk (terutama jika anda memiliki banyak komponen aplikasi non-Go). 80 | 81 | Asal-usul direktori `pkg`: Source code Go yang lama menggunakan `pkg` untuk paket-paketnya, dan kemudian berbagai proyek Go dalam komunitas mulai meniru pola tersebut (Lihat [`tweet Brad Fitzpatrick ini`](https://twitter.com/bradfitz/status/1039512487538970624) untuk konteks lebih lanjut). 82 | 83 | ### `/vendor` 84 | 85 | Dependensi aplikasi (dikelola secara manual atau dengan dependency management tool favorit anda seperti fitur baru bawaan [`Go Modules`](https://go.dev/wiki/Modules). Perintah `go mod vendor` akan membuat direktori `/vendor `untuk anda. Perlu dicatat bahwa anda mungkin perlu menambahkan flag `-mod=vendor` ke perintah `go build` jika anda tidak menggunakan Go 1.14 di mana fitur tersebut sudah diaktifkan secara default. 86 | 87 | Jangan meng-commit dependency aplikasi anda jika anda sedang membangun sebuah library. 88 | 89 | Perlu dicatat bahwa sejak versi [`1.13`](https://golang.org/doc/go1.13#modules), Go telah mengaktifkan fitur module proxy (menggunakan [`https://proxy.golang.org`](https://proxy.golang.org) sebagai server proxy modul default). Baca lebih lanjut tentang fitur ini [`di sini`](https://blog.golang.org/module-mirror-launch) untuk melihat apakah sesuai dengan semua persyaratan dan batasan anda. Jika sesuai, maka anda sama sekali tidak perlu menggunakan direktori `vendor`. 90 | 91 | ## Direktori Servis Aplikasi 92 | 93 | ### `/api` 94 | 95 | Spesifikasi OpenAPI/Swagger, file skema JSON, file definisi protokol. 96 | 97 | Lihat direktori [`/api`](api/README.md) untuk contoh-contohnya. 98 | 99 | ### `/web` 100 | 101 | Komponen-komponen spesifik aplikasi web: aset web statis, template di sisi server, dan SPAs. 102 | 103 | ## Direktori Umum Aplikasi 104 | 105 | ### `/configs` 106 | 107 | Template file konfigurasi atau konfigurasi default. 108 | 109 | Letakkan file template anda di `confd` atau `consul-template`.. 110 | 111 | ### `/init` 112 | 113 | Konfigurasi sistem init (systemd, upstart, sysv) dan manajer proses/supervisor (runit, supervisord). 114 | 115 | ### `/scripts` 116 | 117 | Skrip-skrip untuk melakukan berbagai operasi seperti build, instalasi, analisis, dll. 118 | 119 | Skrip-skrip ini menjaga Makefile tingkat root agar tetap kecil dan sederhana (misalnya, [`https://github.com/hashicorp/terraform/blob/master/Makefile`](https://github.com/hashicorp/terraform/blob/master/Makefile)). 120 | 121 | Lihat direktori [`/scripts`](scripts/README.md) untuk melihat contoh-contohnya. 122 | 123 | ### `/build` 124 | 125 | Pemaketan (Packaging) dan Integrasi Berkelanjutan (Continuous Integration). 126 | 127 | Letakkan skrip paket dan konfigurasi untuk cloud (AMI), container (Docker), sistem operasi (deb, rpm, pkg) anda di direktori `/build/package`. 128 | 129 | Letakkan skrip dan konfigurasi CI (travis, circle, drone) anda di direktori `/build/ci`. Perhatikan bahwa beberapa tools CI (misalnya, Travis CI) sangat ketat mengenai lokasi file konfigurasi mereka. Coba letakkan file konfigurasi di direktori `/build/ci` dan buat tautan ke lokasi yang diharapkan oleh tools CI (jika memungkinkan). 130 | 131 | ### `/deployments` 132 | 133 | Konfigurasi dan template untuk IaaS, PaaS, orkestrasi sistem, dan container (docker-compose, kubernetes/helm, mesos, terraform, bosh). Perhatikan bahwa dalam beberapa repositori (terutama aplikasi yang diimplementasikan dengan kubernetes), direktori ini disebut `/deploy`. 134 | 135 | ### `/test` 136 | 137 | Tambahan eksternal untuk menguji aplikasi dan data. Aturlah struktur direktori `/test` sesuai keinginan anda. Untuk proyek yang lebih besar, disarankan memiliki subdirektori data. Misalnya, anda dapat memiliki `/test/data` atau `/test/testdata` jika anda ingin Go mengabaikan apa yang ada dalam direktori tersebut. Perhatikan bahwa Go juga akan mengabaikan direktori atau file yang dimulai dengan "." atau "_", sehingga anda memiliki fleksibilitas lebih dalam penamaan direktori data pengujian. 138 | 139 | Lihat direktori [`/test`](test/README.md) untuk contoh-contohnya. 140 | 141 | ## Direktori Lainya 142 | 143 | ### `/docs` 144 | 145 | Dokumentasi desain dan pengguna (selain dokumentasi yang dihasilkan oleh godoc). 146 | 147 | Lihat direktori [`/docs`](docs/README.md) untuk contoh-contohnya. 148 | 149 | ### `/tools` 150 | 151 | Tools pendukung untuk proyek ini. Perhatikan bahwa tools ini dapat mengimpor kode dari direktori `/pkg` dan `/internal`. 152 | 153 | Lihat direktori [`/tools`](tools/README.md) untuk contoh-contohnya. 154 | 155 | ### `/examples` 156 | 157 | Contoh-contoh aplikasi atau library publik anda. 158 | 159 | Lihat direktori [`/examples`](examples/README.md) untuk melihat contoh-contohnya. 160 | 161 | ### `/third_party` 162 | 163 | Tools eksternal, kode yang di-fork, dan utilitas pihak ketiga (third party) lainnya (misalnya, Swagger UI). 164 | 165 | ### `/githooks` 166 | 167 | Git hooks. 168 | 169 | ### `/assets` 170 | 171 | Aset lainnya yang ada di repositori anda (gambar, logo, dll). 172 | 173 | ### `/website` 174 | 175 | Tempat untuk meletakkan data situs web proyek anda jika anda tidak menggunakan halaman GitHub. 176 | 177 | Lihat direktori [`/website`](website/README.md) untuk contoh-contohnya. 178 | 179 | ## Direktori yang Sebaiknya Tidak Dimiliki 180 | 181 | ### `/src` 182 | 183 | Beberapa proyek Go memiliki folder `src`, akan tetapi ini biasanya terjadi ketika pengembang berasal dari dunia Java di mana itu adalah pola umum. Jika memungkinkan, hindari mengadopsi pola Java ini. Anda benar-benar tidak ingin kode Go atau proyek Go anda terlihat seperti Java :-) 184 | 185 | Jangan bingung antara direktori proyek `/src` dengan direktori `/src` yang digunakan Go untuk workspace-nya seperti yang dijelaskan dalam [`How to Write Go Code`](https://golang.org/doc/code.html). Variabel environtment `$GOPATH` menunjuk ke workspace anda saat ini (secara default menunjuk ke `$HOME/go` pada sistem non-Windows). Workspace ini mencakup direktori top level `/pkg`, `/bin`, dan `/src`. Proyek aktual anda berada di bawah direktori `/src`, jadi jika anda memiliki direktori `/src` di proyek anda, path proyek akan terlihat seperti ini: `/some/path/to/workspace/src/your_project/src/your_code.go`. Perlu diingat bahwa dengan Go 1.11, memungkinkan untuk memiliki proyek di luar `GOPATH`, tetapi bukan berarti itu adalah ide yang baik untuk menggunakan pola tata letak ini. 186 | 187 | 188 | ## Badges 189 | 190 | * [Go Report Card](https://goreportcard.com/) - Akan memindai kode anda menggunakan `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` dan `misspell`. Ubah `github.com/golang-standards/project-layout` dengan referensi proyek anda. 191 | 192 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 193 | 194 | * ~~[GoDoc](http://godoc.org) -Ini akan menyediakan versi online dari dokumentasi yang dihasilkan oleh GoDoc anda. Ubah tautan tersebut agar mengarah ke proyek anda.~~ 195 | 196 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 197 | 198 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev adalah tempat baru untuk menemukan dan mendokumentasikan Go. Anda dapat membuat badge menggunakan [badge generation tool](https://pkg.go.dev/badge). 199 | 200 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 201 | 202 | * Release - Ini akan menampilkan nomor rilisan terbaru untuk proyek anda. Ubah tautan GitHub menjadi menunjuk ke proyek anda. 203 | 204 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 205 | 206 | ## Catatan 207 | 208 | Opsi template lainya disertai contoh konfigurasi, skrip, dan kode yang dapat digunakan kembali sedang dalam pengembangan (WIP). 209 | -------------------------------------------------------------------------------- /README_it.md: -------------------------------------------------------------------------------- 1 | # Layout standard di un progetto Go 2 | 3 | Traduzioni: 4 | 5 | * [한국어 문서](README_ko.md) 6 | * [简体中文](README_zh.md) 7 | * [正體中文](README_zh-TW.md) 8 | * [简体中文](README_zh-CN.md) - ??? 9 | * [Français](README_fr.md) 10 | * [日本語](README_ja.md) 11 | * [Portuguese](README_ptBR.md) 12 | * [Español](README_es.md) 13 | * [Română](README_ro.md) 14 | * [Русский](README_ru.md) 15 | * [Türkçe](README_tr.md) 16 | * [Українська](README_ua.md) 17 | * [Indonesian](README_id.md) 18 | * [हिन्दी](README_hi.md) 19 | * [Беларуская](README_be.md) 20 | 21 | ## Panoramica 22 | 23 | Questa è un'impostazione di base per applicativi Go. **Non è uno standard ufficiale definito dal team principale di Go**; Invece è un insieme di pattern archittetturali provenienti da progetti ben consolidati nell'ecosistema Go. Alcuni di questi pattern sono più popolari di altri. Sono presenti anche diversi piccoli miglioramenti con alcune cartelle di supporto comuni a qualsiasi grande applicativo in contesto reale. 24 | 25 | **`Se stai imparando Go o se stai sviluppando una PoC o un semplice progetto personale, questa struttura è una complicazione non necessaria. Invece inizia con qualcosa di veramente semplice (un unico file `main.go` e `go.mod` è abbastanza).`** Con la crescita del tuo progetto tieni a mente che sarà sempre più importante la corretta impostazione del tuo codice, altrimenti finirai con codice disordinato con molte dipendenze nascoste e uno stato globale. Quando più persone lavorano su un progetto, avrai bisogno di un'impostazione ancora più strutturata. Questo è il momento in cui è importante introdurre un modo comune di gestire pacchetti e librerie. Quando hai un progetto open source o quando sai che altri progetti importano il codice del tuo repository, questo è il momento in cui è importante avere pacchetti e codice privato (`internal`). Clona il repository, mantieni ciò di cui hai bisogno e cancella qualsiasi altra cosa! Solo perchè è presente non significa che vada usato. Nessuno di questi pattern sono usati in ogni singolo progetto. Perfino il `vendor` pattern non è universale. 26 | 27 | Con Go 1.14 i [`Go Modules`](https://go.dev/wiki/Modules) sono finalmente pronti per la produzione. Usa [`Go Modules`](https://blog.golang.org/using-go-modules) fino a quando hai una specifica ragione per non usarli e se lo farai non dovrai preoccuparti riguardo $GOPATH e dove mettere il tuo progetto. Il file `go.mod` di base nel repo presuppone che il tuo progetto sia pubblicato su GitHub, ma non è obbligatorio. Il path del modulo può essere uno qualsiasi, anche se la prima parte del path del modulo dovrebbe avere un punto nel nome (l'attuale versione di Go non lo forza più, ma se stai usando una delle versioni leggermente più vecchie, non essere sorpreso se le tue builds falliranno). Guarda le Issues [`37554`](https://github.com/golang/go/issues/37554) e [`32819`](https://github.com/golang/go/issues/32819) se vuoi saperne di più a riguardo. 28 | 29 | Questa struttura di progetto è intenzionalmente generica e non cerca di imporre una specifica impostazione per i packages Go. 30 | 31 | Questo è uno sforzo della community. Apri una issue se vedi un nuovo pattern o se pensi che uno di quelli esistenti andrebbe aggiornato. 32 | 33 | Se hai bisogno di aiuto per la nomenclatura, formattazione e lo stile, inizia da utilizzare [`gofmt`](https://golang.org/cmd/gofmt/) e [`golint`](https://github.com/golang/lint). Assicurati anche di leggere le linee guida di stile e i consigli: 34 | * https://talks.golang.org/2014/names.slide 35 | * https://golang.org/doc/effective_go.html#names 36 | * https://blog.golang.org/package-names 37 | * https://go.dev/wiki/CodeReviewComments 38 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 39 | 40 | Vedi [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) per l'aggiunta di altre informazioni a contorno. 41 | 42 | Per altro riguardo la nomenclatura e l'organizzazione dei pacchetti e altre impostazioni raccomandate: 43 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 44 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 45 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 46 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 47 | 48 | Un post Cinese riguardo delle linee guida per il design Package-Oriented e layer archittetturali 49 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 50 | 51 | ## Go Cartelle 52 | 53 | ### `/cmd` 54 | 55 | Applicazioni principali per questo progetto. 56 | 57 | Il nome della cartella per ciascun applicativo dovrebbe coincidere con il nome che vuoi avere per l'eseguibile (es: `/cmd/myapp`). 58 | 59 | Non mettere molto codice nella cartella dell'applicazione. Se pensi che il codice potrebbe essere importato e usato in altri progetti, allora dovrebbe essere inserito nella cartella `/pkg`. Se il codice non è riutilizzabile o non vuoi che altri lo riutilizzino, metti questo codice nella cartella `/internal`. Sarai sorpreso di vedere cosa faranno gli altri, quindi si esplicito riguardo le tue intenzioni! 60 | 61 | E' comune avere una piccola funzione `main` che importa e invoca il codice dalle cartelle `/internal` e `/pkg` e nient'altro. 62 | 63 | Vedi cartella [`/cmd`](cmd/README.md) per esempi. 64 | 65 | ### `/internal` 66 | 67 | Applicativo privato e codice di libreria. Quì c'è il codice che non vuoi gli altri importino nei loro progetti o librerie. Nota che questo pattern archittetturale è forzato dallo stesso compilatore Go. Vedi Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) per maggiori dettagli. Nota che non sei obbligato ad avere unicamente la cartella padre `internal`. Puoi avere più di una singola cartella `internal` a qualsiasi livello della tua ramificazione di progetto. 68 | 69 | 70 | Puoi opzionalmente aggiungere una struttura aggiuntiva ai tuoi pacchetti interni, per separare il tuo codice interno condiviso e non condiviso. Non è obbligatorio (specialmente per piccoli progetti), ma è meglio avere indicazioni per mostrare l'utilizzo raccomandato del pacchetto. Il tuo effettivo codice applicativo può essere inserito nella cartella `/internal/app` (es: `/internal/app/myapp`) e il codice condiviso da queste app nella cartella `/internal/pkg` (es: `/internal/pkg/myprivlib`). 71 | 72 | ### `/pkg` 73 | 74 | Codice di libreria che può essere utilizzato da applicazioni esterne (es:, `/pkg/mypubliclib`). Altri progetti importeranno queste librerie aspettandosi che funzionino, quindi pensaci bene prima di metterci dentro qualcosa :-) Nota che la cartella `internal` è un modo migliore di assicurarsi che i tuoi pacchetti privati non sono importabili, perché ciò è forzato in Go. La cartella `/pkg` è anche un buon modo di esplicitare che il codice contenuto al suo interno è utilizzabile da parte di altri. Il post [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) scritto da Travis Jeffery fornisce una buona panoramica delle cartelle `pkg` e `internal` indicando quando abbia senso usarle. 75 | 76 | C'è anche un modo di raggruppare il codice Go in unico posto quando la tua cartella di root contiene molti componenti non-Go e cartelle semplificando l'utilizzo di vari strumenti Go (come menzionato in questi talk: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) dal GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) e [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 77 | 78 | Guarda la cartella [`/pkg`](pkg/README.md) se vuoi vedere quali popolari repo utilizzano questa struttura di progetto. Questo è un pattern di layout comune, tuttavia non è universalmente accettato e qualcuno nella community Go non lo raccomanda. 79 | 80 | È ok non utilizzarla se il tuo progetto è molto piccolo e aggiungere un ulteriore strato di annidamento non dà un valore aggiunto (a meno che tu non lo voglia davvero molto :-)). Pensa di prevederla quando sta diventando grande abbastanza e la tua cartella root si sta riempendo troppo (specialmente quando hai molti componenti non Go nell'applicativo). 81 | 82 | Origini della cartella `pkg`: Il vecchio codice sorgente di Go usava la cartella `pkg` per i suoi pacchetti e così diversi progetti Go nella community hanno iniziato a copiare questo pattern (vedi [`questo`](https://twitter.com/bradfitz/status/1039512487538970624) tweet di Brad Fitzpatrick per avere un contesto più dettagliato). 83 | 84 | ### `/vendor` 85 | 86 | Dipendenze dell'applicativo (gestite manualmente o dal tuo gestore di pacchetti preferito come la nuova feature built-in [`Go Modules`](https://go.dev/wiki/Modules)). Il comando `go mod vendor` creerà la cartella `/vendor` per te. Tiene presente che potrebbe essere necessario aggiungere il flag `-mod=vendor` al tuo comando `go build` se non stai utilizzando Go 1.14, dove è utilizzato di default. 87 | 88 | Non effettuare il commit delle dipendenze del tuo applicativo se stai sviluppando una libreria. 89 | 90 | Nota che sin dalla versione [`1.13`](https://golang.org/doc/go1.13#modules) Go ha anche abilitata la caratteristica del module proxy (usando [`https://proxy.golang.org`](https://proxy.golang.org) come server proxy predefinito). Approfondisci [`quì`](https://blog.golang.org/module-mirror-launch) per vedere se questo soddisfa tutti i tuoi requisiti e vincoli. In caso positivo, allora non avrai bisogno della cartella `vendor`. 91 | 92 | ## Cartelle di Servizio Applicativo 93 | 94 | ### `/api` 95 | 96 | OpenAPI/Swagger specs, JSON schema files, files di definizione del protocollo. 97 | 98 | Vedi la cartella [`/api`](api/README.md) per esempi. 99 | 100 | ## Cartelle Applicativo Web 101 | 102 | ### `/web` 103 | 104 | Componenti specifici per applitavi Web: assets web statici, templates server side e SPAs. 105 | 106 | ## Cartelle comuni applicativo 107 | 108 | ### `/configs` 109 | 110 | Templates per il file di configurazione o configurazioni di default. 111 | 112 | Metti i tuoi templates `confd` o `consul-template` quì. 113 | 114 | ### `/init` 115 | 116 | Inizializzazione del sistema (systemd, upstart, sysv) e configurazioni per process manager/supervisor (runit, supervisord). 117 | 118 | ### `/scripts` 119 | 120 | Script per effettuare varie operazioni per la build, installazione, analisi, ecc... 121 | 122 | Questi script mantengono a livello di root un Makefile piccolo e immediato (es: [`https://github.com/hashicorp/terraform/blob/master/Makefile`](https://github.com/hashicorp/terraform/blob/master/Makefile)). 123 | 124 | Vedi la cartella [`/scripts`](scripts/README.md) per esempi. 125 | 126 | ### `/build` 127 | 128 | Packaging e Continuous Integration. 129 | 130 | Metti le configurazioni dei tuoi pacchetti: cloud (AMI), container (Docker), OS (deb, rpm, pkg) e script nella cartella `/build/package`. 131 | 132 | Metti le tue configurazioni della CI (travis, circle, drone) e script nella cartella `/build/ci`. Nota che qualche tool di CI (es: Travis CI) sono molto stringenti riguardo la posizione dei propri file di configurazione. Prova mettendo le configurazioni nella cartella `/build/ci` collegandole al percorso dove gli strumenti di CI se le aspettano (quando possibile). 133 | 134 | ### `/deployments` 135 | 136 | Configurazioni e template per distribuzioni IaaS, PaaS, di sistema e basati su sistemi di orchestrazione (docker-compose, kubernetes/helm, mesos, terraform, bosh). Nota che in alcuni repo (specialmente per gli applicativi pubblicati con kubernetes) questa cartella è chiamata `/deploy`. 137 | 138 | ### `/test` 139 | 140 | Ulteriori app di test esterne e dati di test. Sentiti libero di strutturare la cartella `/test` come preferisci. Per progetti più grandi ha senso avere una sotto cartella data. Per esempio potresti avere `/test/data` o `/test/testdata` se hai bisogno che Go ignori il contenuto di questa cartella. Nota che Go ignorerà anche le cartelle o file che iniziano con "." o "_", così si ha più flessibilità in termini di come intendi chiamare la cartella dei tuoi dati test. 141 | 142 | Vedi la cartella [`/test`](test/README.md) per esempi. 143 | 144 | ## Altre Cartelle 145 | 146 | ### `/docs` 147 | 148 | Documenti dell'utente e di Design (in aggiunta alla tua documentazione godoc autogenerata). 149 | 150 | Vedi la cartella [`/docs`](docs/README.md) per esempi. 151 | 152 | ### `/tools` 153 | 154 | Strumenti di supporto per il progetto. Nota che questi strumenti possono importare codice dalle cartelle `/pkg` e `/internal`. 155 | 156 | Vedi la cartella [`/tools`](tools/README.md) per esempi. 157 | 158 | ### `/examples` 159 | 160 | Esempi per il tuo applicativo e/o librerie pubbliche. 161 | 162 | Vedi la cartella [`/examples`](examples/README.md) per esempi. 163 | 164 | ### `/third_party` 165 | 166 | Strumenti esterni di aiuto, codice forcato e altre utility di terze parti (es: Swagger UI). 167 | 168 | ### `/githooks` 169 | 170 | Hook di Git. 171 | 172 | ### `/assets` 173 | 174 | Altri asset del tuo repository (immagini, loghi, etc). 175 | 176 | ### `/website` 177 | 178 | Questo è il posto in cui inserire i dati del sito Web del tuo progetto se non stai utilizzando le GitHub pages. 179 | 180 | Vedi la cartella [`/website`](website/README.md) per esempi. 181 | 182 | ## Cartelle che Non Dovresti Avere 183 | 184 | ### `/src` 185 | 186 | Qualche progetto Go ha una cartella `src`, ma comunemente succede quando gli sviluppatori provengono dal mondo Java, dove è una pratica comune. Se vuoi aiutarti prova a non adottare questo pattern Java. Non vuoi davvero che il tuo codice Go o i tuoi progetti Go assomiglino a quelli Java :-) 187 | 188 | Non confondere la cartella `/src` a livello di progetto con la cartella `/src` che Go utilizza per i suoi workspace come descritto in [`How to Write Go Code`](https://golang.org/doc/code.html). La variabile di ambiente `$GOPATH` punta al tuo (attuale) workspace (di default punta a `$HOME/go` su sistemi non Windows). Questo workspace include le cartelle di livello superiore `/pkg`, `/bin` e `/src`. Il tuo progetto attuale finisce per essere una sotto cartella di `/src`, quindi se hai la cartella `/src` nel tuo progetto, il tuo path di progetto assomiglierà a questo: `/some/path/to/workspace/src/your_project/src/your_code.go`. Nota che da Go 1.11 è possibile avere il proprio progetto al di fuori del `GOPATH`, ma ciò non significa che sia una buona idea utilizzare questo pattern di layout. 189 | 190 | 191 | ## Badges 192 | 193 | * [Go Report Card](https://goreportcard.com/) - Scansione il tuo codice con `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` e `misspell`. Rimpiazza `github.com/golang-standards/project-layout` con la referenza al tuo progetto. 194 | 195 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 196 | 197 | * ~~[GoDoc](http://godoc.org) - Fornisce una verione online della tua documentazione GoDoc generata. Cambia il link per puntare al tuo progetto.~~ 198 | 199 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 200 | 201 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev è una nuova fonte per la scoperta di Go e documentazione. Puoi creare un badge usando lo [badge generation tool](https://pkg.go.dev/badge). 202 | 203 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 204 | 205 | * Release - Mostra l'ultima versione per il tuo progetto. Cambia il link github per puntare al tuo progetto. 206 | 207 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 208 | 209 | ## Note 210 | 211 | Un template di progetto standardizzato con configurazioni semplici e riutilizzabili, gli aggiornamenti per gli script e il codice sono in corso. 212 | -------------------------------------------------------------------------------- /README_ja.md: -------------------------------------------------------------------------------- 1 | # Standard Go Project Layout 2 | 3 | 翻訳: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## 概要 25 | 26 | これは、Goアプリケーションプロジェクトの基本的なレイアウトです。これは、コアとなるGo開発チームによって定義された公式の標準ではありませんが、Goエコシステムの中で、歴史的に共通しているプロジェクトのレイアウトパターンのセットとなっています。これらのパターンの中には、他のパターンよりも人気のあるものもあります。また、現実世界の大規模なアプリケーションに共通するいくつかのサポートディレクトリに加えて、いくつかの小さな機能強化が行われています。 27 | 28 | Goを学ぼうとしている場合や、自分でPoCやおもちゃのプロジェクトを構築しようとしている場合、このプロジェクトレイアウトはやりすぎです。最初は本当にシンプルなものから始めてください（`main.go`ファイルが1つあれば十分です）。プロジェクトが大きくなるにつれて、コードが適切に構造化されているかどうかが重要になることに注意してください。そうしないと、多くの隠れた依存関係やグローバルな状態を持つ厄介なコードになってしまいます。プロジェクトで作業する人が増えれば、さらに多くの構造が必要になります。そこで、パッケージやライブラリを管理するための共通の方法を導入することが重要になります。オープンソースプロジェクトがある場合や、他のプロジェクトがプロジェクトリポジトリからコードをインポートしていることを知っている場合は、プライベートな(内部的な)パッケージやコードを持つことが重要になります。リポジトリをクローンして、必要なものだけを残し、他のものはすべて削除してください。リポジトリにあるからといって、すべてを使わなければならないわけではありません。これらのパターンはすべてのプロジェクトで使われているわけではありません。`vendor`パターンでさえも、万能ではありません。 29 | 30 | Go 1.14では、[`Go Modules`](https://go.dev/wiki/Modules)がついに本番に向けて準備が整いました。使用しない特別な理由がない限り、[`Go Modules`](https://blog.golang.org/using-go-modules) を使用してください。もし使用するのであれば、$GOPATH やプロジェクトをどこに置くかを気にする必要はありません。レポの基本的な `go.mod` ファイルは、プロジェクトが GitHub でホストされていることを前提としていますが、必須ではありません。モジュールパスは何でも構いませんが、最初のモジュールパスコンポーネントの名前にはドットを付けてください (現在の Go のバージョンではもうこれを強制していませんが、少し古いバージョンを使っているのであれば、これを付けなくてもビルドが失敗しても驚かないでください)。これについて詳しく知りたい場合は、Issue [`37554`](https://github.com/golang/go/issues/37554) と [`32819`](https://github.com/golang/go/issues/32819) を参照してください。 31 | 32 | このプロジェクトは意図的に一般的なレイアウトを使用しており、特定のGoパッケージを押し付けているわけではありません。 33 | 34 | これはコミュニティの取り組みです。 新しいパターンが表示された場合、または既存のパターンの1つを更新する必要があると思われる場合は、issueで起票してください。 35 | 36 | 名前付け、フォーマット、スタイルについてサポートが必要な場合は、[`gofmt`](https://golang.org/cmd/gofmt/)と[`golint`](https://github.com/golang/lint)を実行することから始めます。また、次のGoコードスタイルのガイドラインと推奨事項も必ずお読みください: 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | 追加の背景情報については、[`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2)を参照してください。 44 | 45 | パッケージの命名と整理、およびその他のコード構造の推奨事項の詳細: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | パッケージ指向の設計ガイドラインとアーキテクチャレイヤーに関する中国の投稿 52 | * [パッケージ指向の設計とアーキテクチャの階層化](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Goのディレクトリ 55 | 56 | ### `/cmd` 57 | 58 | このプロジェクトの主なアプリケーション。 59 | 60 | 各アプリケーションのディレクトリ名は、欲しい実行ファイルの名前と一致するようにしてください(例: `/cmd/myapp`)。 61 | 62 | アプリケーションディレクトリには多くのコードを入れないようにしましょう。コードをインポートして他のプロジェクトで使えると思うならば、`/pkg`ディレクトリに置くべきです。コードが再利用できない場合や、他の人に再利用してほしくない場合は、そのコードを`/internal`ディレクトリに置いてください。他の人が何をするか驚くでしょうから、自分の意図を明確にしてください。 63 | 64 | このような場合は、`/internal`ディレクトリと`/pkg`ディレクトリからコードをインポートして呼び出す小さなメイン関数を持つのが一般的ですが、それ以外は何もしません。 65 | 66 | 例に関しては、[`/cmd`](cmd/README.md)ディレクトリを参照してください。 67 | 68 | ### `/internal` 69 | 70 | プライベートなアプリケーションやライブラリのコード。これは、他の人が自分のアプリケーションやライブラリにインポートしたくないコードです。このレイアウトパターンは、Goコンパイラによって強制されることに注意してください。詳細については、Go 1.4の[`リリースノート`](https://golang.org/doc/go1.4#internalpackages)を参照してください。トップレベルの内部ディレクトリに限定されないことに注意してください。プロジェクトツリーのどのレベルでも、複数の内部ディレクトリを持つことができます。 71 | 72 | オプションで、内部パッケージに少し余分な構造を追加して、共有内部コードと非共有内部コードを分離することができます。(特に小規模なプロジェクトでは) 必須ではありませんが、パッケージの使用目的を示す視覚的な手がかりがあるのは良いことです。実際のアプリケーションコードは `/internal/app` ディレクトリ (例: `/internal/app/myapp`) に、それらのアプリケーションで共有されるコードは `/internal/pkg` ディレクトリ (例: `/internal/pkg/myprivlib`) に置くことができます。 73 | 74 | ### `/pkg` 75 | 76 | 外部アプリケーションで使用しても問題ないライブラリコード(例: `/pkg/mypubliclib`)。他のプロジェクトは、これらのライブラリが動作することを期待してインポートしますので、ここに何かを置く前によく考えてください :-)。内部ディレクトリは、プライベートパッケージがインポートできないようにするためのより良い方法であることに注意してください。`/pkg` ディレクトリは、そのディレクトリにあるコードが他の人に使われても安全であることを明示的に伝える良い方法です。[`I'll take pkg over internal blog post by Travis Jeffery`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) は、`pkg` ディレクトリと内部ディレクトリの概要と、それらを使用することが意味のある場合の概要を提供しています。 77 | 78 | また、ルートディレクトリにGo以外のコンポーネントやディレクトリが多数含まれている場合は、Goコードを1つの場所にグループ化して、さまざまなGoツールを簡単に実行できるようにする方法でもあります（これらの講演で言及されているように：[`産業用プログラミングのベストプラクティス`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018、[`GopherCon 2018：Kat Zien-How Do You Structure Your Go Apps`](https://www.youtube.com/watch?v=oL6JBUk6tj0) および [`GoLab 2018-Massimiliano Pippi-Goのプロジェクトレイアウトパターン`](https://www.youtube.com/watch?v=3gQa1LWwuzk)）。 79 | 80 | このプロジェクトレイアウトパターンを使用している人気のある Go repos を見たい場合は [`/pkg`](pkg/README.md) ディレクトリを参照してください。これは一般的なレイアウトパターンですが、普遍的に受け入れられているわけではありませんし、Goコミュニティの中には推奨していない人もいます。 81 | 82 | アプリプロジェクトが非常に小さく、追加レベルのネストがあまり価値をもたらさない場合は、使用しないでください（本当に必要な場合を除く:-)）。 それが十分に大きくなり、ルートディレクトリがかなり肥大化してきたときに考えてください（特に、Go以外のアプリコンポーネントがたくさんある場合）。 83 | 84 | ### `/vendor` 85 | 86 | アプリケーションの依存関係 (手動で管理するか、新しい組み込みの [`Go Modules`](https://go.dev/wiki/Modules) 機能のようなお気に入りの依存関係管理ツールで管理します)。`go mod vendor`コマンドは、`/vendor`ディレクトリを作成します。デフォルトでオンになっている Go 1.14 を使用していない場合は、`go build` コマンドに `-mod=vendor` フラグを追加する必要があるかもしれないことに注意してください。 87 | 88 | ライブラリをビルドしている場合は、アプリケーションの依存関係をコミットしないでください。 89 | 90 | [`1.13`](https://golang.org/doc/go1.13#modules) 以降、Go はモジュールプロキシ機能も有効にしています (デフォルトでは [`https://proxy.golang.org`](https://proxy.golang.org) をモジュールプロキシサーバとして使用しています)。[`この機能`](https://blog.golang.org/module-mirror-launch)についての詳細は、ここを読んで、あなたの要件や制約に適合するかどうかを確認してください。そうであれば、ベンダディレクトリは全く必要ありません。 91 | 92 | ## Service Application Directories 93 | 94 | ### `/api` 95 | 96 | OpenAPI/Swaggerの仕様、JSONスキーマファイル、プロトコル定義ファイル。 97 | 98 | 例に関しては、[`/api`](api/README.md)ディレクトリを参照してください。 99 | 100 | ## Web Application Directories 101 | 102 | ### `/web` 103 | 104 | ウェブアプリケーション固有のコンポーネント：静的ウェブアセット、サーバーサイドテンプレート、SPA。 105 | 106 | ## Common Application Directories 107 | 108 | ### `/configs` 109 | 110 | 設定ファイルのテンプレートまたはデフォルトの設定。 111 | 112 | `confd` または `consul-template` テンプレートファイルをここに置きます。 113 | 114 | ### `/init` 115 | 116 | システムinit(systemd, upstart, sysv)とプロセスマネージャ/スーパーバイザ(runit, supervisord)の設定。 117 | 118 | ### `/scripts` 119 | 120 | 様々なビルド、インストール、解析などの操作を行うためのスクリプトです。 121 | 122 | これらのスクリプトはルートレベルの Makefile を小さくシンプルに保ちます (例: [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile))。 123 | 124 | 例に関しては、[`/scripts`](scripts/README.md)ディレクトリを参照してください。 125 | 126 | ### `/build` 127 | 128 | パッケージングと継続的インテグレーション。 129 | 130 | クラウド (AMI)、コンテナ (Docker)、OS (deb、rpm、pkg) パッケージの設定とスクリプトを `/build/package` ディレクトリに置きます。 131 | 132 | CI (travis, circle, drone) の設定とスクリプトを `/build/ci` ディレクトリに配置します。CIツールの中には（Travis CIなど）、設定ファイルの場所に非常にこだわるものがあることに注意してください。コンフィグファイルを `/build/ci` ディレクトリに置き、CIツールが期待する場所にリンクしてみてください（可能であれば）。 133 | 134 | ### `/deployments` 135 | 136 | IaaS、PaaS、システム、コンテナオーケストレーションのデプロイメント設定とテンプレート (docker-compose、kubernetes/helm、mesos、terraform、bosh)。 137 | いくつかのリポジトリ (特に kubernetes でデプロイされたアプリ) では、このディレクトリは `/deploy` と呼ばれていることに注意してください。 138 | 139 | ### `/test` 140 | 141 | 追加の外部テストアプリとテストデータ。`/test`ディレクトリは自由に構成してください。大規模なプロジェクトでは、データのサブディレクトリを持つことは理にかなっています。例えば、`/test/data` や `/test/testdata` などのディレクトリが必要な場合、そのディレクトリにあるものを無視することができます。Go は "." や "_" で始まるディレクトリやファイルも無視するので、テストデータディレクトリの名前の付け方に柔軟性があることに注意してください。 142 | 143 | 例に関しては、[`/test`](test/README.md)ディレクトリを参照してください。 144 | 145 | ## 他のディレクトリ 146 | 147 | ### `/docs` 148 | 149 | デザインドキュメントとユーザードキュメント (godocで生成されたドキュメントに加えて)。 150 | 151 | 例に関しては、[`/docs`](docs/README.md)ディレクトリを参照してください。 152 | 153 | ### `/tools` 154 | 155 | このプロジェクトをサポートするツールです。これらのツールは `/pkg` と `/internal` ディレクトリからコードをインポートできることに注意してください。 156 | 157 | 例に関しては、[`/tools`](tools/README.md)ディレクトリを参照してください。 158 | 159 | ### `/examples` 160 | 161 | あなたのアプリケーション、またはpublic librariesのための例。 162 | 163 | 例に関しては、[`/examples`](examples/README.md)ディレクトリを参照してください。 164 | 165 | ### `/third_party` 166 | 167 | 外部ヘルパーツール、フォークされたコード、その他のサードパーティ製ユーティリティ（Swagger UIなど）。 168 | 169 | ### `/githooks` 170 | 171 | Gitフック。 172 | 173 | ### `/assets` 174 | 175 | リポジトリに付随するその他のアセット（画像、ロゴなど）。 176 | 177 | ### `/website` 178 | 179 | GitHubページを使用していない場合は、プロジェクトのWebサイトのデータを置く場所です。 180 | 181 | 例に関しては、[`/website`](website/README.md)ディレクトリを参照してください。 182 | 183 | ## 作成してはいけないディレクトリ 184 | 185 | ### `/src` 186 | 187 | Goプロジェクトの中には `src` フォルダを持っているものもありますが、これは通常、開発者が一般的なパターンであるJavaの世界から来た場合に起こります。可能であれば、このようなJavaのパターンを採用しないようにしてください。あなたのGoコードやGoプロジェクトがJavaのように見えることは本当に避けてください。 188 | 189 | プロジェクトレベルの `/src` ディレクトリと、[`Goコードの書き方`](https://golang.org/doc/code.html)で説明されているように、Go がワークスペースに使用する `/src` ディレクトリを混同しないようにしてください。環境変数 `$GOPATH` は、(現在の)ワークスペースを指します (Windows 以外のシステムでは、デフォルトでは `$HOME/go` を指します)。このワークスペースには、トップレベルの `/pkg`, `/bin`, `/src` ディレクトリが含まれています。実際のプロジェクトは `/src` の下のサブディレクトリになりますので、プロジェクト内に `/src` ディレクトリがある場合、プロジェクトのパスは以下のようになります。`/some/path/to/workspace/src/your_project/src/your_code.go` のようになります。Go 1.11 では、プロジェクトを `GOPATH` の外に置くことができますが、このレイアウトパターンを使うのが良いというわけではないことに注意してください。 190 | 191 | ## Badges 192 | 193 | * [Go Report Card](https://goreportcard.com/) - `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license`, `misspell` でコードをスキャンします。`github.com/golang-standards/project-layout` をプロジェクトリファレンスに置き換えてください。 194 | 195 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 196 | 197 | * ~~[GoDoc](http://godoc.org) - GoDocで作成したドキュメントのオンライン版を提供します。リンクを自分のプロジェクトへのリンクに変更してください。~~ 198 | 199 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 200 | 201 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.devは、Goの発見とドキュメントの新しい目的地です。[バッジ生成ツール](https://pkg.go.dev/badge)を使ってバッジを作成することができます。 202 | 203 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 204 | 205 | * リリース - あなたのプロジェクトの最新のリリース番号が表示されます。githubのリンクを変更して、あなたのプロジェクトを指すようにしてください。 206 | 207 | [![リリース](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 208 | 209 | ## 注意事項 210 | 211 | サンプル/再利用可能なコンフィグ、スクリプト、コードを備えた、より意見の多いプロジェクトテンプレートはWIPです。 212 | -------------------------------------------------------------------------------- /README_ko.md: -------------------------------------------------------------------------------- 1 | # 표준 Go 프로젝트 레이아웃 2 | 3 | 번역: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## 개요 25 | 26 | 이 레포지토리는 Go 애플리케이션 프로젝트의 기본 레이아웃입니다. 이 레포지토리는 코어 Go 개발팀에 의해 정의된 공식적인 표준은 아니지만, Go 생태계에서 역사적이거나 급부상중인 프로젝트 레이아웃 패턴들의 공통된 부분들입니다. 몇몇 패턴들은 다른 패턴들보다 유명합니다. 또한 이는 충분히 큰 현실세계 애플리케이션들에서 공통적으로 사용하는 여러 보조 디렉터리와 함께 다수의 작은 개선 사항들을 포함하고 있습니다. 27 | 28 | 만약 당신이 Go를 배우려하거나, 혼자 PoC나 토이 프로젝트를 만드는 거라면 이 프로젝트 레이아웃은 과한 것입니다. 아주 간단한 것부터 시작하세요 (`main.go` 파일 하나면 아주 충분합니다). 프로젝트가 성장하면서 당신의 코드가 잘 구조화 되도록 하는 것이 중요합니다. 그렇지 않으면 많은 숨겨진 종속성들과 전역 상태가 있는 지저분한 코드로 끝나게 될 것 입니다. 더 많은 사람들이 프로젝트에 참여할 때 더 많은 구조가 필요합니다. 그 때가 패키지/라이브러리를 관리하는 공통된 방법을 도입하는 것이 중요한 시점입니다. 당신이 오픈 소스 프로젝트를 가지고 있거나 다른 프로젝트가 당신의 프로젝트 레포지토리에서 코드를 임포트 하고있다면 프라이빗 (`internal` 로 일컫어지는) 패키지와 코드를 도입하는게 중요합니다. 이 레포지토리를 Clone하고, 당신에게 필요한것만 남긴다음 나머지 것들을 다 지우세요! 거기에 있다고 해서 다 사용해야하는 것은 아닙니다. 모든 프로젝트에서 다 사용하는 패턴은 없습니다. `vendor`패턴 조차 보편적이지 않습니다. 29 | 30 | Go 1.14로 [`Go Modules`](https://go.dev/wiki/Modules) 은 최종적으로 프로덕션 준비가 완료되었습니다. 특별히 사용하지 않을 사유가 없다면 [`Go Modules`](https://blog.golang.org/using-go-modules) 를 사용하세요. 그러면 $GOPATH와 어디에 내 프로젝트를 놓을지 고민할 필요가 없습니다. 레포지토리에서 기본적인 `go.mod` 파일은 프로젝트가 GitHub에 호스팅되어있다고 가정합니다만, 필수사항은 아닙니다. 모듈 패스는 어느것이든 될 수 있지만 첫번째 모듈 패스 컴포넌트는 그 이름에 점이 있어야 합니다. (현재 버전의 Go는 더이상 이를 강제하지는 않지만, 만약 조금 더 오래된 버전을 사용하고 있다면 점이 없을때 빌드가 실패해도 놀라지 마세요). 이에 대해 더 알아보고 싶으시면 이슈 [`37554`](https://github.com/golang/go/issues/37554) 와 [`32819`](https://github.com/golang/go/issues/32819) 를 읽어보세요. 31 | 32 | 이 프로젝트 레이아웃은 의도적으로 일반적이며 특정 Go 패키지 구조를 강요하지 않습니다. 33 | 34 | 이 레포지토리는 커뮤니티의 노력입니다. 새 패턴을 찾았거나, 있는 패턴들 중 하나가 업데이트가 필요하다고 생각된다면 이슈를 열어주세요. 35 | 36 | 네이밍, 포매팅, 스타일에 대해 도움이 필요하시다면, [`gofmt`](https://golang.org/cmd/gofmt/) 와 [`golint`](https://github.com/golang/lint)를 돌리는 것으로 시작해보세요. 또한 Go 코드 스타일 가이드라인과 권장 사항들을 꼭 읽어보세요: 37 | 38 | * https://talks.golang.org/2014/names.slide 39 | * https://golang.org/doc/effective_go.html#names 40 | * https://blog.golang.org/package-names 41 | * https://go.dev/wiki/CodeReviewComments 42 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 43 | 44 | 자세한 배경 지식에 대해서는 [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) 를 확인하세요. 45 | 46 | 다른 코드 구조 추천과 네이밍과 패키지 구성에 대해 더 알아보기: 47 | 48 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 49 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 50 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 51 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 52 | 53 | 패키지 지향 디자인 가이드라인과 설계 레이어에 대한 중국어 글 54 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 55 | 56 | ## Go 디렉터리 57 | 58 | ### `/cmd` 59 | 60 | 이 프로젝트의 메인 애플리케이션들입니다. 61 | 62 | 각 애플리케이션의 디렉터리명은 만들고싶은 실행 파일 이름과 같아야 합니다 (e.g., `/cmd/myapp`). 63 | 64 | 애플리케이션 디렉터리에 많은 코드를 넣지마세요. 다른 프로젝트들에서 임포트되고 사용될 것 같으면, `/pkg` 디렉터리에 있어야합니다. 코드가 재사용성이 없거나 다른사람들이 재사용하지 않기를 바란다면 코드를 `/internal` 디렉터리에 넣으세요. 다른사람들이 무얼 할지 놀라게 될거에요. 그러니 의도를 분명하게 밝혀주세요! 65 | 66 | 흔히 `/internal`와 `/pkg` 디렉터리 코드를 임포트, 호출만 하는 작은 `main` 함수는 흔히 볼 수 있습니다. 67 | 68 | 예시는 [`/cmd`](cmd/README.md)를 보세요. 69 | 70 | ### `/internal` 71 | 72 | 개인적인 애플리케이션과 라이브러리 코드. 다른 사람들이 애플리케이션이나 라이브러리에서 임포트 하기를 원하지 않는 코드들입니다. 이 레이아웃 패턴은 Go 컴파일러 자체에 강제됩니다. 더 알아보고 싶다면 Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) 를 참고하세요. 이는 최상단 `internal` 디렉터리에 국한되는 것은 아닙니다. 프로젝트 트리의 모든 레벨에서 하나 이상의 `internal` 디렉터리를 가질 수 있습니다. 73 | 74 | Internal 패키지에서 공유되는 내부 코드와 공유되지 않는 내부 코드를 구분하기 위해 부가적인 구조체를 추가할 수 있습니다. 필수사항은 아니지만(특히 작은 프로젝트에서는), 의도된 패키지 사용법을 보여주는 시각적인 단서를 남기는 것이 좋습니다. 실제 에플리케이션 코드는 `/internal/app` 디렉터리에 넣고 (e.g., `/internal/app/myapp`) , 그 앱들에서 공유되는 코드들은 `/internal/pkg` 디렉터리 (e.g., `/internal/pkg/myprivlib`) 에 넣을 수 있습니다. 75 | 76 | ### `/pkg` 77 | 78 | 외부 애플리케이션에서 사용되어도 괜찮은 라이브러리 코드입니다 (e.g., `/pkg/mypubliclib`). 다른 프로젝트는 이 라이브러리들이 작동할거라고 예상하고 임포트 할 것 이므로, 여기에 무언가를 넣기 전에 두번 고민하세요 :-) `internal`디렉터리는 개인적인 패키지들이 임포트 불가능하도록 하는 더 좋은 방법인데, 이유는 Go가 이를 강제하기 때문입니다. `/pkg` 디렉터리는 그 디렉터리 안의 코드가 다른 사람들에 의해 사용되어도 안전하다고 명시적으로 보여주는 좋은 방법입니다. Travis Jeffery의 [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) 블로그 포스트는 `pkg` 와 `internal` 디렉터리와 언제 쓰는게 맞을지에 대해 좋은 개요를 제공합니다. 79 | 80 | 또한 루트 디렉터리에 많은 Go가 아닌 컴포넌트와 디렉터리를 포함하고 있다면 Go 코드를 한 곳에 모아서 다양한 Go 툴들을 쉽게 실행할 수 있습니다 (이 발표들에서 언급되었던것 처럼: GopherCon EU 2018의 [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg), [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 와 [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 81 | 82 | 이 프로젝트 레이아웃 패턴을 사용하는 유명한 Go 레포지토리들을 보고 싶다면 [`/pkg`](pkg/README.md)를 보세요. 이는 흔한 레이아웃 패턴이나, 보편적으로 받아드려지는 것은 아니며 Go 커뮤니티의 일부는 이를 추천하지 않습니다. 83 | 84 | 앱 프로젝트가 정말 작고 추가적인 레벨의 중첩이 많이 효과적이지 않다면 사용하지 않아도 괜찮습니다 (정말로 원하지 않는 한 :-)). 프로젝트가 더 커지고 루트 디렉터리가 꽤 바빠질 때 고려해보세요 (특히 Go가 아닌 앱 컴포넌트가 많이 있다면). 85 | 86 | ### `/vendor` 87 | 88 | 애플리캐이션 종속성 (직접 혹은 새 빌트인 [`Go Modules`](https://go.dev/wiki/Modules) 피쳐와 같은 종속성 관리 도구로 관리되는). `go mod vendor` 명령어는 `/vendor` 디렉터리를 만들어 줄 것 입니다. `go build` 명령어를 사용할 때 Go 1.14를 사용하지 않는다면 Go 1.14에서 기본으로 켜져있는 `-mod=vendor` 플래그를 추가해야 할 수 있습니다. 89 | 90 | 만약 당신이 라이브러리를 만들고 있다면 당신의 애플리케이션 종속성을 커밋하지 마세요. 91 | 92 | [`1.13`](https://golang.org/doc/go1.13#modules)부터 Go는 모듈 프록시 기능(기본적으로 [`https://proxy.golang.org`](https://proxy.golang.org)를 모듈 프록시 서버로 사용하여)을 활성화하였습니다. 이것이 당신의 요구조건과 제한사항을 모두 만족하는지 보려면 [`여기`](https://blog.golang.org/module-mirror-launch) 를 읽어보세요. 만약 만족한다면, `vendor` 디렉터리가 전혀 필요하지 않을 것입니다. 93 | 94 | ## 서비스 애플리케이션 디렉터리 95 | 96 | ### `/api` 97 | 98 | OpenAPI/Swagger 스펙들, JSON schema 파일들, 프로토콜 정의 파일들. 99 | 100 | 예시로 [`/api`](api/README.md) 디렉터리를 확인하세요. 101 | 102 | ## 웹 애플리케이션 디렉터리 103 | 104 | ### `/web` 105 | 106 | 웹 플리케이션의 특정한 컴포넌트들: 정적 웹 에셋들, 서버 사이드 템플릿과 SPA들. 107 | 108 | ## 공통 애플리케이션 디렉터리 109 | 110 | ### `/configs` 111 | 112 | 설정 파일 템플릿이나 기본 설정들. 113 | 114 | `confd` or `consul-template` 템플릿 파일들을 여기에 놓으세요. 115 | 116 | ### `/init` 117 | 118 | 시스템 init (systemd, upstart, sysv) 과 프로세스 매니저/슈퍼바이저 (runit, supervisord) 설정들. 119 | 120 | ### `/scripts` 121 | 122 | 빌드, 설치, 분석, 기타 작업을 위한 스크립트들. 123 | 124 | 이 스크립트들은 루트의 Makefile을 작고 간단하게 유지해줍니다 (e.g., [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 125 | 126 | 예시로 [`/scripts`](scripts/README.md) 디렉터리를 확인하세요. 127 | 128 | ### `/build` 129 | 130 | 패키징과 지속적인 통합(CI). 131 | 132 | 클라우드 (AMI), 컨테이너 (Docker), OS (deb, rpm, pkg) 패키지 설정과 스크립트를 `/build/package` 디렉터리에 넣으세요. 133 | 134 | CI (travis, circle, drone) 설정과 스크립트를 `/build/ci`에 넣으세요. 몇몇 CI 도구들은 (e.g., Travis CI) 설정파일들 위치에 대해 굉장히 까다롭다는 것을 알아두세요. 설정 파일들을 `/build/ci` 에 넣고 CI 도구들이 기대하는 위치에 링크해보세요. (가능하다면). 135 | 136 | ### `/deployments` 137 | 138 | IaaS, PaaS, 시스템과 컨테이너 오케스트레이션 배포 설정과 템플릿 (docker-compose, kubernetes/helm, mesos, terraform, bosh). 몇몇 레포지토리 (특히 쿠버네티스로 배포되는 앱들) 에서 이 디렉터리는 `/deploy` 라고 불립니다. 139 | 140 | ### `/test` 141 | 142 | 추가적인 외부 테스트 앱들과 테스트 데이터들. `/test` 디렉터리를 자유롭게 구조화하세요. 더 큰 프로젝트에서 데이터 서브디렉터리를 갖는것이 합당합니다. 예시로, 이 디렉터리에 무엇이 있는지 Go가 무시하려면 `/test/data` 또는 `/test/testdata` 를 만들면 됩니다. Go는 "." 나 "_" 로 시작하는 디렉터리들이나 파일들도 무시하니, 테스트 데이터 디렉터리 이름을 더 자유롭게 지을 수 있습니다. 143 | 144 | 예시로 [`/test`](test/README.md) 디렉터리를 확인하세요. 145 | 146 | ## 다른 디렉터리들 147 | 148 | ### `/docs` 149 | 150 | 디자인과 사용자 문서들 (godoc이 만든 문서에 더불어). 151 | 152 | 예시로 [`/docs`](docs/README.md) 디렉터리를 확인하세요. 153 | 154 | ### `/tools` 155 | 156 | 이 프로젝트에서 사용하는 도구들. 이 도구들이 `/pkg` 나 `/internal` 디렉터리에서 코드를 임포트 할 수 있음을 알아두세요. 157 | 158 | 예시로 [`/tools`](tools/README.md) 디렉터리를 확인하세요. 159 | 160 | ### `/examples` 161 | 162 | 애플리케이션 혹은 공개된 라이브러리의 예시들. 163 | 164 | 예시로 [`/examples`](examples/README.md) 디렉터리를 확인하세요. 165 | 166 | ### `/third_party` 167 | 168 | 사용하는 외부 도구들, 포크된 코드들과 다른 서드 파티 유틸리티들 (e.g., Swagger UI). 169 | 170 | ### `/githooks` 171 | 172 | Git hooks. 173 | 174 | ### `/assets` 175 | 176 | 레포지토리와 함께 사용될 에셋들 (이미지, 로고, 기타). 177 | 178 | ### `/website` 179 | 180 | GitHub pages를 사용하고 있지 않다면 프로젝트의 웹사이트 데이터를 넣는 곳입니다. 181 | 182 | 예시로 [`/website`](website/README.md) 디렉터리를 확인하세요. 183 | 184 | ## 있으면 안되는 디렉터리 185 | 186 | ### `/src` 187 | 188 | 몇몇 Go 프로젝트들은 분명 `src` 폴더를 가지고 있으나, 이는 개발자들이 해당 패턴이 흔한 Java 세계에서 왔을 때 대부분 발생합니다. 만약 할 수 있다면 이 Java 패턴을 사용하지 않도록 해보세요. Go 코드나 Go 프로젝트가 Java처럼 보이는걸 원하지 않잖아요 :-) 189 | 190 | 프로젝트 레벨의 `/src` 디렉터리와 [`How to Write Go Code`](https://golang.org/doc/code.html)에서 설명된 것 처럼 Go에서 워크스페이스로 사용하는 `/src` 디렉터리와 혼동하지 마세요. `$GOPATH` 환경 변수는 당신의 (현재) 워크스페이스를 가리킵니다 (기본적으로 윈도우가 아닌 시스템에서는 `$HOME/go`를 가리킵니다). 이 워크스페이스는 최상위 `/pkg`, `/bin` , `/src` 디렉터리를 포함하고 있습니다. 실제 프로젝트는 결국 `/src`의 서브디렉터리이므로, 프로젝트 안에 `/src` 디렉터리가 있다면 프로젝트 주소는 이럴 것입니다: `/some/path/to/workspace/src/your_project/src/your_code.go`. Go 1.11에서는 `GOPATH` 밖에 프로젝트를 만드는게 가능하지만, 이 레이아웃 패턴을 사용하는게 좋다는 뜻은 아님을 알아두세요. 191 | 192 | 193 | ## 뱃지 194 | 195 | * [Go Report Card](https://goreportcard.com/) - 이는 당신의 코드를 `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license`, `misspell`로 스캔합니다. `github.com/golang-standards/project-layout` 를 당신의 프로젝트 주소로 바꾸세요. 196 | 197 | * ~~[GoDoc](http://godoc.org) - 온라인 버전의 GoDoc 생성 문서를 제공합니다. 당신의 프로젝트를 가리키도록 링크를 바꾸세요.~~ 198 | 199 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev는 Go 검색 및 문서들을 위한 새로운 사이트입니다. [badge generation tool](https://pkg.go.dev/badge)을 사용해서 새로운 뱃지를 만들 수 있습니다. 200 | 201 | * Release - 프로젝트의 최신 릴리즈 넘버를 보여줍니다. 당신의 프로젝트를 가리키도록 깃헙 링크를 바꾸세요. 202 | 203 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 204 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 205 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 206 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 207 | 208 | ## 참고 209 | 210 | 샘플/재사용 가능한 설정, 스크립트와 코드를 포함하는 더 의견이 담긴 프로젝트 템플릿은 작업 중입니다. 211 | 212 | -------------------------------------------------------------------------------- /README_ptBR.md: -------------------------------------------------------------------------------- 1 | # Layout padrão de projetos em Go 2 | 3 | Traduções: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## Visão geral 25 | 26 | Este é um layout básico para projetos de aplicações em Go. Não é um padrão oficial definido pela equipe de desenvolvimento principal do Go; no entanto, é um conjunto de padrões de layout de projetos históricos e emergentes comuns no ecossistema Go. Alguns desses padrões são mais populares do que outros. Ele também possui uma série de pequenos aprimoramentos junto com vários diretórios de suporte comuns a qualquer aplicativo grande o suficiente do mundo real. 27 | 28 | Se você está tentando aprender Go, se está construindo um PoC(Prova de conceito) ou um pequeno projeto pessoal para você, este layout de projeto é um exagero. Comece com algo realmente simples (um único arquivo `main.go` é mais do que suficiente). Conforme seu projeto cresce, lembre-se de que será importante garantir que seu código esteja bem estruturado, caso contrário, você acabará com um código confuso com muitas dependências ocultas e estados globais. Quando você tiver mais pessoas trabalhando no projeto, precisará de ainda mais estrutura. É quando é importante apresentar uma maneira comum de gerenciar pacotes/bibliotecas. Quando você tem um projeto de código aberto ou quando conhece outros projetos, importe o código do seu repositório de projetos, é quando é importante ter pacotes e códigos privados (também conhecidos como `internal`). Clone o repositório, mantenha o que você precisa e exclua todo o resto! Só porque está lá, não significa que você precise usar tudo. Nenhum desses padrões é usado em todos os projetos. Mesmo o padrão `vendor` não é universal. 29 | 30 | Com Go 1.14 [`Go Modules`](https://go.dev/wiki/Modules) estão finalmente prontos para produção. Use [`Go Modules`](https://blog.golang.org/using-go-modules) a menos que você tenha um motivo específico para não usá-los e, se tiver, não precisa se preocupar com $GOPATH e onde você colocou seu projeto. O arquivo `go.mod` básico no reposiório assume que seu projeto está hospedado no GitHub, mas não é um requisito. O caminho do módulo pode ser qualquer coisa, embora o primeiro componente do caminho do módulo deva ter um ponto em seu nome (a versão atual do Go não o impõe mais, mas se você estiver usando versões um pouco mais antigas, não se surpreenda se suas compilações falharem sem isto). Veja as issues [`37554`](https://github.com/golang/go/issues/37554) e [`32819`](https://github.com/golang/go/issues/32819) se você quiser saber mais sobre isso. 31 | 32 | Este layout de projeto é intencionalmente genérico e não tenta impor uma estrutura de pacote Go específica. 33 | 34 | Este é um esforço da comunidade. Abra uma nova issue se você ver um novo padrão ou se você acha que um dos padrões existentes precisa ser atualizado. 35 | 36 | Se precisar de ajuda com nomenclatura, formatação e estilo, comece executando [`gofmt`](https://golang.org/cmd/gofmt/) e [`golint`](https://github.com/golang/lint). Além disso, certifique-se de ler estas diretrizes e recomendações de estilo de código Go: 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | Veja [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) para obter informações adicionais. 44 | 45 | Mais sobre como nomear e organizar pacotes, bem como outras recomendações de estrutura de código: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | Uma postagem chinesa sobre as diretrizes de design orientado a pacotes e a camada de arquitetura 52 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Diretórios Go 55 | 56 | ### `/cmd` 57 | 58 | Principais aplicações para este projeto. 59 | 60 | O nome do diretório para cada aplicação deve corresponder ao nome do executável que você deseja ter (ex. `/cmd/myapp`). 61 | 62 | Não coloque muitos códigos no diretório da aplicação. Se você acha que o código pode ser importado e usado em outros projetos, ele deve estar no diretório `/pkg`. Se o código não for reutilizável ou se você não quiser que outros o reutilizem, coloque esse código no diretório `/internal`. Você ficará surpreso com o que os outros farão, então seja explícito sobre suas intenções! 63 | 64 | É comum ter uma pequena função `main` que importa e invoca o código dos diretórios` /internal` e `/pkg` e nada mais. 65 | 66 | Veja o diretório [`/cmd`](cmd/README.md) para mais exemplos. 67 | 68 | ### `/internal` 69 | 70 | Aplicação privada e código de bibliotecas. Este é o código que você não quer que outras pessoas importem em suas aplicações ou bibliotecas. Observe que esse padrão de layout é imposto pelo próprio compilador Go. Veja o Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) para mais detalhes. Observe que você não está limitado ao diretório `internal` de nível superior. Você pode ter mais de um diretório `internal` em qualquer nível da árvore do seu projeto. 71 | 72 | Opcionalmente, você pode adicionar um pouco de estrutura extra aos seus pacotes internos para separar o seu código interno compartilhado e não compartilhado. Não é obrigatório (especialmente para projetos menores), mas é bom ter dicas visuais que mostram o uso pretendido do pacote. Seu atual código da aplicação pode ir para o diretório `/internal/app` (ex. `/internal/app/myapp`) e o código compartilhado por essas aplicações no diretório `/internal/pkg` (ex. `/internal/pkg/myprivlib`). 73 | 74 | ### `/pkg` 75 | 76 | Código de bibliotecas que podem ser usados por aplicativos externos (ex. `/pkg/mypubliclib`). Outros projetos irão importar essas bibliotecas esperando que funcionem, então pense duas vezes antes de colocar algo aqui :-) Observe que o diretório `internal` é a melhor maneira de garantir que seus pacotes privados não sejam importáveis porque é imposto pelo Go. O diretório `/pkg` contudo é uma boa maneira de comunicar explicitamente que o código naquele diretório é seguro para uso. [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) A postagem no blog de Travis Jeffery fornece uma boa visão geral dos diretórios `pkg` e` internal`, e quando pode fazer sentido usá-los. 77 | 78 | É também uma forma de agrupar o código Go em um só lugar quando o diretório raiz contém muitos componentes e diretórios não Go, tornando mais fácil executar várias ferramentas Go (conforme mencionado nestas palestras: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) da GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) e [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 79 | 80 | Consulte o diretório [`/pkg`](pkg/README.md) se quiser ver quais repositórios Go populares usam esse padrão de layout de projeto. Este é um padrão de layout comum, mas não é universalmente aceito e alguns na comunidade Go não o recomendam. 81 | 82 | Não há problema em não usá-lo se o projeto do seu aplicativo for muito pequeno e onde um nível extra de aninhamento não agrega muito valor (a menos que você realmente queira :-)). Pense nisso quando estiver ficando grande o suficiente e seu diretório raiz ficar muito ocupado (especialmente se você tiver muitos componentes de aplicativos não Go). 83 | 84 | ### `/vendor` 85 | 86 | Dependências de aplicativos (gerenciadas manualmente ou por sua ferramenta de gerenciamento de dependências favorita, como o novo recurso integrado [`Go Modules`](https://go.dev/wiki/Modules)). O comando `go mod vendor` criará o diretório` /vendor` para você. Note que você pode precisar adicionar a flag `-mod=vendor` ao seu comando` go build` se você não estiver usando Go 1.14 onde ele está ativado por padrão. 87 | 88 | Não comprometa as dependências do seu aplicativo se você estiver construindo uma biblioteca. 89 | 90 | Observe que desde o Go [`1.13`](https://golang.org/doc/go1.13#modules) também habilitou o recurso de proxy do módulo (usando [`https://proxy.golang.org`](https://proxy.golang.org) como servidor proxy de módulo por padrão). Leia mais sobre isso [`aqui`](https://blog.golang.org/module-mirror-launch) para ver se ele se encaixa em todos os seus requisitos e restrições. Se isso acontecer, então você não precisará do diretório `vendor`. 91 | 92 | ## Diretórios de aplicativos de serviço 93 | 94 | ### `/api` 95 | 96 | Especificações OpenAPI/Swagger, arquivos de esquema JSON, arquivos de definição de protocolo. 97 | 98 | Veja o diretório [`/api`](api/README.md) para mais exemplos. 99 | 100 | ## Diretórios de aplicativos da web 101 | 102 | ### `/web` 103 | 104 | Componentes específicos de aplicativos da Web: ativos estáticos da Web, modelos do lado do servidor e SPAs. 105 | 106 | ## Diretórios de aplicativos comuns 107 | 108 | ### `/configs` 109 | 110 | Modelos de arquivo de configuração ou configurações padrão. 111 | 112 | Coloque seus arquivos de modelo `confd` ou` consul-template` aqui. 113 | 114 | ### `/init` 115 | 116 | Configurações de inicialização do sistema (systemd, upstart, sysv) e gerenciador/supervisor de processos (runit, supervisord). 117 | 118 | ### `/scripts` 119 | 120 | Scripts para executar várias operações de construção, instalação, análise, etc. 121 | 122 | Esses scripts mantêm o Makefile de nível raiz pequeno e simples (ex. [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 123 | 124 | Veja o diretório [`/scripts`](scripts/README.md) para mais exemplos. 125 | 126 | ### `/build` 127 | 128 | Empacotamento e integração contínua. 129 | 130 | Coloque suas configurações de pacote e scripts em nuvem (AMI), contêiner (Docker), sistema operacional (deb, rpm, pkg) no diretório `/build/package`. 131 | 132 | Coloque suas configurações e scripts de CI (travis, circle, drone) no diretório `/build/ci`. Observe que algumas das ferramentas de CI (por exemplo, Travis CI) são muito exigentes quanto à localização de seus arquivos de configuração. Tente colocar os arquivos de configuração no diretório `/build/ci` vinculando-os ao local onde as ferramentas de CI os esperam (quando possível). 133 | 134 | ### `/deployments` 135 | 136 | IaaS, PaaS, configurações e modelos de implantação de orquestração de sistema e contêiner (docker-compose, kubernetes / helm, mesos, terraform, bosh). Observe que em alguns repositórios (especialmente em aplicativos implantados com kubernetes), esse diretório é denominado `/deploy`. 137 | 138 | ### `/test` 139 | 140 | Aplicações de testes externos adicionais e dados de teste. Sinta-se à vontade para estruturar o diretório `/test` da maneira que quiser. Para projetos maiores, faz sentido ter um subdiretório de dados. Por exemplo, você pode ter `/test/data` ou` /test/testdata` se precisar que o Go ignore o que está naquele diretório. Observe que o Go também irá ignorar diretórios ou arquivos que começam com "." ou "_", para que você tenha mais flexibilidade em termos de como nomear seu diretório de dados de teste. 141 | 142 | Veja o diretório [`/test`](test/README.md) para mais exemplos. 143 | 144 | ## Outros diretórios 145 | 146 | ### `/docs` 147 | 148 | Documentos do projeto e do usuário (além da documentação gerada pelo godoc). 149 | 150 | Veja o diretório [`/docs`](docs/README.md) para mais exemplos. 151 | 152 | ### `/tools` 153 | 154 | Ferramentas de suporte para este projeto. Observe que essas ferramentas podem importar código dos diretórios `/pkg` e` /internal`. 155 | 156 | Veja o diretório [`/tools`](tools/README.md) para mais exemplos. 157 | 158 | ### `/examples` 159 | 160 | Exemplos para seus aplicativos e / ou bibliotecas públicas. 161 | 162 | Veja o diretório [`/examples`](examples/README.md) para mais exemplos. 163 | 164 | ### `/third_party` 165 | 166 | Ferramentas auxiliares externas, código bifurcado e outros utilitários de terceiros (por exemplo, Swagger UI). 167 | 168 | ### `/githooks` 169 | 170 | Git hooks. 171 | 172 | ### `/assets` 173 | 174 | Outros recursos para acompanhar seu repositório (imagens, logotipos etc). 175 | 176 | ### `/website` 177 | 178 | Este é o lugar para colocar os dados do site do seu projeto se você não estiver usando as páginas do GitHub. 179 | 180 | Veja o diretório [`/website`](website/README.md) para mais exemplos. 181 | 182 | ## Diretórios que você não deveria ter 183 | 184 | ### `/src` 185 | 186 | Alguns projetos Go têm uma pasta `src`, mas normalmente acontece quando os devs vêm do mundo Java, onde é um padrão comum. Se você puder se ajudar, tente não adotar esse padrão Java. Você realmente não quer que seu código Go ou projetos Go se pareçam com Java :-) 187 | 188 | Não confunda o diretório `/src` do nível do projeto com o diretório` /src` que Go usa para seus espaços de trabalho, conforme descrito em [`How to Write Go Code`](https://golang.org/doc/code.html). A variável de ambiente `$GOPATH` aponta para sua área de trabalho(atual) (por padrão, ela aponta para` $HOME/go` em sistemas não Windows). Este espaço de trabalho inclui os diretórios de nível superior `/pkg`,` /bin` e `/src`. Seu projeto atual acaba sendo um subdiretório em `/ src`, então se você tiver o diretório` /src` em seu projeto, o caminho do projeto será parecido com este: `/algum/caminho/para/workspace/src/your_project/src/ your_code.go`. Observe que com Go 1.11 é possível ter seu projeto fora de seu `GOPATH`, mas ainda não significa que é uma boa ideia usar este padrão de layout. 189 | 190 | 191 | ## Distintivos 192 | 193 | * [Go Report Card](https://goreportcard.com/) - Ele irá escanear seu código com `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` e `misspell`. Substitua `github.com/golang-standards/project-layout` com sua referência de projeto. 194 | 195 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 196 | 197 | * ~~[GoDoc](http://godoc.org) - Ele fornecerá uma versão online da documentação gerada pelo GoDoc. Mude o link para apontar para seu projeto.~~ 198 | 199 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 200 | 201 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev é um novo destino para Go discovery e docs. Você pode criar um emblema usando o [badge generation tool](https://pkg.go.dev/badge). 202 | 203 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 204 | 205 | * Release - Ele mostrará o número da versão mais recente do seu projeto. Altere o link do github para apontar para seu projeto. 206 | 207 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 208 | 209 | ## Notas 210 | 211 | Um modelo de projeto mais opinativo com configurações, scripts e código de amostra/reutilizáveis é um WIP. 212 | -------------------------------------------------------------------------------- /README_ro.md: -------------------------------------------------------------------------------- 1 | # Structură standard pentru aplicațiile Go 2 | 3 | Traduceri: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## General 25 | 26 | Aceasta este o structură de bază pentru aplicațiile Go. Nu este un standard oficial definit de echipa Go; însă reprezintă un set de structuri/modele comune folosite de-a lungul timpului în aplicațiile din ecosistemul Go. Unele sunt mai populare decât altele. Sunt prezente și îmbunătățiri, cu directoare specifice unei aplicații de mari dimensiuni. 27 | 28 | Dacă încerci să înveți Go sau să creezi un PoC/proiect hobby aceasta structură este excesivă. Începe cu ceva foarte simplu (un fișier `main.go` e de ajuns). Pe măsură ce proiectul crește ține minte că va fi nevoie să îl structurezi, altfel te vei trezi cu mult cod spagettă și dependințe/state-uri globale greu de întreținut. Când sunt mai mulți oameni care lucrează la proiect, vei avea nevoie de o structură și mai bună. Din acest motiv este important să introduci un mod comun de gestionare a librăriilor/package-urilor. Când ai un proiect open-source, când știi că alte proiecte importă codul din proiectul tău, e important să ai module (packages) private (internal). Clonează acest repo și ține doar ce ai nevoie. Doar pentru că e acolo, nu înseamnă că trebuie să îl folosești. Aceste standarde nu sunt folosite în toate proiectele Go, nici măcar cel comun `vendor` nu este universal. 29 | 30 | De la apariția Go 1.14 [`Go Modules`](https://go.dev/wiki/Modules) sunt gata de producție (production mode). Folosește [`Go Modules`](https://blog.golang.org/using-go-modules) doar dacă nu ai un motiv specific de a nu le folosești. Dacă nu vrei să le folosești atunci nu este nevoie să te gândești la $GOPATH și unde să îți plasezi proiectul. Fișierul `go.mod` din repo-ul tău asumă că proiectul îți este hostat pe Github, însă asta nu e o necesitate. Calea (path) modulelor poate fi orice, însă primul modul component ar trebui să aibă un punct în numele său (versiunea curentă Go nu o mai cere explicit însă dacă folosești o versiune mai veche nu fi surprins dacă primești erori la compilare). Vezi problemele [`37554`](https://github.com/golang/go/issues/37554) și [`32819`](https://github.com/golang/go/issues/32819) dacă vrei să afli mai multe. 31 | 32 | Această structură este intenționat generică și nu își dorește să impună un standard în gestiunea modulelor Go. 33 | 34 | Această structură este un efort al comunității. Deschide o problemă (issue) dacă observi o nouă structură sau consideri că una existentă ar trebui actualizată. 35 | 36 | Dacă ai nevoie de ajutor cu denumirile, formatare, stilare vezi [`gofmt`](https://golang.org/cmd/gofmt/) și [`golint`](https://github.com/golang/lint). Ar fi bine să citești și aceste linii de ghidare în vederea stilării codului Go: 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Ghid de stilare pentru modulele Go](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | Vezi [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) pentru informații adiționale. 44 | 45 | Mai multe despre numirea și organizarea modulelor + recomandări: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | Un articol chinezeasc despre Package-Oriented-Design și arhitectură: 52 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Directoarele Go 55 | 56 | ### `/cmd` 57 | 58 | Aplicațiile principale ale acestui proiect. 59 | 60 | Numele directorului pentru fiecare aplicație ar trebui să coincidă cu numele executabilului pe care vrei să îl ai (e.g., `/cmd/myapp`). 61 | 62 | Nu pune mult cod în directorul aplicației. Dacă el ar trebui importat și folosit în alte proiecte, atunci ar trebui pus în `/pkg`. Dacă nu este reutilizabil sau vrei ca alții să îl reutilizeze, pune codul în `/internal`. Vei fi surprins ce vor face ceilalți, deci fii explicit în intențiile tale! 63 | 64 | Este comun să ai o funcție `main` care doar importă și invocă cod din `/internal` și `/pkg`. 65 | 66 | Vezi directorul [`/cmd`](cmd/README.md) pentru exemple. 67 | 68 | ### `/internal` 69 | 70 | Cod privat al modulelor/aplicației. Acesta este cod pe care nu vrei alții să îl importe în aplicațiile/modulele lor. Această structură este forțată de compilatorul Go. Vezi Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) pentru mai multe detalii. Nu ești însă limitat de un singur director top-level `internal`. Poți avea mai multe directoare `internal` la orice nivel în cadrul proiectului tău. 71 | 72 | Poți adăuga o structură adițională modulelor tale interne pentru a separa codul partajat de cel nepartajat. Nu este necesar, dar este bune să ai indicii vizuale pentru a arăta scopul de folosire al modulelor. Codul actual al aplicației poate fi în directorul `/internal/app` (e.g., `/internal/app/myapp`) iar codul partajat de acele aplicații în `/internal/pkg` (e.g., `/internal/pkg/myprivlib`). 73 | 74 | ### `/pkg` 75 | 76 | Cod librărie care poate fi folosit de aplicațiile externe (e.g., `/pkg/mypubliclib`). Alte proiecte vor importa aceste module și se vor aștepta ca ele să funcționeze, așa că gândește-te de 2 ori înainte de a pune ceva aici :) Directorul `internal` este o modalitate mai bună de a fi sigur că modulele tale no sunt importabile deoarece acest fapt este forțat de Go. Directorul `/pkg` este în continuare un mod bun de a comunica explicit codul ca fiind sigur de folosit de către ceilalți. Postarea [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) oferă o prezentare generală a directoarelor `pkg` și `internal`. 77 | 78 | Este o metodă bună să grupezi codul Go într-un singur loc atunci când directorul root al aplicației conține multe componente no-Go, (cum este menționat în aceste prezentări: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) and [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 79 | 80 | Vezi [`/pkg`](pkg/README.md) dacă vrei să vezi care repo-uri populare Go folosesc această structură de proiect. Aceasta este o structură comună de proiect însă nu este universală și nu o recomand în comunitatea Go. 81 | 82 | ### `/vendor` 83 | 84 | Dependințele aplicației (gestionate manual sau automat). Comanda `go mod vendor` va creea un director `/vendor`. Probabil va trebui să adaugi ca parametru `-mod=vendor` atunci când execuți `go build` dacă nu folosești Go 1.14 85 | 86 | Nu da commit la dependințele aplicației dacă construiești un modul. 87 | 88 | Odată cu versiunea [`1.13`](https://golang.org/doc/go1.13#modules) Go a implementat funcționalitatea modulelor proxy (folosind [`https://proxy.golang.org`](https://proxy.golang.org) ca server proxy al modulelor implicit). Poți citi mai multe despre el [`aici`](https://blog.golang.org/module-mirror-launch). S-ar putea să nu ai nevoie de directorul `/vendor` dacă poți folosi modulele proxy. 89 | 90 | ## Directoarele de servicii ale aplicației 91 | 92 | ### `/api` 93 | 94 | Specificații OpenAPI/Swagger, fișiere JSON schema, fișiere cu definiții de protocoale. 95 | 96 | Vezi directorul [`/api`](api/README.md) pentru exemple. 97 | 98 | ## Directorul aplicațiilor Web 99 | 100 | ### `/web` 101 | 102 | Componente specifice aplicațiilor Web: asset-uri, template-uri, SPAs, etc 103 | 104 | ## Directoare comune aplicațiilor 105 | 106 | ### `/configs` 107 | 108 | Șablonuri de configurare, configurări implicite. 109 | 110 | Poți pune `confd` sau `consul-template` aici. 111 | 112 | ### `/init` 113 | 114 | Configurări de inițializare system (systemd, upstart, sysv) și gestiune/supervizare a proceselor (runit, supervisord) 115 | 116 | ### `/scripts` 117 | 118 | Scripturi pentru rularea diferitelor operații. 119 | 120 | Ele țin nivelul rădăcinii Makefile mic și simplu (e.g., [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 121 | 122 | Vezi directorul [`/scripts`](scripts/README.md) pentru examples. 123 | 124 | ### `/build` 125 | 126 | Packaging și Integrare Continuă. 127 | 128 | Pune configurări ale modulelor AMI, Docker, OS (deb, rpm, pkg) și scripturi în directorul `/build/package` 129 | 130 | Pune configurările CI (travis, circle, drone) și scripturile similare în directorul `/build/ci`. Unele instrumente CI sunt pretențioase când vine vorba de locația configurărilor (e.g., Travis CI). Încearcă să pui fișierele de configurare în directorul `/build/ci` legându-le de locația în care uneltele CI se așteaptă să fie. 131 | 132 | ### `/deployments` 133 | 134 | Conține sisteme și containere de orchestrare, implementare, șablonare (docker-compose, kubernetes/helm, mesos, terraform, bosh) IaaS, PaaS. În unele repo-uri (în special cele implementate cu kubernetes) acest director e numit direct `/deploy`. 135 | 136 | ### `/test` 137 | 138 | Softuri și fișiere adiționale de testare. Poți structura directorul `/test` cum dorești. Pentru proiecte mari are sens să conțină sub-directoare. De exemplu, poți avea `/test/data` sau `/test/testdata` dacă vrei ca Go să ignore ce este in acel director. Go va ignora și directoarele sau fișierele care încep cu "." sau "\_", deci ai mai multă flexibilitate cu privire la modul în care îți numești fișierele/directoarele din `/test` 139 | 140 | Vezi [directorul](test/README.md) pentru example. 141 | 142 | ## Alte directoare 143 | 144 | ### `/docs` 145 | 146 | Documentația structurii aplicației 147 | 148 | Vezi [`/docs`](docs/README.md) pentru exemple. 149 | 150 | ### `/tools` 151 | 152 | Unelte de suport pentru acest proiect. Ele pot importa și module din directoarele `/pkg` și `/internal` 153 | 154 | Vezi [`/tools`](tools/README.md) pentru exemple. 155 | 156 | ### `/examples` 157 | 158 | Exemple pentru aplicația ta și/sau librării publice 159 | 160 | Vezi [`/examples`](examples/README.md) pentru exemple. 161 | 162 | ### `/third_party` 163 | 164 | Unelte externe de ajutor, cod forked și alte utilități (e.g., Swagger UI). 165 | 166 | ### `/githooks` 167 | 168 | Git hooks. 169 | 170 | ### `/assets` 171 | 172 | Alte aseturi conținute de repo (images, logos, etc). 173 | 174 | ### `/website` 175 | 176 | Acesta este locul în care îți pui datele website, dacă nu folosești pagini GitHub. 177 | 178 | Vezi [`/website`](website/README.md) pentru exemple. 179 | 180 | ## Directoare pe care NU ar trebui să le ai 181 | 182 | ### `/src` 183 | 184 | Unele proiecte Go au un director `src`, dar se întâmplă de obicei când developer-ii au venit din domeniul Java. Încearcă să nu adopți o astfel de structură, e indicat ca proiectul tău să nu se asemene cu unul tip Java. 185 | 186 | Nu confunda directorul `/src` cu cel pe care Go îl folosește ca spațiu de lucru (workspace). Variabila `$GOPATH` arată workspace-ul (implicit el e setat la `$HOME/go` pentru sistemele de operare non-Windows). Acest workspace folosește directoarele `/pkg`, `/bin` și `/src`. Proiectul tău actual ajunge să fie un sub-director sub `/src`, deci dacă ai un director `/src` în proiectul tău, calea va arăta cam așa: `/some/path/to/workspace/src/your_project/src/your_code.go`. Odată cu Go 1.11 este permis să ai proiectul în afara `GOPATH`, însă nu este neapărat o idee bună să adopți o astfel de schemă. 187 | 188 | ## Adiționale 189 | 190 | * [Go Report Card](https://goreportcard.com/) - Îți va scana codul cu `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` și `misspell`. Înlocuiește `github.com/golang-standards/project-layout` cu referința la proiuectul tău. 191 | 192 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 193 | 194 | * ~~[GoDoc](http://godoc.org) - Va furniza versiuni online ale documentației generate local de GoDoc.~~ 195 | 196 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 197 | 198 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev este o nouă destinație pentru descoperiri și documentație Go. Poți creea o insignă (badge) cu [badge generation tool](https://pkg.go.dev/badge). 199 | 200 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 201 | 202 | * Release - Va arăta ultimele lansări (versiuni) ale proiectului tău. 203 | 204 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 205 | 206 | ## Note 207 | 208 | Un șablon mai pedant cu configurări probate/reutilizabile, scripturi și cod este un WIP. 209 | -------------------------------------------------------------------------------- /README_ru.md: -------------------------------------------------------------------------------- 1 | # Стандартный макет Go проекта 2 | 3 | Переводы: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## Обзор 25 | 26 | Это базовый макет организации проектов, разработанных на Go. Это **не официально определенный командой разработчиков Go стандарт**, однако он удовлетворяет исторически сложившимся шаблонам организации проекта в экосистеме Go. Некоторые из шаблонов могут быть известнее остальных. В макете также присутствуют несколько улучшений, включая дополнительные директории, используемые в любом достаточно большом реальном приложении. 27 | 28 | Если вы пытаетесь изучить Go или собрать маленький обучающий проект для личного пользования, данный макет будет явным перебором. Стоит начать с чего-нибудь действительно простого (одного файла `main.go` будет достаточно). Как только ваш проект начнет расти, стоит задуматься о важности содержания кода в структурированном состоянии, чтобы в конечном итоге не получить грязный код с множеством скрытых зависимостей и global state. А когда над проектом начнут работать другие люди - понадобится еще большая структуризация. В этот момент важно определить стандартный путь организации пакетов/библиотек. Если вы разрабатываете проект с открытым исходным кодом или знаете, что вашим кодом будут пользоваться при разработке других проектов, необходимо понимать важность создания личных, внутренних (или `internal`) пакетов и кода. Клонируйте репозиторий, пользуйтесь тем, что действительно нужно, и удалите всё остальное! Наличие этого "всего остального" вовсе не означает, что это обязательно использовать. Заметьте, что ни один из этих шаблонов не обязан быть использован в абсолютно каждом проекте. Даже `vendor` не может быть универсален во всех случаях. 29 | 30 | С выходом обновления Go 1.14, [`Go Modules`](https://go.dev/wiki/Modules) стали наконец-то доступны для использования. Применяйте [`Go Modules`](https://blog.golang.org/using-go-modules) везде, пока не столкнётесь с веской причиной отказаться от них, и если такой момент всё же настанет - вам больше не придётся волноваться о значении переменной окружения $GOPATH и месте, где вы размещаете свой проект. Базовый `go.mod` файл в репозитории показывает, что ваш проект размещён на GitHub, однако он не является обязательным. Путь к модулю может быть любым, при условии, что первый компонент пути должен содержать точку в имени (текущая версия Go больше не требует этого, но если вы используете достаточно устаревшие версии - не стоит удивляться, что ваши сборки могу перестать работать). Ознакомьтесь с проблемами: [`37554`](https://github.com/golang/go/issues/37554) и [`32819`](https://github.com/golang/go/issues/32819) если хотите узнать об этом больше. 31 | 32 | Этот шаблон организации проекта намеренно сделан обобщенным, и не является примером структуры какого-то конкретного пакета Go. 33 | 34 | Этот проект открыт сообществу для улучшения. Создайте заявку о проблеме, если вы нашли новый шаблон или считаете, что один из существующих шаблонов необходимо обновить. 35 | 36 | Если вам нужна помощь в наименовании, форматировании или стилизации кода - начните с [`gofmt`](https://golang.org/cmd/gofmt/) и [`golint`](https://github.com/golang/lint). Также обязательно прочтите эти руководства по стилю для кода на Go и рекомендации: 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Руководство по стилизации кода для пакетов Golang](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | Обратите внимание на [`Шаблон проекта Golang`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) для получения дополнительной информации. 44 | 45 | Еще больше про наименование и организацию пакетов, а так же про структуру кода можно узнать здесь: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | Пост о руководствах по пакетно-ориентированному дизайну и архитектурным слоям 52 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Директории Go 55 | 56 | ### `/cmd` 57 | 58 | Основные приложения для текущего проекта. 59 | 60 | Имя директории для каждого приложения должно совпадать с именем исполняемого файла, который вы хотите собрать (например, `/cmd/myapp`). 61 | 62 | Не стоит располагать в этой директории большие объёмы кода. Если вы предполагаете дальнейшее использование кода в других проектах, вам стоит хранить его в директории `/pkg` в корне проекта. Если же код не должен быть переиспользован где-то еще - ему самое место в директории `/internal` в корне проекта. Вы будете удивлены тем, что могут сделать другие люди, по 63 | тому выражайте свои намерения явно! 64 | 65 | Самой распространённой практикой является использование маленькой `main` функции, которая импортирует и вызывает весь необходимый код из директорий `/internal` и `/pkg`, но не из других. 66 | 67 | Примеры смотрите в директории [`/cmd`](cmd/README.md). 68 | 69 | ### `/internal` 70 | 71 | Внутренний код приложения и библиотек. Это код, который не должен использоваться в других приложениях и библиотеках. Стоит отметить, что этот шаблон применяется самим компилятором Golang. Ознакомьтесь с [`release notes`](https://golang.org/doc/go1.4#internalpackages) Go 1.4 для более детальной информации. Также, вы вольны использовать более одной директории `internal` на разных уровнях структуры своего проекта. 72 | 73 | Вы можете добавить дополнительное структурирование, чтобы разделить открытую и закрытую части вашего внутреннего кода. Такой подход не является необходимым, особенно для маленьких проектов, но позволяет сразу визуально оценить применение кода. Код самого приложения может находиться в директории `/internal/app` (например, `/internal/app/myapp`), а код, который это приложение использует - в директории `/internal/pkg` (например, `/internal/pkg/myprivlib`). 74 | 75 | ### `/pkg` 76 | 77 | Код библиотек, пригодных для использования в сторонних приложениях (например, `/pkg/mypubliclib`). Другие проекты будут импортировать эти библиотеки, ожидая их автономной работы, поэтому стоит подумать дважды, прежде чем класть сюда какой-нибудь код. Обратите внимание, что использование директории `internal` - более оптимальный способ гарантировать что ваши внутренние пакеты, не будут импортированы, потому что это обеспечивает сам Go. Директория `/pkg` - всё еще хороший путь дать понять, что код в этой директории могут безопасно использовать другие. Статья [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) в блоге Трэвиса Джеффери (Travis Jeffery) предоставляет хороший обзор директорий `pkg` и `internal` и когда есть смысл их использовать. 78 | 79 | Это так же способ группировать код на Go в одном месте, когда ваша корневая директория содержит множество не относящихся к Go компонентов и директорий, что позволит облегчить работу с разными инструментами Go (как упомянуто в этих выступлениях: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) с GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) и [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 80 | 81 | Ознакомьтесь с директорией [`/pkg`](pkg/README.md), если хотите увидеть, какие популярные репозитории используют этот макет для организации проекта. Это часто используемый макет, но он не общепринятый, а некоторые в сообществе Go и вовсе не рекомендует его использовать. 82 | 83 | Вы можете не использовать эту директорию, если проект совсем небольшой и добавление нового уровня вложенности не несет практического смысла (разве что вы сами этого не хотите). Подумайте об этом, когда ваша корневая директория начинает слишком сильно разрастаться, особенно, если у вас много компонентов, написанных не на Go. 84 | 85 | ### `/vendor` 86 | 87 | Зависимости приложений, управляемые вручную или с использованием вашей любимой системы управления зависимостями, вроде доступного из коробки [`Go Modules`](https://go.dev/wiki/Modules). Команда `go mod vendor` создаст для вас директорию `/vendor`. Обратите внимание, что вам возможно придётся добавить флаг `-mod=vendor` к команде `go build`, если вы используете версию, отличную от Go 1.14, где такой флаг выставлен по-умолчанию. 88 | 89 | Не стоит отправлять зависимости вашего приложения в репозиторий, если собираетесь создавать библиотеку. 90 | 91 | Стоит отметить, что начиная с версии [`1.13`](https://golang.org/doc/go1.13#modules) Go добавил возможность проксирования модулей (с использованием [`https://proxy.golang.org`](https://proxy.golang.org) как прокси-сервера по-умолчанию). [`Здесь`](https://blog.golang.org/module-mirror-launch) можно побольше узнать про эту возможность, чтобы убедиться, что она удовлетворяет вашим требованиям и ограничениям. Если это так - использование директории `vendor` не требуется вовсе. 92 | 93 | ## Директории приложений-сервисов 94 | 95 | ### `/api` 96 | 97 | Спецификации OpenAPI/Swagger, JSON schema файлы, файлы определения протоколов. 98 | 99 | Примеры смотрите в директории [`/api`](api/README.md). 100 | 101 | ## Директории Веб-приложений 102 | 103 | ### `/web` 104 | 105 | Специальные компоненты для веб-приложений: статические веб-ресурсы, серверные шаблоны и одностраничные приложения. 106 | 107 | ## Распространенные директории 108 | 109 | ### `/configs` 110 | 111 | Шаблоны файлов конфигураций и файлы настроек по-умолчанию. 112 | 113 | Поместите файлы конфигураций `confd` или `consul-template` сюда. 114 | 115 | ### `/init` 116 | 117 | Файлы конфигураций для инициализации системы (systemd, upstart, sysv) и менеджеров процессов (runit, supervisord). 118 | 119 | ### `/scripts` 120 | 121 | Скрипты для выполнения различных операций сборки, установки, анализа и т.п. операций. 122 | 123 | Эти скрипты позволяют оставить основной Makefile небольшим и простым (например, [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 124 | 125 | Примеры смотрите в директории [`/scripts`](scripts/README.md). 126 | 127 | ### `/build` 128 | 129 | Сборка и непрерывная интеграция (Continuous Integration, CI). 130 | 131 | Поместите файлы конфигурации и скрипты облака (AMI), контейнера (Docker), пакетов (deb, rpm, pkg) в директорию `/build/package`. 132 | 133 | Поместите ваши файлы конфигурации CI (travis, circle, drone) и скрипты в директорию `/build/ci`. Обратите внимание, что некоторые инструменты CI (например, Travis CI) очень требовательны к расположению их конфигурационных файлов. Попробуйте поместить конфигурационные файлы в директорию `/build/ci` создав ссылку на них в месте, где их ожидают найти CI инструменты (если возможно). 134 | 135 | ### `/deployments` 136 | 137 | Шаблоны и файлы конфигураций разворачивания IaaS, PaaS, системной и контейнерной оркестрации (docker-compose, kubernetes/helm, mesos, terraform, bosh). Стоит заметить, что в некоторых репозиториях (особенно в приложениях, развернутых с использованием Kubernetes) эта директория называется `/deploy`. 138 | 139 | ### `/test` 140 | 141 | Дополнительные внешние тестовые приложения и данные для тестирования. Вы вольны организовывать структуру директории `/test` так, как вам угодно. Для больших проектов имеет смысл создавать вложенную директорию с данными для тестов. Например,`/test/data` или `/test/testdata`, если вы хотите, чтобы Go игнорировал находящиеся там файлы. Стоит заметить, что Go будет также игнорировать файлы, путь к которым начинается с "." или "_", что предоставляет вам гибкость в наименовании вашей директории с тестовыми данными. 142 | 143 | Примеры смотрите в директории [`/test`](test/README.md). 144 | 145 | ## Другие Директории 146 | 147 | ### `/docs` 148 | 149 | Проектная и пользовательская документация (в дополнение к документации сгенерированной godoc). 150 | 151 | Примеры смотрите в директории [`/docs`](docs/README.md). 152 | 153 | ### `/tools` 154 | 155 | Инструменты поддержки проекта. Обратите внимание, что эти инструменты могут импортировать код из директорий `/pkg` и `/internal`. 156 | 157 | Примеры смотрите в директории [`/tools`](tools/README.md). 158 | 159 | ### `/examples` 160 | 161 | Примеры ваших приложений и/или библиотек. 162 | 163 | Примеры смотрите в директории [`/examples`](examples/README.md). 164 | 165 | ### `/third_party` 166 | 167 | Внешние вспомогательные инструменты, ответвления кода и другие сторонние утилиты (например, Swagger UI). 168 | 169 | ### `/githooks` 170 | 171 | Git hooks. 172 | 173 | ### `/assets` 174 | 175 | Другие ресурсы, необходимые для использования вашего репозитория (изображения, логотипы и т.д.) 176 | 177 | ### `/website` 178 | 179 | Здесь можно разделить файлы для сайта вашего проекта, если вы не используете `GitHub pages`. 180 | 181 | Примеры смотрите в директории [`/website`](website/README.md). 182 | 183 | ## Директории, которые не стоит размещать у себя в проекте 184 | 185 | ### `/src` 186 | 187 | Некоторые проекты на Go имеют директорию `src`, но это обычно происходит, когда разработкой занялся человек, пришедший из мира Java, где такой подход весьма распространен. Постарайтесь не использовать этот Java паттерн. Вы же не хотите, чтобы ваш код на Go или Go проект выглядел, будто написан на Java. 188 | 189 | Не путайте директорию уровня проекта `/src` с директорией `/src`, которую Go использует для своих рабочих пространств, как это описано в [`How to Write Go Code`](https://golang.org/doc/code.html). Переменная окружения `$GOPATH` указывает на ваше (текущее) рабочее пространство (по-умолчанию она указывает на `$HOME/go` на системах под управлением ОС, отличной от Windows). Это рабочее пространство включает высокоуровневые директории `/pkg`, `/bin` и `/src`. Ваш проект в свою очередь находится в директории вложенной в директорию `/src`, поэтому если у вас есть директория `/src` внутри вашего проекта, путь к проекту будет выглядеть примерно так: `/some/path/to/workspace/src/your_project/src/your_code.go`. Стоит заметить, что в версиях Go начиная с 1.11 ваш проект может хранить за пределами вашего `GOPATH`, но это всё еще не значит, что применять этот шаблон компоновки - это хорошая идея. 190 | 191 | 192 | ## Badges 193 | 194 | * [Go Report Card](https://goreportcard.com/) - Просканирует ваш код с помощью `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` и `misspell`. Замените `github.com/golang-standards/project-layout` на ссылку на ваш проект. 195 | 196 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 197 | 198 | * ~~[GoDoc](http://godoc.org) - Предоставит онлайн версию вашей сгенерированной GoDoc документации. Измените ссылку, чтобы она указывала на ваш проект.~~ 199 | 200 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 201 | 202 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev это новое место для исследования Go и документации. Вы можете создать бейдж с помощью [badge generation tool](https://pkg.go.dev/badge). 203 | 204 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 205 | 206 | * Release - Покажет версию последнего релиза вашего проекта. Измените ссылку на github, чтобы она указывала на ваш проект. 207 | 208 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 209 | 210 | ## Примечания 211 | 212 | Более продуманный шаблон проекта с образцами/повторно используемыми конфигурациями, скриптами и кодом — это WIP. 213 | -------------------------------------------------------------------------------- /README_tr.md: -------------------------------------------------------------------------------- 1 | # Standart Go Projesi Düzeni 2 | 3 | Çeviriler: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | ## Genel Bakış: 25 | 26 | Bu proje Go projeleri için basit bir yerleşim düzenidir. `Go geliştirici takımının belirlediği, resmi standartları değil`. Go ekosistemindeki, ortak geçmişi ve zaman içinde ortaya çıkmış şablonları içerir. Bu şablonlardan bazıları diğerlerinden daha popülerdir. Bir dizi iyileştirmenin yanı sıra yeterli büyüklükte herhangi bir gerçek dünya uygulamasına özgü birkaç destekli dizin de içerir. 27 | 28 | **`Eğer Go'yu öğrenmeye çalışıyorsanız veya PoC (Proof of Concept) ya da kendinize deneme bir proje yapıyorsanız bu klasör düzeni sizin için ideal olmaya bilir. Çok basit bir şeyle başlayın (tek bir` main.go `dosyası ve` go.mod `fazlasıyla yeterli olucaktır).`** Projeniz büyüdükçe projenin iyi yapılandırıldığından emin olmanın önemli olduğunu unutmayın, yoksa bir sürü gizli bağımlılık (dependency) ve bir sürü, her yerden erişilebilen, `global` değişkenlerle dolu dağınık bir kodla karşılaşabilirsiniz. Proje üstünde fazla kişi çalıştığında projeyi çok daha fazla yapılandırmanız gerekebilir. İşte tam da bu durumda paketleri/kütüphaneleri idare edebilmek için ortaya ortak bir yol koymak gerekir. Açık kaynak bir projeniz olduğunda ya da başkalarının sizin projenizi kullandıklarını bildiğinizde projenizde özel paketlerin ve kodların (diğer adıyla, `internal` klasörü) olması önemlidir. Bu projeyi klonlayın, ihtiyacınız olanları bırakın ve diğer bütün her şeyi silin. Bütün klasörlerin burada olması kullanmanız gerektiği anlamına gelmez. `vendor` klasörü bile herkes tarafından kullanılan bir şey değildir. 29 | 30 | Go 1.14 ile birlikte [`Go Modules`](https://go.dev/wiki/Modules) özelliği sonunda `production` ortamında kullanılması için hazır oldu. Eğer karşı bir nedeniniz yoksa [`Go Modules`](https://blog.golang.org/using-go-modules) kullanın. Eğer kullanırsanız `$GOPATH` ile ve projenizin nereye koyulacağıyla alakalı endişeler duymazsınız. Projenizde bulunan basit `go.mod` dosyası projenizin GitHub'da barındırıldığını varsayar ama bu bir gereklilik değildir. Modül yolu her şey olabilir ama modül yolunun ilk parçasının içinde bir nokta olmalıdır (Go'nun şimdiki versiyonu artık bu konuda zorlamıyor ama eğer daha eski versiyonları kullanırsanız ve derleme işleminde hata alırsanız şaşırmayın). Daha fazla bilgi için [`37554`](https://github.com/golang/go/issues/37554) ve [`32819`](https://github.com/golang/go/issues/32819) hata bildirimlerine bakabilirsiniz. 31 | 32 | "Bu proje düzeni genel bir düzendir ve belirli bir Go paketi yapısını empoze etmeye çalışmaz". 33 | 34 | Bu proje bir topluluk eseridir. Eğer yeni bir şablon ve ya düzen ile karşılaşırsanız ya da olan şablonların, düzenlerin güncellenmesi gerektiğini düşünüyorsanız bir hata bildirimi açınız. 35 | 36 | Eğer isimlendirmekle, biçimlendirmeyle ve stilize etmeyle ilgili yardıma ihtiyacınız varsa [`gofmt`](https://golang.org/cmd/gofmt/) ve [`golint`](https://github.com/golang/lint) yazılımlarını çalıştırmayı deneyin. Ayrıca aşağıdaki Go kod stili rehberlerini ve önerilerini okuduğunuzdan emin olun. 37 | * https://talks.golang.org/2014/names.slide 38 | * https://golang.org/doc/effective_go.html#names 39 | * https://blog.golang.org/package-names 40 | * https://go.dev/wiki/CodeReviewComments 41 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 42 | 43 | Ek bilgi için [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) adlı yazıya bakabilirsin. 44 | 45 | Paketlerin adlandırılması ve düzenlenmesi ile diğer kod yapısı önerileri hakkında daha fazla bilgi: 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | Paket odaklı dizayn rehberi ve Mimari katmanı ile alakalı Çince bir yazı: 52 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Go Klasörleri 55 | 56 | ### `/cmd` 57 | 58 | Projenin ana uygulamalarını içerir. 59 | 60 | Her uygulamanın klasör adı, eklemek istediğiniz uygulamanın adıyla eşleşmelidir. (örneğin, `/cmd/myapp`) 61 | 62 | Bu klasöre çok fazla kod koymanız iyi olmaz. Eğer kodların başka projeler tarafından kullanılabileceğini düşünüyorsanız, o kodları `/pkg` klasörüne koymalısınız. Eğer kod yeniden kullanılabilecek değilse ya da diğerlerinin yeniden kullanmasını istemiyorsanız, bu kodları `/internal` klasörüne koymalısınız. Niyetiniz hakkında açık olun, diğer geliştiricilerin kodunuzu ne için kullanabileceğine şaşıracaksınız! 63 | 64 | `/internal` ve `/pkg` klasörlerinden kod çağıran küçük bir `main` fonksiyonunuzun olması yaygındır. 65 | 66 | Örnekler için [`/cmd`](cmd/README.md) klasörüne bakabilirsiniz. 67 | 68 | ### `/internal` 69 | 70 | Özel uygulama ve kütüphane kodunu içerir. Buradaki kodlar diğer geliştiricilerin kendi projelerinde kullanmasını istemediğiniz kodlardır. Bu yerleşim düzeninin Go derleyicisinin kendisi tarafından uygulandığına dikkat edin. Ayrıntılar için Go 1.4 [`sürüm notları`](https://golang.org/doc/go1.4#internalpackages). Üst katmandaki `internal` klasörü ile sınırlı olmadığınızı unutmayın, projenizin herhangi bir katmanında birden fazla `internal` klasörüne sahip olabilirsiniz. 71 | 72 | Paylaşılan ve paylaşılmayan kodunuzu ayırmak için isteğe bağlı olarak ekstra yapılar ekleyebilirsiniz. Bu gerekli değildir (özellikle küçük projeler için) ancak amaçlanan paket kullanımını gösteren görsel ipuçlarına sahip olmak güzel bir şeydir. Asıl uygulama kodunuz `/internal/app` klasöründe yer alabilir (örneğin, `/internal/app/benimuygulamam`) ve bu kodlar `/internal/pkg` klasöründe yer alan kodlar (örneğin, `/internal/pkg/benimözelkütüphanem`) ile paylaşılabilir. 73 | 74 | ### `/pkg` 75 | 76 | Diğerleriyle paylaşmak istediğiniz kodu içerir (örneğin, `/pkg/myopenlibrary`). Diğer projeler bu kütüphaneleri çalışacağını tahmin ederek kullanırlar. Yani buraya bir şey koyarken iki kere düşünün :-) Unutmayın ki `internal` klasörü başka projeler tarafından kullanılmasını istemediğiniz kodlar için daha iyi bir yerdir çünkü bu Go tarafından zorunlu olarak uygulanır. `/pkg` klasörü içindeki kodun başkaları tarafından kullanılmasının güvenli olduğunu açıkça belirtmek için hala iyi bir yoldur. Travis Jeffery tarafından yazılan [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) blog yazısı `pkg` ve `internal` klasörleri ve onları ne zaman kullanmanın mantıklı olacağına dair genel bakış sağlar. 77 | 78 | Ayrıca ana klasörünüz çok sayıda Go kodu olmayan dosya ve klasör içerdiğinde Go kodunu tek bir yerde gruplamanın yoludur ve bazı Go araçlarını kullanmayı daha kolay hale getirir (bu konuşmalarda bahsedildiği gibi: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) GopherCon Avrupa 2018 konferansından, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) ve [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 79 | 80 | Hangi popüler Go projelerinin bu düzeni kullandığını merak ediyorsanız [`/pkg`](pkg/README.md) klasörüne bakabilirsiniz. Bu genel bir yerleşim düzenidir ama herkes tarafından kabul edilmeyebilir ve bazı Go toplulukları bu yerleşim düzenini tavsiye etmeyebilir. 81 | 82 | Eğer projenizde ekstra bir katmana gerek yoksa ya da projeniz çok küçükse burayı kullanmamanızda bir sakınca olmaz (çok istiyorsanız kullanın). Projeniz yeterince büyük olduğunda ve ana klasörünüz karışmaya başladığında (özellikle çok fazla Go kodu olmayan dosyanız olduğunda) bunu kullanmayı düşünebilirsiniz. 83 | 84 | ### `/vendor` 85 | 86 | Uygulama bağımlılıkları (el ile yönetilen ya da yeni bir özellik olan [`Go Modules`](https://go.dev/wiki/Modules) gibi favori bağımlılık yönetim aracınızla yönetilen). `go mod vendor` komutu size yeni bir `/vendor` klasörü yaratır. Unutmayın eğer Go 1.14 kullanmıyorsanız `go build` komutuna `-mod=vendor` parametresi vermeniz gerekebilir Go 1.14 bunu varsayılan olarak yapar. 87 | 88 | Eğer bir kütüphane yazıyorsanız bağımlılıklarınızı `commit` etmeyin. 89 | 90 | Not olarak [`1.13`](https://golang.org/doc/go1.13#modules) versiyonundan itibaren Go modüller için `proxy` özelliğini aktif hale getirdi (varsayılan olarak [`https://proxy.golang.org`](https://proxy.golang.org) adresini kullanır). [`Buradan`](https://blog.golang.org/module-mirror-launch) gereksinimlerinize ve kısıtlamalarınıza uyup uymadığı hakkında daha fazla bilgi edinebilirsiniz. Eğer bu size uyarsa `vendor` klasörüne çokta ihtiyacınız olmayacaktır. 91 | 92 | ## Servis Uygulaması Klasörleri 93 | 94 | ### `/api` 95 | 96 | OpenAPI/Swagger dosyaları, JSON şema dosyaları, protokol tanımlama dosyaları. 97 | 98 | Örnekler için [`/api`](api/README.md) klasörüne bakabilirsiniz. 99 | 100 | ## Web Uygulaması Klasörleri 101 | 102 | ### `/web` 103 | 104 | Spesifik web uygulaması parçaları: statik web varlıkları, sunucu taraflı şablonlar ve SPA'lar. 105 | 106 | ## Genel Uygulama Klasörleri 107 | 108 | ### `/configs` 109 | 110 | Konfigürasyon dosya şablonları veya varsayılan konfigürasyonlar. 111 | 112 | `confd` veya `consul-template` dosyalarını buraya koyabilirsiniz. 113 | 114 | ### `/init` 115 | 116 | Sistem başlangıcı (systemd, upstart, sysv) ve işlem yöneticisi (runit, supervisord) konfigürasyonları. 117 | 118 | ### `/scripts` 119 | 120 | Çeşitli derleme, yükleme, analiz ve benzeri işlemleri gerçekleştirmek için olan komut dosyaları. 121 | 122 | Bu dosyalar ana katmandaki Makefile dosyasını küçük ve basit tutar. (örneğin, [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile)). 123 | 124 | Örnekler için [`/scripts`](scripts/README.md) klasörüne bakabilirsiniz. 125 | 126 | ### `/build` 127 | 128 | Paketleme ve Sürekli Entegrasyon. 129 | 130 | `/build/package` klasörüne bulut (AMI), konteyner (Docker), işletim sistemi (deb, rpm, pkg) paket konfigürasyonlarını ve komut dosyalarını koyabilirsiniz. 131 | 132 | `/build/ci` klasörüne de Sürekli Entegrasyon (travis, circle, drone) konfigürasyonlarını ve komut dosyalarını koyabilirsiniz. Önemli olarak bazı sürekli entegrasyon araçları (örneğin, Travis CI) konfigürasyon dosyalarının klasörleriyle alakalı seçici olabiliyor. Konfigürasyon dosyalarını `/build/ci` klasörüne koymayı deneyin ve dosyaları sürekli entegrasyon araçlarının bekledikleri yere bağlayın (mümkün olduğunda). 133 | 134 | ### `/deployments` 135 | 136 | IaaS, Paas, sistem ve konteyner orkestrasyon yayınlama konfigürasyonlarını ve şablonlarını (docker-compose, kubernetes/helm, mesos, terraform, bosh) bu klasöre koyabilirsiniz. Önemli olarak bazı projelerde (özellikle kubernetes ile yayınlanan projeler) bu klasörün adı `/deploy` olabilir. 137 | 138 | ### `/test` 139 | 140 | Ek harici test uygulamaları ve test verileri. `/test` klasörünün içini istediğiniz gibi yapılandırmada özgür hissedin. Daha büyük projelerde test verileri için alt klasörler açmak mantıklı olabilir. Örneğin, eğer Go'nun test dosyalarını görmezden gelmesini istiyorsanız bu dosyalar için `/test/data` veya `/test/testdata` adlı klasörlere sahip olabilirsiniz. Not olarak Go "." veya "_" ile başlayan klasörleri ve dosyalarıda görmezden gelir, bu sayede test klasörlerinizi ve dosyalarınızı isimlendirmede daha esnek olabilirsiniz. 141 | 142 | Örnekler için [`/test`](test/README.md) klasörüne bakabilirsiniz. 143 | 144 | ## Diğer Klasörler 145 | 146 | ### `/docs` 147 | 148 | Tasarım ve kullanıcı dökümanları (godoc ile oluşturulmuş dökümanlara ek olarak) 149 | 150 | Örnekler için [`/docs`](docs/README.md) klasörüne bakabilirsiniz. 151 | 152 | ### `/tools` 153 | 154 | Bu klasöre projen için destekleyici araçları koyabilirsiniz. Unutmayın bu araçlar `/pkg` ve `/internal` klasörlerindeki kodları kullanabilirler. 155 | 156 | Örnekler için [`/tools`](tools/README.md) klasörüne bakabilirsiniz. 157 | 158 | ### `/examples` 159 | 160 | Bu klasöre yaptığınız uygulamalar ya da kütüphaneler için örnekleri koyabilirsiniz. 161 | 162 | Örnekler için [`/examples`](examples/README.md) klasörüne bakabilirsiniz. 163 | 164 | ### `/third_party` 165 | 166 | Dış yardımcı araçlar, çatallanmış kod (forked code) ve diğer 3. parti yardımcı şeyler. (örneğin, Swagger UI) 167 | 168 | ### `/githooks` 169 | 170 | Git hooks. 171 | 172 | ### `/assets` 173 | 174 | Bu klasöre resim, logo ve benzeri kaynakları koyabilirsiniz. 175 | 176 | ### `/website` 177 | 178 | Eğer GitHub Pages kullanmıyorsanız burası projenin websitesinin dosyalarının konulması için doğru adres. 179 | 180 | Örnekler için [`/website`](website/README.md) klasörüne bakabilirsiniz. 181 | 182 | ## Sahip olmamanız gereken klasörler 183 | 184 | ### `/src` 185 | 186 | Bazı Go projelerinde `src` adlı bir klasör görebilirsiniz, ama bu çoğunlukla `src` klasörü kullanmanın genel bir kalıp olduğu Java dünyasından gelen geliştiricilerde olur. Eğer yapabilirseniz bu Java kalıbını benimsememeye çalışın. Gerçekten Go kodunuzun ya da Go projenizin Java gibi gözükmesini istemezsiniz :-) 187 | 188 | Proje seviyesindeki `/src` klasörü ile [`How to Write Go Code`](https://golang.org/doc/code.html) adresinde belirtilen Go'nun çalışma alanları için kullandığı `/src` klasörünü karıştırmayın. `$GOPATH` ortam değişkeni sizin çalışma alanınıza (şu anki) işaret eder (Windows olmayan sistemlerde varsayılan olarak `$HOME/go` klasörüne işaret eder). Bu çalışma alanı içerisinde en üst katmandaki `/pkg`, `/bin` ve `/src` klasörlerini barındırır. Asıl projeniz `/src` klasörü altında bir alt dizin olur. Eğer projende `/src` klasörüne sahipseniz, projenizin dosya yolu büyük ihtimal şöyle gözükecek `/calismaalaniniz/src/projeniz/src/kodunuz.go`. Not olarak Go 1.11 ile `$GOPATH` klasörü dışında projeler açabilirsiniz ama bunu yapabilmeniz bu yerleşim düzeninin kullanılmasının iyi bir fikir olduğu anlamına gelmez. 189 | 190 | ## Rozetler 191 | 192 | * [Go Report Card](https://goreportcard.com/) - Kodunuzu `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` ve `misspell` yazılımları ile tarar. `github.com/golang-standards/project-layout` linkini kendi proje linkiniz ile değiştirin. 193 | 194 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 195 | 196 | * ~~[GoDoc](http://godoc.org) - Projenizin GoDoc tarafından yaratılmış online bir dökümantasyonunu çıkartır. İşaret ettiği linki kendi proje linkiniz ile değiştirin.~~ 197 | 198 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 199 | 200 | * [Pkg.go.dev](https://pkg.go.dev) - Paket keşfi ve dökümantasyonları için yeni adres Pkg.go.dev. [Rozet yaratma aracı](https://pkg.go.dev/badge) ile projenize bir rozet yaratabilirsiniz. 201 | 202 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 203 | 204 | * Release - Projenizin en son yayınlanmış versiyonunu gösterir. İşaret ettiği linki kendi proje linkiniz ile değiştirin. 205 | 206 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 207 | 208 | ## Notlar 209 | 210 | Örnek / yeniden kullanılabilir yapılandırmalar, komut dosyaları ve kodları içeren daha kararlı bir proje şablonu yapım aşamasındadır. 211 | -------------------------------------------------------------------------------- /README_ua.md: -------------------------------------------------------------------------------- 1 | # Стандартний макет проєкту Go 2 | 3 | Translations: 4 | 5 | * [한국어 문서](README_ko.md) 6 | * [简体中文](README_zh.md) 7 | * [正體中文](README_zh-TW.md) 8 | * [简体中文](README_zh-CN.md) - ??? 9 | * [Français](README_fr.md) 10 | * [日本語](README_ja.md) 11 | * [Portuguese](README_ptBR.md) 12 | * [Español](README_es.md) 13 | * [Română](README_ro.md) 14 | * [Русский](README_ru.md) 15 | * [Türkçe](README_tr.md) 16 | * [Українська](README_ua.md) 17 | * [Indonesian](README_id.md) 18 | * [हिन्दी](README_hi.md) 19 | * [Беларуская](README_be.md) 20 | 21 | ## Огляд 22 | 23 | Це базовий макет для проєктів Go-додатків. Це **`не є офіційним стандартом, визначеним командою розробників Go`**; тим не менш, це звід паттернів програмування в екосистемі Go, що склалися історично. Деякі з цих паттернів більш популярні та відомі ніж інші. Також в цьому макеті є декілька покращень, в тому числі декілька додаткових дерикторій, що використовуються в будь-якому достатньо великому реальному застосунку. 24 | 25 | **`Якщо ви тільки вивчаєте Go або створюєте якийсь демонстраційний чи простий проєкт для себе цей макет буде занадто складним. Почність з чогось дійсно простого (одного файлу `main.go` та `go.mod` буде достатньо).`** Коли проєкт почне рости не забувайте, важливо щоб код залишався добре структурованим, інакше ви отримаєте брудний код з великою кількістю прихованих залежностей та глобальних станів. Якщо над проєктом працює більше людей, необхідно ще більше структури. Саме тоді важливо запровадити єдиний спосіб управління пакетами/бібліотеками. Коли ви маєте проєкт з відкритим вихідним кодом або коли ви знаєте, що інші проєкти імпортують код з вашого репозиторію проєкту, саме тоді важливо мати приватні (`internal`) пакети та код. Клонуйте сховище, зберігайте те, що вам потрібно, а все інше видаляйте! Те, що це є, не означає, що ви повинні використовувати все це. Жодна з цих моделей не використовується в кожному окремому проєкті. Навіть паттерн `vendor` не є універсальним. 26 | 27 | Починаючи з Go 1.14 [`Go модулі`](https://go.dev/wiki/Modules) нарешті готові до використання. Використовуйте [`Go модулі`](https://blog.golang.org/using-go-modules) якщо у вас немає конкретної причини не використовувати їх, а якщо є, то вам не потрібно турбуватися про $GOPATH і про те, куди ви помістили свій проєкт. Базовий файл `go.mod` в репозиторії передбачає, що ваш проєкт розміщено на GitHub, однак це не є обов'язковою вимогою. Шлях до модуля може бути будь-яким, але перший компонент шляху до модуля повинен містити крапку в назві (поточна версія Go більше не вимагає цього, але якщо ви використовуєте трохи старіші версії, не дивуйтеся, якщо ваші збірки не працюватимуть без цього). Якщо ви хочете дізнатися більше про це, дивіться: [`37554`](https://github.com/golang/go/issues/37554) та [`32819`](https://github.com/golang/go/issues/32819). 28 | 29 | Ця схема проєкту є навмисно загальною і не намагається нав'язати конкретну структуру пакета Go. 30 | 31 | Це зусилля спільноти. Відкрийте тему, якщо ви бачите новий шаблон або якщо ви вважаєте, що один з існуючих шаблонів потребує оновлення. 32 | 33 | Якщо вам потрібна допомога з іменуванням, форматуванням та стилем, почніть з запуску [`gofmt`](https://golang.org/cmd/gofmt/) та [`golint`](https://github.com/golang/lint). Також обов'язково ознайомтеся з цими керівними принципами та рекомендаціями щодо стилю коду Go: 34 | * https://talks.golang.org/2014/names.slide 35 | * https://golang.org/doc/effective_go.html#names 36 | * https://blog.golang.org/package-names 37 | * https://go.dev/wiki/CodeReviewComments 38 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 39 | 40 | Дивіться [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) для додаткової довідкової інформації. 41 | 42 | Більше про іменування та організацію пакетів, а також інші рекомендації щодо структури коду: 43 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 44 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 45 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 46 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 47 | 48 | Китайська публікація про керівні принципи пакетно-орієнтованого проєктування та рівень архітектури 49 | * [面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 50 | 51 | ## Go каталоги 52 | 53 | ### `/cmd` 54 | 55 | Головні застосунки цього проєкту 56 | 57 | Ім'я каталогу для кожного додатка повинно збігатися з ім'ям виконуваного файлу, який ви хочете мати (наприклад `/cmd/myapp`). 58 | 59 | Не розміщуйте багато коду в каталозі програми. Якщо ви вважаєте, що код може бути імпортований і використаний в інших проєктах, то він повинен знаходитися в каталозі `/pkg`. Якщо код не може бути використаний повторно або якщо ви не хочете, щоб інші використовували його повторно, помістіть цей код в каталог `/internal`. Ви будете здивовані тим, що будуть робити інші, тому будьте відверті у своїх намірах! 60 | 61 | Зазвичай є невелика функція `main`, яка імпортує та викликає код з каталогів `/internal` та `/pkg` і нічого більше. 62 | 63 | Дивіться [`/cmd`](cmd/README.md) для прикладів. 64 | 65 | ### `/internal` 66 | 67 | Приватний код додатків та бібліотек. Це код, який ви не хочете, щоб інші імпортували у свої програми або бібліотеки. Зауважте, що цей шаблон компонування забезпечується самим компілятором Go. Дивіться Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) для додаткових деталей. Зверніть увагу, що ви не обмежені директорією `internal` верхнього рівня. Ви можете мати більше одного каталогу `internal` на будь-якому рівні дерева вашого проєкту. 68 | 69 | За бажанням ви можете додати трохи додаткової структури до ваших внутрішніх пакунків, щоб відокремити ваш спільний і не спільний внутрішній код. Це не є обов'язковим (особливо для невеликих проєктів), але приємно мати візуальні підказки, що показують передбачуване використання пакунків. Ваш власне код програми може знаходитися у каталозі `/internal/app` (наприклад, `/internal/app/myapp`), а код, який використовується спільно з іншими програмами, у каталозі `/internal/pkg` (наприклад, `/internal/pkg/myprivlib`). 70 | 71 | ### `/pkg` 72 | 73 | Код бібліотеки, який можна використовувати зовнішніми програмами (наприклад, `/pkg/mypubliclib`). Інші проєкти імпортуватимуть ці бібліотеки, очікуючи, що вони будуть працювати, тому подумайте двічі, перш ніж щось сюди класти :-) Зауважте, що каталог `internal` є кращим способом гарантувати, що ваші приватні пакунки не будуть імпортовані, оскільки це забезпечується Go. Каталог `/pkg` все ще є гарним способом явно повідомити, що код у цьому каталозі є безпечним для використання іншими. Допис у блозі [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) Тревіса Джеффрі (Travis Jeffery) надає гарний огляд каталогів `pkg` та `internal` і того, коли може мати сенс їх використання. 74 | 75 | Це також спосіб згрупувати код Go в одному місці, коли ваш кореневий каталог містить багато не-Go компонентів і каталогів, що полегшує запуск різних інструментів Go (як згадувалося в цих доповідях: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) з GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) та [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 76 | 77 | Якщо ви хочете побачити, які популярні репозиторії Go використовують цей шаблон оформлення проєктів, зверніться до каталогу [`/pkg`](pkg/README.md). Це загальноприйнятий шаблон, але він не є загальноприйнятим, і дехто у спільноті Go не рекомендує його використовувати. 78 | 79 | Можна не використовувати його, якщо ваш проєкт програми дійсно невеликий і де додатковий рівень вкладеності не додає особливої цінності (якщо тільки ви дійсно цього не хочете :-)). Подумайте про це, коли він стане досить великим і ваш кореневий каталог буде досить зайнятий (особливо якщо у вас багато компонентів програми, які не є Go). 80 | 81 | Походження каталогу `pkg`: старий вихідний код Go використовував `pkg` для своїх пакунків, а потім різні проєкти Go у спільноті почали копіювати цей шаблон (див. [`це`](https://twitter.com/bradfitz/status/1039512487538970624) твіт Бреда Фіцпатріка для більш детального контексту). 82 | 83 | ### `/vendor` 84 | 85 | Залежності додатків (управляються вручну або за допомогою вашого улюбленого інструменту управління залежностями, наприклад, нової вбудованої функції [`Go модулі`](https://go.dev/wiki/Modules)). Команда `go mod vendor` створить для вас каталог `/vendor`. Зауважте, що вам може знадобитися додати прапорець `-mod=vendor` до команди `go build`, якщо ви не використовуєте Go 1.14, де він увімкнений за замовчуванням. 86 | 87 | Не фіксуйте залежності програми, якщо ви створюєте бібліотеку. 88 | 89 | Зверніть увагу, що починаючи з [`1.13`](https://golang.org/doc/go1.13#modules) Go також включив функцію модульного проксі (використовуючи [`https://proxy.golang.org`](https://proxy.golang.org) в якості свого модульного проксі-сервера за замовчуванням). Прочитайте більше про нього [`тут`](https://blog.golang.org/module-mirror-launch), щоб дізнатися, чи відповідає він усім вашим вимогам і обмеженням. Якщо так, то каталог `vendor` вам взагалі не знадобиться. 90 | 91 | ## Каталоги сервісних додатків 92 | 93 | ### `/api` 94 | 95 | Специфікації OpenAPI/Swagger, файли схем JSON, файли визначення протоколів. 96 | 97 | Приклади дивіться у каталозі [`/api`](api/README.md). 98 | 99 | ## Каталоги веб-додатків 100 | 101 | ### `/web` 102 | 103 | Специфічні компоненти веб-додатків: статичні веб-активи, шаблони на стороні сервера та односторінкові застосунки. 104 | 105 | ## Загальні директорії додатків 106 | 107 | ### `/configs` 108 | 109 | Шаблони файлів конфігурації або конфігурації за замовчуванням. 110 | 111 | Сюди викладіть файли шаблонів `confd` або `consul-template`. 112 | 113 | ### `/init` 114 | 115 | Конфігурації системного запуску (systemd, upstart, sysv) та диспетчера/супервізора процесів (runit, supervisord). 116 | 117 | ### `/scripts` 118 | 119 | Скрипти для виконання різних операцій по збірці, установці, аналізу і т.д. 120 | 121 | Ці скрипти роблять Makefile кореневого рівня невеликим і простим (наприклад, [`https://github.com/hashicorp/terraform/blob/master/Makefile`](https://github.com/hashicorp/terraform/blob/master/Makefile)). 122 | 123 | Приклади див. у каталозі [`/scripts`](scripts/README.md). 124 | 125 | ### `/build` 126 | 127 | Упаковка та безперервна інтеграція (CI). 128 | 129 | Конфігурації хмарних (AMI), контейнерних (Docker), ОС (deb, rpm, pkg) пакетів та скрипти покладіть в каталог `/build/package`. 130 | 131 | Помістіть конфігурації та скрипти CI (travis, circle, drone) в каталог `/build/ci`. Зверніть увагу, що деякі інструменти CI (наприклад, Travis CI) дуже прискіпливі до розташування своїх конфігураційних файлів. Спробуйте помістити конфігураційні файли в каталог `/build/ci`, пов'язавши їх з тим місцем, де їх очікують інструменти CI (коли це можливо). 132 | 133 | ### `/deployments` 134 | 135 | Конфігурації та шаблони розгортання IaaS, PaaS, системної та контейнерної оркестрації (docker-compose, kubernetes/helm, mesos, terraform, bosh). Зверніть увагу, що в деяких репозиторіях (особливо для додатків, що розгортаються за допомогою kubernetes) цей каталог називається `/deploy`. 136 | 137 | ### `/test` 138 | 139 | Додаткові зовнішні тестові програми та тестові дані. Не соромтеся структурувати каталог `/test` як завгодно. Для великих проєктів має сенс мати підкаталог даних. Наприклад, ви можете мати `/test/data` або `/test/testdata`, якщо вам потрібно, щоб команда Go ігнорувала те, що знаходиться в цьому каталозі. Зауважте, що Go також ігноруватиме каталоги або файли, які починаються з "." або "_", тому у вас є більше гнучкості в плані того, як ви можете назвати свій каталог тестових даних. 140 | 141 | Приклади дивіться у каталозі [`/test`](test/README.md). 142 | 143 | ## Інші директорії 144 | 145 | ### `/docs` 146 | 147 | Проєктна та користувацька документація (на додаток до вашої документації, згенерованої в godoc). 148 | 149 | Приклади дивіться у каталозі [`/docs`](docs/README.md). 150 | 151 | ### `/tools` 152 | 153 | Допоміжні інструменти для цього проєкту. Зверніть увагу, що ці інструменти можуть імпортувати код з каталогів `/pkg` та `/internal`. 154 | 155 | Приклади дивіться у каталозі [`/tools`](tools/README.md). 156 | 157 | ### `/examples` 158 | 159 | Приклади для ваших додатків та/або публічних бібліотек. 160 | 161 | Приклади дивіться у каталозі [`/examples`](examples/README.md). 162 | 163 | ### `/third_party` 164 | 165 | Зовнішні допоміжні інструменти, форкований код та інші утиліти сторонніх розробників (наприклад, Swagger UI). 166 | 167 | ### `/githooks` 168 | 169 | Скріпти (хуки) Git. 170 | 171 | ### `/assets` 172 | 173 | Інші ресурси, які будуть супроводжувати ваш репозиторій (зображення, логотипи тощо). 174 | 175 | ### `/website` 176 | 177 | Це місце для розміщення даних сайту вашого проєкту, якщо ви не використовуєте GitHub Pages. 178 | 179 | Приклади дивіться у каталозі [`/website`](website/README.md). 180 | 181 | ## Директорії, яких у вас не має бути 182 | 183 | ### `/src` 184 | 185 | Деякі проєкти Go мають папку `src`, але це зазвичай трапляється, коли розробники прийшли зі світу Java, де це є поширеним шаблоном. Намагайтеся не використовувати цей патерн Java. Ви ж не хочете, щоб ваш Go код або Go проєкти виглядали як Java :-) 186 | 187 | Не плутайте каталог `/src` на рівні проєкту з каталогом `/src`, який Go використовує для своїх робочих областей, як описано в [`How to Write Go Code`](https://golang.org/doc/code.html). Змінна оточення `$GOPATH` вказує на вашу (поточну) робочу область (за замовчуванням вона вказує на `$HOME/go` на системах, відмінних від Windows). Ця робоча область включає в себе каталоги верхнього рівня `/pkg`, `/bin` та `/src`. Ваш фактичний проєкт закінчується підкаталогом у каталозі `/src`, тому, якщо у вашому проєкті є каталог `/src`, шлях до проєкту буде виглядати наступним чином: `/some/path/to/workspace/src/ваш_проєкт/src/ваш_код.go`. Зауважте, що з Go 1.11 можна мати проєкт поза `GOPATH`, але це ще не означає, що це гарна ідея використовувати цей шаблон компонування. 188 | 189 | 190 | ## Бейджі 191 | 192 | * [Go Report Card](https://goreportcard.com/) - відсканує ваш код за допомогою `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` та `misspell`. Замініть `github.com/golang-standards/project-layout` посиланням на ваш проєкт. 193 | 194 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 195 | 196 | * ~~[GoDoc](http://godoc.org) - надає онлайн-версію вашої документації, створеної у форматі GoDoc. Змініть посилання, щоб воно вказувало на ваш проєкт.~~ 197 | 198 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 199 | 200 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev це нове місцезнаходження для дослідження Go та документації. Ви можете створити бейдж використовуючи [badge generation tool](https://pkg.go.dev/badge). 201 | 202 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 203 | 204 | * Реліз - покаже номер останнього релізу для вашого проєкту. Змініть посилання на github, щоб воно вказувало на ваш проєкт. 205 | 206 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 207 | 208 | ## Нотатки 209 | 210 | Більш розгорнутий шаблон проєкту зі зразками/багаторазовими конфігураціями, скриптами та кодом - це WIP. 211 | -------------------------------------------------------------------------------- /README_vi.md: -------------------------------------------------------------------------------- 1 | # Bố cục tiêu chuẩn của một dự án Go 2 | 3 | Các bản dịch: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Vietnamese](README_vi.md) 18 | * [हिन्दी](README_hi.md) 19 | * [Беларуская](README_be.md) 20 | 21 | ## Tổng quan 22 | 23 | Đây là một bố cục cơ bản cho nhiều ứng dụng Go. Dù **`không phải là tiêu chuẩn chính thức được đưa ra từ đội ngũ cốt lõi của Go`**, đây là một tập hợp mẫu bố cục trong hệ sinh thái Go. Những cải tiến nhỏ cùng với một số thư mục hỗ trợ đều có thể được dùng phổ biến cho bất kỳ ứng dụng lớn nào trong thực tế. 24 | 25 | **`Nếu bạn đang muốn học Go hoặc đang xây dựng một PoC hoặc một dự án cá nhân đơn giản thì bố cục này là thừa. Bạn nên bắt đầu bằng những thứ đơn giản hơn (chẳng hạn một tập tin `main.go`và một tập tin`go.mod` là đủ).`** Hãy nhớ một điều là khi dự án của bạn phát triển, điều quan trọng là dự án của bạn có cấu trúc tốt, nếu không thì bạn sẽ gặp nhiều vấn đề với mã nguồn lộn xộn cùng các phụ thuộc ẩn và trạng thái toàn cục. Khi bạn có nhiều người làm việc trên một dự án, bạn còn cần cấu trúc nhiều hơn. Vì thế, việc quan trọng là giới thiệu cách phổ biến để quản lý các gói/thư viện. Khi bạn có một dự án mã nguồn mở hoặc khi bạn biết các dự án khác, hãy nhập mã từ kho lưu trữ dự án của bạn, đó là lúc điều quan trọng là phải có các gói và mã riêng tư (hay còn gọi là `nội bộ`). Sao y kho lưu trữ, giữ lại những thứ bạn cần và xóa hết phần còn lại! Chỉ vì nó ở đó không có nghĩa là bạn phải sử dụng tất cả. Không có mẫu nào trong số này được sử dụng trong mọi dự án. Ngay cả mô hình `vendor` cũng không phải là phổ biến. 26 | 27 | Ở phiên bản Go 1.14, [`Go Modules`](https://go.dev/wiki/Modules) đã sẵn sàng để dùng trên môi trường production. Trừ khi bạn có một lý do cục thể nào đấy, còn không thì bạn nên dùng [`Go Modules`](https://blog.golang.org/using-go-modules) vì bạn sẽ không cần để tâm tới $GOPATH và nơi bạn đặt dự án của mình. Tập tin cơ bản `go.mod` trong repo giả định rằng dự án của bạn được lưu trữ trên GitHub, nhưng nó không phải là một yêu cầu. Đường dẫn module có thể là bất kỳ thứ gì mặc dù phần đầu thành phần đường dẫn module phải có dấu chấm trong tên của nó (phiên bản Go hiện tại không bắt buộc điều này, nhưng nếu bạn đang sử dụng các phiên bản cũ hơn, đừng ngạc nhiên nếu bản dựng của bạn thất bại khi thiếu nó). Xem các lỗi [`37554`](https://github.com/golang/go/issues/37554) và [`32819`](https://github.com/golang/go/issues/32819) nếu bạn muốn tìm hiểu thêm. 28 | 29 | Bố cục dự án này có chủ đích chung chung và nó không cố gắng áp đặt một vài trúc gói Go cụ thể. 30 | 31 | Dự án này là nỗ lực của cộng đồng. Hãy mở một issue nếu bạn gặp một mẫu thiết kế nào mới hoặc bạn nghĩ những mẫu thiết kế có sẵn cần được cập nhật. 32 | 33 | Bắt đầu với [`gofmt`](https://golang.org/cmd/gofmt/) và [`golint`](https://github.com/golang/lint) nếu bạn cần hỗ trợ về cách đặt tên, định dạng và phong cách. Đồng thời, đảm bảo rằng bạn đã đọc các hướng dẫn và khuyến nghị của Go dưới đây: 34 | 35 | * https://talks.golang.org/2014/names.slide 36 | * https://golang.org/doc/effective_go.html#names 37 | * https://blog.golang.org/package-names 38 | * https://go.dev/wiki/CodeReviewComments 39 | * [Hướng dẫn thiết kế các gói trong Go](https://rakyll.org/style-packages) (rakyll/JBD) 40 | 41 | Đọc thêm [`Mẫu dự án Go`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) để biết thêm thông tin cơ bản. 42 | 43 | Tìm hiểu thêm về cách đặt tên và tổ chức các gói cũng như các đề xuất về cấu trúc mã khác: 44 | 45 | * [GopherCon EU 2018: Peter Bourgon - Thực tiễn tốt nhất cho lập trình công nghiệp](https://www.youtube.com/watch?v=PTE4VJIdHPg) 46 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Thực tiễn tốt trong Go.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 47 | * [GopherCon 2017: Edward Muller - Các chống mẫu trong Go](https://www.youtube.com/watch?v=ltqV6pDKZD8) 48 | * [GopherCon 2018: Kat Zien - Bạn cấu trúc ứng dụng Go của mình như thế nào](https://www.youtube.com/watch?v=oL6JBUk6tj0) 49 | 50 | Một bài đăng của Trung Quốc về hướng dẫn thiết kế theo hướng gói và lớp kiến ​​trúc 51 | 52 | * [Thiết kế theo hướng gói và phân lớp kiến ​​trúc](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 53 | 54 | ## Các thư mục trong Go 55 | 56 | ### `/cmd` 57 | 58 | Thư mục chứa các ứng dụng chính cho dự án này. 59 | 60 | Tên thư mục cho mỗi ứng dụng phải khớp với tên của tập tin thực thi mà bạn muốn có (ví dụ: `/cmd/myapp`). 61 | 62 | Đừng đặt nhiều mã trong thư mục ứng dụng. Nếu bạn nghĩ rằng mã có thể được nhập và sử dụng trong các dự án khác, thì nó sẽ nằm trong thư mục `/pkg`. Nếu mã không thể sử dụng lại được hoặc nếu bạn không muốn người khác sử dụng lại, hãy đặt mã đó vào thư mục `/internal`. Bạn sẽ ngạc nhiên về những gì người khác sẽ làm, vì vậy hãy rõ ràng về ý định của bạn! 63 | 64 | Thông thường có một hàm `main` nhỏ nhập và gọi mã từ các thư mục `/internal` và `/pkg` và không có gì khác. 65 | 66 | Xem thêm ví dụ ở thư mục [`/cmd`](cmd/README.md). 67 | 68 | ### `/internal` 69 | 70 | Thư mục chứa ứng dụng riêng và mã thư viện. Đây là mã mà bạn không muốn người khác sử dụng trong các ứng dụng hoặc thư viện của họ. Lưu ý, mẫu bố cục này được thực thi bởi chính trình biên dịch Go. Xem Go 1.4 [`ghi chú phát hành`](https://golang.org/doc/go1.4#internalpackages) để biết thêm chi tiết. Lưu ý rằng bạn không bị giới hạn ở thư mục `internal` cấp cao nhất. Bạn có thể có nhiều hơn một thư mục `internal` ở bất kỳ cấp nào trong cây dự án của bạn. 71 | 72 | Bạn có thể tùy chọn thêm một chút cấu trúc bổ sung vào các gói bên trong của mình để tách mã nội bộ được chia sẻ và không được chia sẻ. Nó không bắt buộc (đặc biệt đối với các dự án nhỏ), nhưng thật tuyệt khi có manh mối trực quan cho thấy mục đích sử dụng gói dự kiến. Mã ứng dụng thực tế của bạn có thể nằm trong thư mục `/internal/app` (ví dụ: `/internal/app/myapp`) và mã được các ứng dụng đó chia sẻ trong thư mục `/internal/pkg` (ví dụ: `/internal/pkg/myprivlib`). 73 | 74 | ### `/pkg` 75 | 76 | Thư mục chứa code thư viện cho phép các ứng dụng bên ngoài sử dụng (ví dụ: `/pkg/mypubliclib`). Các dự án khác sẽ nhập các thư viện này và kỳ vọng là chúng sẽ hoạt động, vì vậy hãy nghĩ cẩn thận trước khi bạn để thứ gì vào đây :-). Lưu ý rằng thư mục `nội bộ` là cách tốt hơn để đảm bảo các gói riêng tư của bạn không thể nhập được vì nó được Go thực thi. Thư mục `/pkg` vẫn là một cách tốt để thông báo rõ ràng rằng mã trong thư mục đó an toàn cho người khác sử dụng. Bài [`Tôi sẽ dùng pkg thay vì gói nội bộ`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) đăng bởi Travis Jeffery cung cấp một góc nhìn tổng quan về các thư mục `pkg` và `internal` và khi nào nên dùng chúng. 77 | 78 | Đó cũng là một cách để nhóm mã Go vào một nơi khi thư mục gốc của bạn chứa nhiều thành phần và thư mục không phải Go, giúp chạy các công cụ Go khác nhau dễ dàng hơn (như đã đề cập trong các bài nói này: [`Thực tiễn tốt nhất cho lập trình công nghiệp`](https://www.youtube.com/watch?v=PTE4VJIdHPg) từ GopherCon EU 2018, [GopherCon 2018: Kat Zien - Làm thế nào để tổ chức các ứng dụng Go](https://www.youtube.com/watch?v=oL6JBUk6tj0) và [GoLab 2018 - Massimiliano Pippi - Mẫu bố cục dự án trong Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 79 | 80 | Xem thư mục [`/pkg`](pkg/README.md) nếu bạn muốn xem repos Go phổ biến nào dùng bố cục này. Đây là một mẫu bố cục phổ biến, nhưng nó không được chấp nhận rộng rãi và một số người trong cộng đồng Go không khuyến khích nó. 81 | 82 | Bạn không nên sử dụng nó nếu dự án ứng dụng của bạn thực sự nhỏ và ở đó mức độ lồng ghép bổ sung không mang lại nhiều giá trị (trừ khi bạn thực sự muốn :-)). Hãy nghĩ về nó khi nó đủ lớn và thư mục gốc của bạn trở nên khá bận rộn (đặc biệt nếu bạn có nhiều thành phần ứng dụng không phải của Go). 83 | 84 | Nguồn gốc thư mục `pkg`: Mã nguồn Go cũ dùng `pkg` cho các gói của nó và sau đó các dự án Go khác trong cộng đồng bắt đầu sao chép mẫu này (xem [`Tweet`](https://twitter.com/bradfitz/status/1039512487538970624) của Brad Fitzpatrick để biết thêm ngữ cảnh). 85 | 86 | ### `/vendor` 87 | 88 | Thư mục chứa các phụ thuộc của ứng dụng (được quản lý thủ công hoặc bằng công cụ quản lý phụ thuộc ưa thích của bạn tương tự như tính năng tích hợp mới là [`Go Modules`](https://go.dev/wiki/Modules)). Câu lệnh `go mod vendor` sẽ tạo ra cho bạn một thư mục `/vendor`. Lưu ý rằng bạn có thể sẽ cần phải thêm cờ hiệu `-mod=vendor` cho câu lệnh `go build` nếu bạn không dùng Go 1.14, phiên bản được thêm cờ hiệu mặc định. 89 | 90 | Không nên commit các phụ thuộc ứng dụng nếu bạn đang muốn xây dựng một thư viện. 91 | 92 | Lưu ý rằng kể từ phiên bản [`1.13`](https://golang.org/doc/go1.13#modules), Go bật tính năng module proxy (mặc định dùng máy chủ module proxy [`https://proxy.golang.org`](https://proxy.golang.org)). Đọc thêm để xem liệu nó có phù hợp với tất cả các yêu cầu và ràng buộc của bạn hay không ở [`đây`](https://blog.golang.org/module-mirror-launch). Nếu có thì bạn không cần tới thư mục `vendor`. 93 | 94 | ## Thư mục ứng dụng dịch vụ 95 | 96 | ### `/api` 97 | 98 | Thư mục chứa bản mô tả OpenAPI/Swagger, tập tin lược đồ JSON, tập tin định nghĩa giao thức. 99 | 100 | Xem thêm ví dụ ở thư mục [`/api`](api/README.md). 101 | 102 | ## Thư mục ứng dụng Web 103 | 104 | ### `/web` 105 | 106 | Thư mục chứa các thành phần cụ thể của ứng dụng web: tài nguyên web tĩnh, mẫu bên máy chủ và SPAs. 107 | 108 | Để các tập mẫu `confd` và `consul-template` ở đây. 109 | 110 | ### `/init` 111 | 112 | Thư mục chứa phần khởi tạo hệ thống (systemd, upstart, sysv) và cấu hình quản lý/giám sát tiến trình (runit, supervisord). 113 | 114 | ### `/scripts` 115 | 116 | Thư mục chứa tập lệnh để thực hiện các hoạt động xây dựng, cài đặt, phân tích ... 117 | 118 | Các tập lệnh này làm cho tập Makefile ở cấp cao nhất nhỏ gọn và đơn giản. (Ví dụ: [`https://github.com/hashicorp/terraform/blob/master/Makefile`](https://github.com/hashicorp/terraform/blob/master/Makefile)) 119 | 120 | Xem ví dụ ở thư mục [`/scripts`](scripts/README.md). 121 | 122 | ### `/build` 123 | 124 | Thư mục chứa gói và tích hợp liên tục. 125 | 126 | Đặt các cấu hình và tập lệnh các gói đám mây (AMI), container (Docker), OS (deb, rpm, pkg) của bạn vào thư mục `/build/package`. 127 | 128 | Đặt cấu hình và tập lệnh CI (travis, circle, drone) trong thư mục `/build/ci`. Lưu ý rằng một vài công cụ CI (ví dụ: Travis CI) rất kén chọn vị trí của tập tin cấu hình. Thử đặt các tập tin cấu hình ở thư mục `/build/ci`, lên kết chúng với vị trí mà công cụ CI mong đợi (khi có thể). 129 | 130 | ### `/deployments` 131 | 132 | Thư mục chứa IaaS, PaaS, các cấu hình và mẫu triển khai điều phối hệ thống và vùng chứa (docker-compose, kubernetes/helm, mesos, terraform, bosh). Lưu ý rằng trong một số repo (đặc biệt là các ứng dụng được triển khai với kubernetes) thư mục này được gọi là `/deploy`. 133 | 134 | ### `/test` 135 | 136 | Thư mục chứa các ứng dụng thử nghiệm bên ngoài bổ sung và dữ liệu thử nghiệm. Hãy thoải mái cấu trúc thư mục `/test` theo cách bạn muốn. Đối với các dự án lớn hơn, điều hợp lý là có một thư mục con dữ liệu. Ví dụ: bạn có thể có `/test/data` hoặc `/test/testdata` nếu bạn cần Go bỏ qua những gì trong thư mục đó. Lưu ý rằng Go cũng sẽ bỏ qua các thư mục hoặc tệp bắt đầu bằng "." hoặc "_", vì vậy bạn có thể linh hoạt hơn về cách đặt tên cho thư mục dữ liệu thử nghiệm của mình. 137 | 138 | Xem ví dụ ở thư mục [`/test`](test/README.md). 139 | 140 | ## Thư mục khác 141 | 142 | ### `/docs` 143 | 144 | Thư mục chứa tài liệu người dùng và bản thiết kế (bên cạnh tài liệu do godoc tạo ra). 145 | 146 | Xem ví dụ ở thư mục [`/docs`](docs/README.md). 147 | 148 | ### `/tools` 149 | 150 | Thư mục chứa công cụ hỗ trợ cho dự án này. Lưu ý rằng các công cụ này có thể nhập mã từ thư mục `/pkg` và `/internal`. 151 | 152 | Xem ví dụ ở thư mục [`/tools`](tools/README.md). 153 | 154 | ### `/examples` 155 | 156 | Thư mục chứa mẫu cho ứng dụng và/hoặc các thư viện công cộng của bạn. 157 | 158 | Xem ví dụ ở thư mục [`/examples`](examples/README.md) 159 | 160 | ### `/third_party` 161 | 162 | Thư mục chứa các công cụ trợ giúp bên ngoài, mã phân nhánh và các tiện ích bên thứ ba khác (ví dụ: giao diện người dùng Swagger). 163 | 164 | ### `/githooks` 165 | 166 | Thư mục chứa git hooks. 167 | 168 | ### `/assets` 169 | 170 | Các tài sản khác đi cùng với kho lưu trữ của bạn (hình ảnh, logo ...). 171 | 172 | ### `/website` 173 | 174 | Đây là nơi để dữ liệu trang web của bạn nếu bạn không sử dụng các trang của GitHub. 175 | 176 | Xem ví dụ ở thư mục [`/website`](website/README.md). 177 | 178 | ## Thư mục bạn không nên có 179 | 180 | ### `/src` 181 | 182 | Một vài dự án Go có thư mục `src` nhưng nó thường xảy ra khi các nhà phát triển đến từ thế giới Java, nơi đó là một mẫu phổ biến. Bạn không nên học mẫu này từ Java. Bạn thực sự không muốn mã Go hoặc các dự án Go của mình trông giống như Java :-) 183 | 184 | Đừng nhầm lẫn giữa thư mục `/src` cấp dự án với thư mục `/src` mà Go sử dụng cho các không gian làm việc của nó như được mô tả trong [`Cách viết mã Go`](https://golang.org/doc/code.html). Biến môi trường `$GOPATH` trỏ tới không gian làm việc hiện tại của bạn (với những hệ thống không phải là Windows, nó mặc định trỏ tới `$HOME/go`). Không gian làm việc này bao gồm các thư mục `/pkg`, `/bin`, `/src` cấp cao nhất. Dự án thực tế của bạn kết thúc là một thư mục con trong `/src`, vì vậy nếu bạn có thư mục `/src` trong dự án của mình, đường dẫn dự án sẽ giống như sau: `/some/path/to/workspace/src/your_project/src/your_code.go`. Lưu ý rằng với Go 1.11, bạn có thể đặt dự án của mình bên ngoài `GOPATH`, nhưng điều đó không có nghĩa là bạn nên sử dụng mẫu bố cục này. 185 | 186 | ## Danh hiệu 187 | 188 | * [Go Report Card](https://goreportcard.com/) - Nó sẽ quét toàn bộ mã của bạn bằng `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` and `misspell`. Thay `github.com/golang-standards/project-layout` bằng tuỳ chọn trong dự án của bạn. 189 | 190 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 191 | 192 | * ~~[GoDoc](http://godoc.org) - Nó sẽ cung cấp phiên bản trực tuyến của tài liệu do GoDoc tự tạo. Đổi đường dẫn để trỏ tới dự án của bạn.~~ 193 | 194 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 195 | 196 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev là điểm đến mới cho khám phá và tài liệu về Go. Bạn có thể tạo huy hiệu bằng [badge generation tool](https://pkg.go.dev/badge). 197 | 198 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 199 | 200 | * Bản phát hành - Nó sẽ hiển thị số phát hành mới nhất cho dự án của bạn. Thay đổi liên kết github để trỏ đến dự án của bạn. 201 | 202 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 203 | 204 | ## Ghi chú 205 | 206 | Một mẫu dự án "có định kiến" (opinionated) hơn đang được xây dựng với các cấu hình, tập lệnh và mã có thể tái sử dụng. 207 | -------------------------------------------------------------------------------- /README_zh-CN.md: -------------------------------------------------------------------------------- 1 | # Go项目标准布局 2 | 3 | * [English](README.md) 4 | * [한국어 문서](README_ko.md) 5 | * [简体中文](README_zh.md) 6 | * [正體中文](README_zh-TW.md) 7 | * [简体中文](README_zh-CN.md) - ??? 8 | * [Français](README_fr.md) 9 | * [日本語](README_ja.md) 10 | * [Portuguese](README_ptBR.md) 11 | * [Español](README_es.md) 12 | * [Română](README_ro.md) 13 | * [Русский](README_ru.md) 14 | * [Türkçe](README_tr.md) 15 | * [Italiano](README_it.md) 16 | * [Vietnamese](README_vi.md) 17 | * [Українська](README_ua.md) 18 | * [Indonesian](README_id.md) 19 | * [हिन्दी](README_hi.md) 20 | * [Беларуская](README_be.md) 21 | 22 | 这是Go应用程序项目的基础布局。这不是Go核心开发团队定义的官方标准；无论是在经典项目还是在新兴的项目中，这都是Go生态系统中一组常见的项目布局模式。这其中有一些模式比另外的一些更受欢迎。它通过几个支撑目录为任何足够大规模的实际应用程序提供一些增强功能。 23 | 24 | 如果你正准备学习Go、正在构建PoC项目或编写玩具项目，那么按照这个项目进行布局就大材小用了。从一些真正简单的事情开始（一个`main.go`文件就足够了）。随着项目的增长，确保代码结构的合理是非常重要的，否则最终会出现很多隐藏的依赖关系和全局状态而导致这个项目的代码混乱。当一个项目多人同时进行时，就更需要有清晰的结构，此时引入一种通用的项目包/标准库管理工具就显得尤为重要。当你维护一个开源项目或者有其他项目导入了你的代码，那么有一个私有的包（如`internal`）就很重要了。克隆这个项目，保留你项目中需要的部分，并删除其他部分。通常来说不需要也没必要使用这个项目中的全部内容。因为，从来没有在一个单一的项目中使用本项目中定义的全部模式，甚至如`vendor`模式。 25 | 26 | Go 1.14 `Go Modules`已经可以用于生产环境。没有什么特殊原因的话，请使用`Go Modules`，使用它之后，你就再也不用担心`$GOPATH`的配置和项目实际的存放位置，项目想放在哪里就放在哪里。本项目中`go.mod`文件的内容假设你的项目是托管在GitHub上的，当然这不是必选项，因为`Module`中的路径可以是任意的值，一般`Module`路径的第一部分中应该包含一个点（最新版的Go中不再强制要求这一点，如果使用的是稍微旧一些的版本，那么可能遇到编译失败的问题）。了解更多请看Issues [37554](https://github.com/golang/go/issues/37554)和 [32819](https://github.com/golang/go/issues/32819)。 27 | 28 | 本项目布局有意设计的更通用一些，而不会尝试去引入一些特定的Go包结构。 29 | 30 | 这是社区共同的努力。如果发现了一种新的模式或者项目中已经存在的某些模式需要更新，请新建一个issue。 31 | 32 | 如果需要一些关于命名、格式化或者样式方面的帮助，请先运行[`gofmt`](https://golang.org/cmd/gofmt/)和[`golint`](https://github.com/golang/lint)。另外，请务必阅读以下Go代码样式指南和建议： 33 | 34 | * 35 | * 36 | * 37 | 38 | * 39 | 40 | * Style guideline for Go packages (rakyll/JBD) 41 | 42 | 更多背景信息请查看[`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2)。 43 | 44 | 有关命名和项目包组织样式以及其他代码结构的更多推荐文章： 45 | 46 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 47 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices](https://www.youtube.com/watch?v=MzTcsI6tn-0) 48 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 49 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 50 | 51 | ## Go目录 52 | 53 | ### `/cmd` 54 | 55 | 项目主要的应用程序。 56 | 57 | 对于每个应用程序来说这个目录的名字应该和项目可执行文件的名字相匹配（例如，`/cmd/myapp`）。 58 | 59 | 不要在这个目录中放太多的代码。如果目录中的代码可以被其他项目导入并使用，那么应该把他们放在`/pkg`目录。如果目录中的代码不可重用，或者不希望被他人使用，应该将代码放在`/internal`目录。显式地表明意图比较好！ 60 | 61 | 通常来说，项目都应该拥有一个小的`main`函数，并在`main`函数中导入或者调用`/internal`和`/pkg`目录中的代码。 62 | 63 | 更多详情，请看[`/cmd`](https://github.com/golang-standards/project-layout/blob/master/cmd/README.md)目录中的例子。 64 | 65 | ### `/internal` 66 | 67 | 私有的应用程序代码库。这些是不希望被其他人导入的代码。请注意：这种模式是Go编译器强制执行的。详细内容情况Go 1.4的[release notes](https://golang.org/doc/go1.4#internalpackages)。再次注意，在项目的目录树中的任意位置都可以有`internal`目录，而不仅仅是在顶级目录中。 68 | 69 | 可以在内部代码包中添加一些额外的结构，来分隔共享和非共享的内部代码。这不是必选项（尤其是在小项目中），但是有一个直观的包用途是很棒的。应用程序实际的代码可以放在`/internal/app`目录（如，`internal/app/myapp`），而应用程序的共享代码放在`/internal/pkg`目录（如，`internal/pkg/myprivlib`）中。 70 | 71 | ### `/pkg` 72 | 73 | 外部应用程序可以使用的库代码（如，`/pkg/mypubliclib`）。其他项目将会导入这些库来保证项目可以正常运行，所以在将代码放在这里前，一定要三思而行。请注意，`internal`目录是一个更好的选择来确保项目私有代码不会被其他人导入，因为这是Go强制执行的。使用`/pkg`目录来明确表示代码可以被其他人安全的导入仍然是一个好方式。Travis Jeffery撰写的关于 [I’ll take pkg over internal](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) 文章很好地概述了`pkg`和`inernal`目录以及何时使用它们。 74 | 75 | 当您的根目录包含大量非Go组件和目录时，这也是一种将Go代码分组到一个位置的方法，从而使运行各种Go工具更加容易（在如下的文章中都有提到：2018年GopherCon [Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg)，[Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) ，Golab 2018 [Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)）。 76 | 77 | 点击查看`/pkg`就能看到那些使用这个布局模式的流行Go代码仓库。这是一种常见的布局模式，但未被普遍接受，并且Go社区中的某些人不推荐这样做。 78 | 79 | 如果项目确实很小并且嵌套的层次并不会带来多少价值（除非你就是想用它），那么就不要使用它。请仔细思考这种情况，当项目变得很大，并且根目录中包含的内容相当繁杂（尤其是有很多非Go的组件）。 80 | 81 | ### `/vendor` 82 | 83 | 应用程序的依赖关系（通过手动或者使用喜欢的依赖管理工具，如新增的内置[Go Modules](https://go.dev/wiki/Modules)特性）。执行`go mod vendor`命令将会在项目中创建`/vendor`目录，注意，如果使用的不是Go 1.14版本，在执行`go build`进行编译时，需要添加`-mod=vendor`命令行选项，因为它不是默认选项。 84 | 85 | 构建库文件时，不要提交应用程序依赖项。 86 | 87 | 请注意，从[1.13](https://golang.org/doc/go1.13#modules)开始，Go也启动了模块代理特性（使用`https：//proxy.golang.org`作为默认的模块代理服务器）。点击[这里](https://blog.golang.org/module-mirror-launch)阅读有关它的更多信息，来了解它是否符合所需要求和约束。如果`Go Module`满足需要，那么就不需要`vendor`目录。 88 | 89 | ## 服务端应用程序的目录 90 | 91 | ### `/api` 92 | 93 | OpenAPI/Swagger规范，JSON模式文件，协议定义文件。 94 | 95 | 更多样例查看[`/api`](https://github.com/golang-standards/project-layout/blob/master/api/README.md)目录。 96 | 97 | ## Web应用程序的目录 98 | 99 | ### `/web` 100 | 101 | Web应用程序特定的组件：静态Web资源，服务器端模板和单页应用（Single-Page App，SPA）。 102 | 103 | ## 通用应用程序的目录 104 | 105 | ### `/configs` 106 | 107 | 配置文件模板或默认配置。 108 | 109 | 将`confd`或者`consul-template`文件放在这里。 110 | 111 | ### `/init` 112 | 113 | 系统初始化（systemd、upstart、sysv）和进程管理（runit、supervisord）配置。 114 | 115 | ### `/scripts` 116 | 117 | 用于执行各种构建，安装，分析等操作的脚本。 118 | 119 | 这些脚本使根级别的Makefile变得更小更简单（例如）。 120 | 121 | 更多样例查看[`/scripts`](https://github.com/golang-standards/project-layout/blob/master/scripts/README.md)。 122 | 123 | ### `/build` 124 | 125 | 打包和持续集成。 126 | 127 | 将云（AMI），容器（Docker），操作系统（deb，rpm，pkg）软件包配置和脚本放在`/build/package`目录中。 128 | 129 | 将CI（travis、circle、drone）配置文件和就脚本放在`build/ci`目录中。请注意，有一些CI工具（如，travis CI）对于配置文件的位置有严格的要求。尝试将配置文件放在`/build/ci`目录，然后链接到CI工具想要的位置。 130 | 131 | ### `/deployments` 132 | 133 | IaaS，PaaS，系统和容器编排部署配置和模板（docker-compose，kubernetes/helm，mesos，terraform，bosh）。请注意，在某些存储库中（尤其是使用kubernetes部署的应用程序），该目录的名字是`/deploy`。 134 | 135 | ### `/test` 136 | 137 | 外部测试应用程序和测试数据。随时根据需要构建`/test`目录。对于较大的项目，有一个数据子目录更好一些。例如，如果需要Go忽略目录中的内容，则可以使用`/test/data`或`/test/testdata`这样的目录名字。请注意，Go还将忽略以“`.`”或“`_`”开头的目录或文件，因此可以更具灵活性的来命名测试数据目录。 138 | 139 | 更多样例查看[`/test`](https://github.com/golang-standards/project-layout/blob/master/test/README.md)。 140 | 141 | ## 其他 142 | 143 | ### `/docs` 144 | 145 | 设计和用户文档（除了godoc生成的文档）。 146 | 147 | 更多样例查看[`/docs`](https://github.com/golang-standards/project-layout/blob/master/docs/README.md)。 148 | 149 | ### `/tools` 150 | 151 | 此项目的支持工具。请注意，这些工具可以从`/pkg`和`/internal`目录导入代码。 152 | 153 | 更多样例查看[`/tools`](https://github.com/golang-standards/project-layout/blob/master/tools/README.md)。 154 | 155 | ### `/examples` 156 | 157 | 应用程序或公共库的示例。 158 | 159 | 更多样例查看[`/examples`](https://github.com/golang-standards/project-layout/blob/master/examples/README.md)。 160 | 161 | ### `/third_party` 162 | 163 | 外部辅助工具，fork的代码和其他第三方工具（例如Swagger UI）。 164 | 165 | ### `/githooks` 166 | 167 | Git的钩子。 168 | 169 | ### `/assets` 170 | 171 | 项目中使用的其他资源（图像，Logo等）。 172 | 173 | ### `/website` 174 | 175 | 如果不使用Github pages，则在这里放置项目的网站数据。 176 | 177 | 更多样例查看[`/website`](https://github.com/golang-standards/project-layout/blob/master/website/README.md)。 178 | 179 | ## 不应该出现的目录 180 | 181 | ### `/src` 182 | 183 | 有一些Go项目确实包含`src`文件夹，但通常只有在开发者是从Java（这是Java中一个通用的模式）转过来的情况下才会有。如果可以的话请不要使用这种Java模式。你肯定不希望你的Go代码和项目看起来像Java。 184 | 185 | 不要将项目级别的`/src`目录与Go用于其工作空间的`/src`目录混淆，就像[How to Write Go Code](https://golang.org/doc/code.html)中描述的那样。`$GOPATH`环境变量指向当前的工作空间（默认情况下指向非Windows系统中的`$HOME/go`）。此工作空间包括顶级`/pkg`，`/bin`和`/src`目录。实际的项目最终变成`/src`下的子目录，因此，如果项目中有`/src`目录，则项目路径将会变成：`/some/path/to/workspace/src/your_project/src/your_code.go`。请注意，使用Go 1.11，可以将项目放在GOPATH之外，但这并不意味着使用此布局模式是个好主意。 186 | 187 | ## 徽章 188 | 189 | * [Go Report Card](https://goreportcard.com/)：它将使用`gofmt`，`vet`，`gocyclo`，`golint`，`ineffassign`，`license`和`mispell`扫描项目中的代码。将`github.com/golang-standards/project-layout`替换为你的项目的引用。 190 | * [GoDoc](http://godoc.org/)：它将提供GoDoc生成的文档的在线版本。更改链接以指向你的项目。 191 | * Release：它将显示你项目的最新版本号。更改github链接以指向你的项目。 192 | 193 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 194 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 195 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 196 | 197 | ## 注意 198 | 199 | WIP项目是一个自以为是的项目模板其中带有`sample/reusable`配置、脚本和代码。 200 | -------------------------------------------------------------------------------- /README_zh-TW.md: -------------------------------------------------------------------------------- 1 | # 標準 Go 專案目錄結構 (Standard Go Project Layout) 2 | 3 | 其他語言的翻譯： 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | 這是 Go 應用程式專案的基本目錄結構。它不是核心 Go 開發團隊定義的官方標準；然而，它是 Go 生態系統中一組常見的老專案和新專案的目錄結構。其中一些目錄結構比其他目錄結構更受歡迎。這個專案目錄結構還有一些細微的改進，可以支援任何大型且實用的應用程式目錄結構。 25 | 26 | 如果你才剛開始學習 Go 程式語言，或者你只是想建立一個實驗性的玩具專案，這個專案目錄結構就過於複雜了。從一個非常簡單的 `main.go` 檔案開始，其實已經綽綽有餘。但隨著專案增長，你一定要記得，維持一份良好的程式碼結構其實是非常重要的，否則你最終將會得到一堆淩亂的程式碼，這其中肯定也會包含大量隱藏的相依問題與全域狀態。當有越多人參與專案時，你也將需要更多、更好的目錄結構。這時候就是帶入套件/函式庫常見的管理方法最好的時機。當你擁有一個開源專案，或者當你知道有其他專案從你的專案匯入程式碼時，這時候擁有**私有的** (`internal`) 套件和程式碼就很重要。複製這個專案，保留你需要的內容，刪除所有用不到的內容！因為這些目錄結構在這裡並不意味著你全部都要用。這些目錄結構並不是每個專案都會這樣用，甚至連 `vendor` 模式也不是通用的。 27 | 28 | Go 1.14 的 [`Go Modules`](https://go.dev/wiki/Modules) 已經是正式版本，除非你有特定的理由不使用它們，否則請一律使用 [`Go Modules`](https://blog.golang.org/using-go-modules) 來管理套件。如果你用了 Go Modules 之後，就無需擔心 `$GOPATH` 與專案放置的位置。專案中的 `go.mod` 檔案假設你的專案放置在 GitHub 中，但這不是必須的。模組路徑可以是任意位址，然而你的模組路徑名稱至少要有個「點」(`.`) 才是合法路徑 (雖然最新版的 Go 不會強迫你一定要用網址當成模組路徑，但如果你用了早期的 Go 版本的話，遇到建置失敗就不要覺得奇怪)。如果你想知道更多資訊，請參考 Issues [`37554`](https://github.com/golang/go/issues/37554) 和 [`32819`](https://github.com/golang/go/issues/32819)。 29 | 30 | 此專案目錄結構是通用的，它並非嘗試強迫讓你使用在特定的 Go 套件結構。 31 | 32 | 這個套件是社群共同努力的成果。如果你看到新的模式，或者你認為一個現有的模式需要更新，請提出一個 issue 出來討論。 33 | 34 | 如果需要命名、格式與程式碼風格方面的協助，請使用 [`gofmt`](https://golang.org/cmd/gofmt/) 和 [`golint`](https://github.com/golang/lint)。也請確保你閱讀過以下這些 Go 程式碼撰寫風格的指導方針與建議： 35 | 36 | * https://talks.golang.org/2014/names.slide 37 | * https://golang.org/doc/effective_go.html#names 38 | * https://blog.golang.org/package-names 39 | * https://go.dev/wiki/CodeReviewComments 40 | 41 | 參見 [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) 了解更多的背景資訊。 42 | 43 | 更多關於套件的命名與組織方式，以及其他程式碼結構的建議： 44 | 45 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 46 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 47 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 48 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 49 | 50 | > 這裡有份中文的文件可供參考：[Go 面向包的设计和架构分层](https://github.com/danceyoung/paper-code/blob/master/package-oriented-design/packageorienteddesign.md) 51 | 52 | ## Go 目錄結構 53 | 54 | ### `/cmd` 55 | 56 | 本專案的主要應用程式。 57 | 58 | 每個應用程式的目錄名應該與你的執行檔案名稱一致 (例如：`/cmd/myapp`)。 59 | 60 | 不要在這個目錄下放置太多程式碼。如果你認為某些程式碼也可以從其他應用程式或專案中匯入使用，那麼這些程式碼應該位於 `/pkg` 目錄中。如果程式碼不是可重複利用的，或者你不希望其他人使用它，請將該程式碼放到 `/internal` 目錄下。你未來將會驚訝的發現別人是怎麼使用你的程式碼，所以請現在就明確的表達你的意圖！ 61 | 62 | 通常主要應用程式只會有一個小小的 `main` 函式，然後大部分的程式都是從 `/internal` 和 `/pkg` 匯入呼叫並執行，除此之外應該什麼都沒有！ 63 | 64 | 請查看 [`/cmd`](cmd/README.md) 目錄獲得更多範例。 65 | 66 | ### `/internal` 67 | 68 | **私有應用程式**和**函式庫**的程式碼，是你不希望其他人在其應用程式或函式庫中匯入的程式碼。請注意：這個目錄結構是由 Go 編譯器本身所要求的。有關更多細節，請參閱 Go 1.4 的 [`release notes`](https://golang.org/doc/go1.4#internalpackages)。注意：這個目錄並不侷限於放在專案最上層的 `internal` 目錄。事實上，你在專案目錄下的任何子目錄都可以包含 `internal` 目錄。 69 | 70 | 你可以選擇性的加入一些額外的目錄結構到你的內部套件(`internal package`)中，用來區分你想「共用」與「非共用」的內部程式碼(internal code)。這不是必要的（尤其是對小型專案來說），但有視覺上的線索來表達套件的共用意圖來說，肯定會更好(nice to have)。你的應用程式程式碼可以放在 `/internal/app` 目錄下 (例如：`/internal/app/myapp`)，而這些應用程式共享的程式碼就可以放在 `/internal/pkg` 目錄下 (例如：`/internal/pkg/myprivlib`)。 71 | 72 | ### `/pkg` 73 | 74 | 函式庫的程式碼當然可以讓外部應用程式來使用 (例如：`/pkg/mypubliclib`)，其他專案會匯入這些函式庫，並且期待它們能正常運作，所以要把程式放在這個目錄下請多想個幾遍！:-) 注意：使用 `internal` 目錄可以確保私有套件不會被匯入到其他專案使用，因為它是由 Go 的編譯器強制執行的，所以是比較好的解決方案。使用 `/pkg` 目錄仍然是一種很好的方式，它代表其他專案可以安全地使用這個目錄下的程式碼。由 Travis Jeffery 撰寫的 [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) 文章提供了關於 `pkg` 和 `internal` 目錄很好的概述，以及使用它們的時機點。 75 | 76 | 當專案的根目錄包含許多不是用 Go 所寫的元件與目錄時，將 Go 程式碼放在一個集中的目錄下也是種不錯的方法，這使得運行各種 Go 工具變得更加容易（正如以下這些演講中提到的那樣：來自 GopherCon EU 2018 的 [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg)、[GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 和 [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)）。 77 | 78 | 如果你想查看哪些知名的 Go 專案使用本專案的目錄結構，請查看 [`/pkg`](pkg/README.md) 目錄。這是一組常見的目錄結構，但並不是所有人都接受它，有些 Go 社群的人也不推薦使用。 79 | 80 | 如果你的應用程式專案真的很小，或是套用這些資料夾不會對你有太大幫助（除非你真的很想用XD），不使用本專案推薦的目錄結構是完全沒問題的。當你的專案變的越來越大，根目錄將會會變得越來越複雜（尤其是當你有許多不是 Go 所寫的元件時)，你可以考慮參考這個專案所建議的目錄結構來組織你的程式碼。 81 | 82 | ### `/vendor` 83 | 84 | 應用程式的相依套件可透過手動管理，或使用你喜歡的相依性套件管理工具，例如內建的 [`Go Modules`](https://go.dev/wiki/Modules) 特性。使用 `go mod vendor` 命令可以幫你建立一個 `/vendor` 目錄。請注意：如果你不是用 Go 1.14+ 版本的話，你可能需要在執行 `go build` 的時候增加 `-mod=vendor` 命令列參數。從 Go 1.14 開始，這個參數預設就是啟用的。 85 | 86 | 如果你正在建立一個函式庫套件，那麼請不要將你應用程式的相依套件加入版控！ 87 | 88 | 注意：從 [`Go 1.13`](https://golang.org/doc/go1.13#modules) 開始，Go 預設啟用了**模組的代理伺服器** (module proxy) 功能 (預設使用 [`https://proxy.golang.org`](https://proxy.golang.org) 作為模組的代理伺服器)。你可以從[`這裡`](https://blog.golang.org/module-mirror-launch)查看這功能是否符合你的需求與限制。如果你可以使用 module proxy 的話，那麼你根本不需要 `vendor` 目錄。 89 | 90 | ## 服務應用程式目錄 (Service Application Directories) 91 | 92 | ### `/api` 93 | 94 | OpenAPI/Swagger 規格、JSON schema 檔案、各種協定定義檔。 95 | 96 | 請查看 [`/api`](api/README.md) 目錄獲得更多範例。 97 | 98 | ## Web 應用程式目錄 (Web Application Directories) 99 | 100 | ### `/web` 101 | 102 | Web 應用程式相關的元件：靜態 Web 檔案、伺服器端範本與 SPAs 相關檔案。 103 | 104 | ## 通用應用程式目錄 (Common Application Directories) 105 | 106 | ### `/configs` 107 | 108 | 組態設定的檔案範本或預設設定。 109 | 110 | 將你的 `confd` 或 `consul-template` 範本檔案放在這裡。 111 | 112 | ### `/init` 113 | 114 | 放置 System init (`systemd`, `upstart`, `sysv`) 與 Process manager/supervisor (`runit`, `supervisor`) 相關設定。 115 | 116 | ### `/scripts` 117 | 118 | 放置要執行各種建置、安裝、分析等操作的命令腳本！ 119 | 120 | 這些腳本可以讓你在根目錄的 `Makefile` 更小、更簡單（例如：[`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile))。 121 | 122 | 請查看 [`/scripts`](scripts/README.md) 目錄獲得更多範例。 123 | 124 | ### `/build` 125 | 126 | 封裝套件與持續整合(CI)。 127 | 128 | 將你的雲端 (AMI)、容器 (Docker)、OS (deb, rpm, pkg) 套件的組態設定與腳本放在 `/build/package` 目錄下。 129 | 130 | 將你的 CI (Travis CI, CircleCI, Drone CI) 的組態設定與腳本放在 `/build/ci` 目錄中。請注意：有些 CI 工具 (例如 Travis CI 等)，它們對這些組態設定檔案的位置非常挑剔。如果可能的話，請嘗試將檔案放在 `/build/ci` 目錄中，並**連結** (linking) 這些檔案到 CI 工具期望它們出現的位置。 131 | 132 | ### `/deployments` 133 | 134 | IaaS、PaaS、系統和容器編配部署的組態設定與範本 (docker-compose、kubernetes/helm、mesos、terraform、bosh)。注意：在某些儲存庫中（特別是那些部署在 kubernetes 的應用程式），這個目錄會被命名為 `/deploy`。 135 | 136 | ### `/test` 137 | 138 | 額外的外部測試應用程式和測試資料。你可以自在的調整你在 `/test` 目錄中的結構。對於較大的專案來說，通常會有一個 `data` 資料夾也是蠻正常的。例如：如果你需要 Go 忽略這些目錄下的檔案，你可以使用 `/test/data` 或 `/test/testdata` 當作你的目錄名稱。請注意：Go 還會忽略以 `.` 或 `_` 開頭的目錄或檔案，所以你在測試資料的目錄命名上，將擁有更大的彈性。 139 | 140 | 請查看 [`/test`](test/README.md) 目錄獲得更多範例。 141 | 142 | ## 其他目錄 143 | 144 | ### `/docs` 145 | 146 | 設計和使用者文件 (除了 `godoc` 自動產生的文件之外)。 147 | 148 | 請查看 [`/docs`](docs/README.md) 目錄獲得更多範例。 149 | 150 | ### `/tools` 151 | 152 | 這個專案的支援工具。注意：這些工具可以從 `/pkg` 和 `/internal` 目錄匯入程式碼。 153 | 154 | 請查看 [`/tools`](tools/README.md) 目錄獲得更多範例。 155 | 156 | ### `/examples` 157 | 158 | 放置關於你的應用程式或公用函式庫的使用範例。 159 | 160 | 請查看 [`/examples`](examples/README.md) 目錄獲得更多範例。 161 | 162 | ### `/third_party` 163 | 164 | 外部輔助工具、Forked 程式碼，以及其他第三方工具 (例如：Swagger UI)。 165 | 166 | ### `/githooks` 167 | 168 | Git hooks。 169 | 170 | ### `/assets` 171 | 172 | 其他要一併放入儲存庫的相關檔案 (例如圖片、Logo、... 等等)。 173 | 174 | ### `/website` 175 | 176 | 如果你不使用 GitHub Pages 的話，這裡可以放置專案的網站相關資料。 177 | 178 | 請查看 [`/website`](website/README.md) 目錄獲得更多範例。 179 | 180 | ## 你不應該擁有的目錄 181 | 182 | ### `/src` 183 | 184 | 有些 Go 專案確實擁有一個 `src` 資料夾，但這通常發生在開發人員有 Java 背景，這在 Java 的世界很常見。如果你可以嘗試不要採用這種 Java 常見的資料夾的話，你應該不希望你的 Go 程式碼或 Go 專案看起來像 Java 吧！ :-) 185 | 186 | 不要將專案層級的 `/src` 目錄與 [`How to Write Go Code`](https://golang.org/doc/code.html) 所描述的 `/src` 混為一談。`$GOPATH` 環境變數指向你目前的工作區 (workspace)（非 Windows 的作業環境預設指向 `$HOME/go`），這個工作區包含了最上層的 `/pkg`、`/bin` 和 `/src` 目錄。你的實際專案最終其實是放在 `/src` 下的一個子目錄，所以你的專案路徑大概會長這樣：`/some/path/to/workspace/src/your_project/src/your_code.go`。注意：雖然 Go 1.11 可以將專案放在 `GOPATH` 之外，但這並不意味著使用這種目錄結構模式是一個好主意！ 187 | 188 | ## 徽章 (Badges) 189 | 190 | * [Go Report Card](https://goreportcard.com/) - 它會使用 `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` 與 `misspell` 掃描你的程式碼。如下範例請替換 `github.com/golang-standards/project-layout` 為你的專案參考。 191 | 192 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 193 | 194 | * ~~[GoDoc](http://godoc.org) - It will provide online version of your GoDoc generated documentation. Change the link to point to your project.~~ 195 | 196 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 197 | 198 | * [Pkg.go.dev](https://pkg.go.dev) - Pkg.go.dev 是一個探索 Go 與查閱相關文件的新目標，你可以利用 [徽章建立工具](https://pkg.go.dev/badge) 來替你的套件建立一個徽章。 199 | 200 | [![PkgGoDev](https://pkg.go.dev/badge/github.com/golang-standards/project-layout)](https://pkg.go.dev/github.com/golang-standards/project-layout) 201 | 202 | * Release - 它會顯示你專案中的最新發行版號。請變更 GitHub 連結到你的專案！ 203 | 204 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 205 | 206 | ## 備註 (Notes) 207 | 208 | 更多的專案範本，連同範例或可重用的組態設定、腳本命令、程式碼都在持續進行中! 209 | -------------------------------------------------------------------------------- /README_zh.md: -------------------------------------------------------------------------------- 1 | # Standard Go Project Layout 2 | 3 | 翻译: 4 | 5 | * [English](README.md) 6 | * [한국어 문서](README_ko.md) 7 | * [简体中文](README_zh.md) 8 | * [正體中文](README_zh-TW.md) 9 | * [简体中文](README_zh-CN.md) - ??? 10 | * [Français](README_fr.md) 11 | * [日本語](README_ja.md) 12 | * [Portuguese](README_ptBR.md) 13 | * [Español](README_es.md) 14 | * [Română](README_ro.md) 15 | * [Русский](README_ru.md) 16 | * [Türkçe](README_tr.md) 17 | * [Italiano](README_it.md) 18 | * [Vietnamese](README_vi.md) 19 | * [Українська](README_ua.md) 20 | * [Indonesian](README_id.md) 21 | * [हिन्दी](README_hi.md) 22 | * [Беларуская](README_be.md) 23 | 24 | 这是 Go 应用程序项目的基本布局。它不是核心 Go 开发团队定义的官方标准；然而，它是 Go 生态系统中一组常见的老项目和新项目的布局模式。其中一些模式比其他模式更受欢迎。它还具有许多小的增强，以及对任何足够大的实际应用程序通用的几个支持目录。 25 | 26 | 如果你尝试学习 Go，或者你正在为自己建立一个 PoC 或一个玩具项目，这个项目布局是没啥必要的。从一些非常简单的事情开始(一个 `main.go` 文件绰绰有余)。随着项目的增长，请记住保持代码结构良好非常重要，否则你最终会得到一个凌乱的代码，这其中就包含大量隐藏的依赖项和全局状态。当有更多的人参与这个项目时，你将需要更多的结构。这时候，介绍一种管理包/库的通用方法是很重要的。当你有一个开源项目时，或者当你知道其他项目从你的项目存储库中导入代码时，这时候拥有私有(又名 `internal`)包和代码就很重要。克隆存储库，保留你需要的内容，删除其他所有的内容！仅仅因为它在那里并不意味着你必须全部使用它。这些模式都没有在每个项目中使用。甚至 `vendor` 模式也不是通用的。 27 | 28 | Go 1.14 [`Go Modules`](https://go.dev/wiki/Modules) 终于可以投入生产了。除非你有特定的理由不使用它们，否则使用 [`Go Modules`](https://blog.golang.org/using-go-modules) 。如果你使用，就无需担心 $GOPATH 以及项目放置的位置。存储库中的 `go.mod` 文件基本假定你的项目托管在 Github 上，但这不是要求。模块路径可以是任何地方，尽管第一个模块路径组件的名称中应该有一个点（当前版本的 Go 不再强制使用该模块，但如果使用稍旧的版本，如果没有 `mod` 文件构建失败的话 ，不要惊讶）。如果你想知道更多信息，请参阅 Issues [`37554`](https://github.com/golang/go/issues/37554) 和 [`32819`](https://github.com/golang/go/issues/32819) 。 29 | 30 | 此项目布局是通用的，并且不会尝试强加一个特定的 Go 包结构。 31 | 32 | 这是社区的努力。 如果看到新的模式，或者认为一个现有的模式需要更新，请提一个 issue。 33 | 34 | 如果需要命名、格式和样式方面的帮助，请运行 [`gofmt`](https://golang.org/cmd/gofmt/) 和 [`golint`](https://github.com/golang/lint) 。还要确保阅读这些 Go 代码风格的指导方针和建议: 35 | * https://talks.golang.org/2014/names.slide 36 | * https://golang.org/doc/effective_go.html#names 37 | * https://blog.golang.org/package-names 38 | * https://go.dev/wiki/CodeReviewComments 39 | * [Style guideline for Go packages](https://rakyll.org/style-packages) (rakyll/JBD) 40 | 41 | 参见 [`Go Project Layout`](https://medium.com/golang-learn/go-project-layout-e5213cdcfaa2) 了解更多的背景信息。 42 | 43 | 更多关于包的命名和组织以及其他代码结构的建议: 44 | * [GopherCon EU 2018: Peter Bourgon - Best Practices for Industrial Programming](https://www.youtube.com/watch?v=PTE4VJIdHPg) 45 | * [GopherCon Russia 2018: Ashley McNamara + Brian Ketelsen - Go best practices.](https://www.youtube.com/watch?v=MzTcsI6tn-0) 46 | * [GopherCon 2017: Edward Muller - Go Anti-Patterns](https://www.youtube.com/watch?v=ltqV6pDKZD8) 47 | * [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 48 | 49 | ## Go 目录 50 | 51 | ### `/cmd` 52 | 53 | 本项目的主干。 54 | 55 | 每个应用程序的目录名应该与你想要的可执行文件的名称相匹配(例如，`/cmd/myapp`)。 56 | 57 | 不要在这个目录中放置太多代码。如果你认为代码可以导入并在其他项目中使用，那么它应该位于 `/pkg` 目录中。如果代码不是可重用的，或者你不希望其他人重用它，请将该代码放到 `/internal` 目录中。你会惊讶于别人会怎么做，所以要明确你的意图! 58 | 59 | 通常有一个小的 `main` 函数，从 `/internal` 和 `/pkg` 目录导入和调用代码，除此之外没有别的东西。 60 | 61 | 有关示例，请参阅 [`/cmd`](cmd/README.md) 目录。 62 | 63 | ### `/internal` 64 | 65 | 私有应用程序和库代码。这是你不希望其他人在其应用程序或库中导入代码。请注意，这个布局模式是由 Go 编译器本身执行的。有关更多细节，请参阅Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) 。注意，你并不局限于顶级 `internal` 目录。在项目树的任何级别上都可以有多个内部目录。 66 | 67 | 你可以选择向 internal 包中添加一些额外的结构，以分隔共享和非共享的内部代码。这不是必需的(特别是对于较小的项目)，但是最好有可视化的线索来显示预期的包的用途。你的实际应用程序代码可以放在 `/internal/app` 目录下(例如 `/internal/app/myapp`)，这些应用程序共享的代码可以放在 `/internal/pkg` 目录下(例如 `/internal/pkg/myprivlib`)。 68 | 69 | ### `/pkg` 70 | 71 | 外部应用程序可以使用的库代码(例如 `/pkg/mypubliclib`)。其他项目会导入这些库，希望它们能正常工作，所以在这里放东西之前要三思:-)注意，`internal` 目录是确保私有包不可导入的更好方法，因为它是由 Go 强制执行的。`/pkg` 目录仍然是一种很好的方式，可以显式地表示该目录中的代码对于其他人来说是安全使用的好方法。由 Travis Jeffery  撰写的 [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) 博客文章提供了 `pkg` 和 `internal` 目录的一个很好的概述，以及什么时候使用它们是有意义的。 72 | 73 | 当根目录包含大量非 Go 组件和目录时，这也是一种将 Go 代码分组到一个位置的方法，这使得运行各种 Go 工具变得更加容易（正如在这些演讲中提到的那样: 来自 GopherCon EU 2018 的 [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) , [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) 和 [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk) ）。 74 | 75 | 如果你想查看哪个流行的 Go 存储库使用此项目布局模式，请查看 [`/pkg`](pkg/README.md) 目录。这是一种常见的布局模式，但并不是所有人都接受它，一些 Go 社区的人也不推荐它。 76 | 77 | 如果你的应用程序项目真的很小，并且额外的嵌套并不能增加多少价值(除非你真的想要:-)，那就不要使用它。当它变得足够大时，你的根目录会变得非常繁琐时(尤其是当你有很多非 Go 应用组件时)，请考虑一下。 78 | 79 | ### `/vendor` 80 | 81 | 应用程序依赖项(手动管理或使用你喜欢的依赖项管理工具，如新的内置 [`Go Modules`](https://go.dev/wiki/Modules) 功能)。`go mod vendor` 命令将为你创建 `/vendor` 目录。请注意，如果未使用默认情况下处于启用状态的 Go 1.14，则可能需要在 `go build` 命令中添加 `-mod=vendor` 标志。 82 | 83 | 如果你正在构建一个库，那么不要提交你的应用程序依赖项。 84 | 85 | 注意，自从 [`1.13`](https://golang.org/doc/go1.13#modules) 以后，Go 还启用了模块代理功能(默认使用 [`https://proxy.golang.org`](https://proxy.golang.org) 作为他们的模块代理服务器)。在[`here`](https://blog.golang.org/module-mirror-launch) 阅读更多关于它的信息，看看它是否符合你的所有需求和约束。如果需要，那么你根本不需要 `vendor` 目录。 86 | 87 | 国内模块代理功能默认是被墙的，七牛云有维护专门的的[`模块代理`](https://github.com/goproxy/goproxy.cn/blob/master/README.zh-CN.md) 。 88 | 89 | ## 服务应用程序目录 90 | 91 | ### `/api` 92 | 93 | OpenAPI/Swagger 规范，JSON 模式文件，协议定义文件。 94 | 95 | 有关示例，请参见 [`/api`](api/README.md) 目录。 96 | 97 | ## Web 应用程序目录 98 | 99 | ### `/web` 100 | 101 | 特定于 Web 应用程序的组件:静态 Web 资源、服务器端模板和 SPAs。 102 | 103 | 104 | ## 通用应用目录 105 | 106 | 107 | ### `/configs` 108 | 109 | 配置文件模板或默认配置。 110 | 111 | 将你的 `confd` 或 `consul-template` 模板文件放在这里。 112 | 113 | ### `/init` 114 | 115 | System init（systemd，upstart，sysv）和 process manager/supervisor（runit，supervisor）配置。 116 | 117 | ### `/scripts` 118 | 119 | 执行各种构建、安装、分析等操作的脚本。 120 | 121 | 这些脚本保持了根级别的 Makefile 变得小而简单(例如， [`https://github.com/hashicorp/terraform/blob/main/Makefile`](https://github.com/hashicorp/terraform/blob/main/Makefile) )。 122 | 123 | 有关示例，请参见  [`/scripts`](scripts/README.md) 目录。 124 | 125 | ### `/build` 126 | 127 | 打包和持续集成。 128 | 129 | 将你的云( AMI )、容器( Docker )、操作系统( deb、rpm、pkg )包配置和脚本放在 `/build/package` 目录下。 130 | 131 | 将你的 CI (travis、circle、drone)配置和脚本放在 `/build/ci` 目录中。请注意，有些 CI 工具(例如 Travis CI)对配置文件的位置非常挑剔。尝试将配置文件放在 `/build/ci` 目录中，将它们链接到 CI 工具期望它们的位置(如果可能的话)。 132 | 133 | ### `/deployments` 134 | 135 | IaaS、PaaS、系统和容器编排部署配置和模板(docker-compose、kubernetes/helm、mesos、terraform、bosh)。注意，在一些存储库中(特别是使用 kubernetes 部署的应用程序)，这个目录被称为 `/deploy`。 136 | 137 | ### `/test` 138 | 139 | 额外的外部测试应用程序和测试数据。你可以随时根据需求构造 `/test` 目录。对于较大的项目，有一个数据子目录是有意义的。例如，你可以使用 `/test/data` 或 `/test/testdata` (如果你需要忽略目录中的内容)。请注意，Go 还会忽略以“.”或“_”开头的目录或文件，因此在如何命名测试数据目录方面有更大的灵活性。 140 | 141 | 有关示例，请参见  [`/test`](test/README.md) 目录。 142 | 143 | ## 其他目录 144 | 145 | ### `/docs` 146 | 147 | 设计和用户文档(除了 godoc 生成的文档之外)。 148 | 149 | 有关示例，请参阅 [`/docs`](docs/README.md) 目录。 150 | 151 | ### `/tools` 152 | 153 | 这个项目的支持工具。注意，这些工具可以从 `/pkg` 和 `/internal` 目录导入代码。 154 | 155 | 有关示例，请参见 [`/tools`](tools/README.md) 目录。 156 | 157 | ### `/examples` 158 | 159 | 你的应用程序和/或公共库的示例。 160 | 161 | 有关示例，请参见 [`/examples`](examples/README.md) 目录。 162 | 163 | ### `/third_party` 164 | 165 | 外部辅助工具，分叉代码和其他第三方工具(例如 Swagger UI)。 166 | 167 | ### `/githooks` 168 | 169 | Git hooks。 170 | 171 | ### `/assets` 172 | 173 | 与存储库一起使用的其他资源(图像、徽标等)。 174 | 175 | ### `/website` 176 | 177 | 如果你不使用 Github 页面，则在这里放置项目的网站数据。 178 | 179 | 有关示例，请参见 [`/website`](website/README.md) 目录。 180 | 181 | ## 你不应该拥有的目录 182 | 183 | ### `/src` 184 | 185 | 有些 Go 项目确实有一个 `src` 文件夹，但这通常发生在开发人员有 Java 背景，在那里它是一种常见的模式。如果可以的话，尽量不要采用这种 Java 模式。你真的不希望你的 Go 代码或 Go 项目看起来像 Java:-) 186 | 187 | 不要将项目级别 `src` 目录与 Go 用于其工作空间的 `src` 目录(如 [`How to Write Go Code`](https://golang.org/doc/code.html) 中所述)混淆。`$GOPATH` 环境变量指向你的(当前)工作空间(默认情况下，它指向非 windows 系统上的 `$HOME/go`)。这个工作空间包括顶层 `/pkg`, `/bin` 和 `/src` 目录。你的实际项目最终是 `/src` 下的一个子目录，因此，如果你的项目中有 `/src` 目录，那么项目路径将是这样的: `/some/path/to/workspace/src/your_project/src/your_code.go`。注意，在 Go 1.11 中，可以将项目放在 `GOPATH` 之外，但这并不意味着使用这种布局模式是一个好主意。 188 | 189 | 190 | ## Badges 191 | 192 | * [Go Report Card](https://goreportcard.com/) - It will scan your code with `gofmt`, `go vet`, `gocyclo`, `golint`, `ineffassign`, `license` and `misspell`. Replace `github.com/golang-standards/project-layout` with your project reference. 193 | 194 | * [GoDoc](http://godoc.org) - It will provide online version of your GoDoc generated documentation. Change the link to point to your project. 195 | 196 | * Release - It will show the latest release number for your project. Change the github link to point to your project. 197 | 198 | [![Go Report Card](https://goreportcard.com/badge/github.com/golang-standards/project-layout?style=flat-square)](https://goreportcard.com/report/github.com/golang-standards/project-layout) 199 | [![Go Doc](https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square)](http://godoc.org/github.com/golang-standards/project-layout) 200 | [![Release](https://img.shields.io/github/release/golang-standards/project-layout.svg?style=flat-square)](https://github.com/golang-standards/project-layout/releases/latest) 201 | 202 | ## Notes 203 | 204 | A more opinionated project template with sample/reusable configs, scripts and code is a WIP. 205 | 206 | -------------------------------------------------------------------------------- /api/README.md: -------------------------------------------------------------------------------- 1 | # `/api` 2 | 3 | OpenAPI/Swagger specs, JSON schema files, protocol definition files. 4 | 5 | Examples: 6 | 7 | * https://github.com/kubernetes/kubernetes/tree/master/api 8 | * https://github.com/moby/moby/tree/master/api 9 | -------------------------------------------------------------------------------- /assets/README.md: -------------------------------------------------------------------------------- 1 | # `/assets` 2 | 3 | Other assets to go along with your repository (images, logos, etc). 4 | -------------------------------------------------------------------------------- /build/README.md: -------------------------------------------------------------------------------- 1 | # `/build` 2 | 3 | Packaging and Continuous Integration. 4 | 5 | Put your cloud (AMI), container (Docker), OS (deb, rpm, pkg) package configurations and scripts in the `/build/package` directory. 6 | 7 | Put your CI (travis, circle, drone) configurations and scripts in the `/build/ci` directory. Note that some of the CI tools (e.g., Travis CI) are very picky about the location of their config files. Try putting the config files in the `/build/ci` directory linking them to the location where the CI tools expect them when possible (don't worry if it's not and if keeping those files in the root directory makes your life easier :-)). 8 | 9 | Examples: 10 | 11 | * https://github.com/cockroachdb/cockroach/tree/master/build 12 | -------------------------------------------------------------------------------- /build/ci/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/build/ci/.keep -------------------------------------------------------------------------------- /build/package/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/build/package/.keep -------------------------------------------------------------------------------- /cmd/README.md: -------------------------------------------------------------------------------- 1 | # `/cmd` 2 | 3 | Main applications for this project. 4 | 5 | The directory name for each application should match the name of the executable you want to have (e.g., `/cmd/myapp`). 6 | 7 | Don't put a lot of code in the application directory. If you think the code can be imported and used in other projects, then it should live in the `/pkg` directory. If the code is not reusable or if you don't want others to reuse it, put that code in the `/internal` directory. You'll be surprised what others will do, so be explicit about your intentions! 8 | 9 | It's common to have a small `main` function that imports and invokes the code from the `/internal` and `/pkg` directories and nothing else. 10 | 11 | Examples: 12 | 13 | * https://github.com/vmware-tanzu/velero/tree/main/cmd (just a really small `main` function with everything else in packages) 14 | * https://github.com/moby/moby/tree/master/cmd 15 | * https://github.com/prometheus/prometheus/tree/main/cmd 16 | * https://github.com/influxdata/influxdb/tree/master/cmd 17 | * https://github.com/kubernetes/kubernetes/tree/master/cmd 18 | * https://github.com/dapr/dapr/tree/master/cmd 19 | * https://github.com/ethereum/go-ethereum/tree/master/cmd 20 | -------------------------------------------------------------------------------- /cmd/_your_app_/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/cmd/_your_app_/.keep -------------------------------------------------------------------------------- /configs/README.md: -------------------------------------------------------------------------------- 1 | # `/configs` 2 | 3 | Configuration file templates or default configs. 4 | 5 | Put your `confd` or `consul-template` template files here. 6 | -------------------------------------------------------------------------------- /deployments/README.md: -------------------------------------------------------------------------------- 1 | # `/deployments` 2 | 3 | IaaS, PaaS, system and container orchestration deployment configurations and templates (docker-compose, kubernetes/helm, mesos, terraform, bosh). 4 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # `/docs` 2 | 3 | Design and user documents (in addition to your godoc generated documentation). 4 | 5 | Examples: 6 | 7 | * https://github.com/gohugoio/hugo/tree/master/docs 8 | * https://github.com/openshift/origin/tree/master/docs 9 | * https://github.com/dapr/dapr/tree/master/docs 10 | -------------------------------------------------------------------------------- /examples/README.md: -------------------------------------------------------------------------------- 1 | # `/examples` 2 | 3 | Examples for your applications and/or public libraries. 4 | 5 | Examples: 6 | 7 | * https://github.com/nats-io/nats.go/tree/master/examples 8 | * https://github.com/docker-slim/docker-slim/tree/master/examples 9 | * https://github.com/hashicorp/packer/tree/master/examples 10 | -------------------------------------------------------------------------------- /githooks/README.md: -------------------------------------------------------------------------------- 1 | # `/githooks` 2 | 3 | Git hooks. 4 | -------------------------------------------------------------------------------- /go.mod: -------------------------------------------------------------------------------- 1 | module github.com/YOUR-USER-OR-ORG-NAME/YOUR-REPO-NAME 2 | 3 | go 1.19 4 | -------------------------------------------------------------------------------- /init/README.md: -------------------------------------------------------------------------------- 1 | # `/init` 2 | 3 | System init (systemd, upstart, sysv) and process manager/supervisor (runit, supervisord) configs. 4 | -------------------------------------------------------------------------------- /internal/README.md: -------------------------------------------------------------------------------- 1 | # `/internal` 2 | 3 | Private application and library code. This is the code you don't want others importing in their applications or libraries. Note that this layout pattern is enforced by the Go compiler itself. See the Go 1.4 [`release notes`](https://golang.org/doc/go1.4#internalpackages) for more details. Note that you are not limited to the top level `internal` directory. You can have more than one `internal` directory at any level of your project tree. 4 | 5 | You can optionally add a bit of extra structure to your internal packages to separate your shared and non-shared internal code. It's not required (especially for smaller projects), but it's nice to have visual clues showing the intended package use. Your actual application code can go in the `/internal/app` directory (e.g., `/internal/app/myapp`) and the code shared by those apps in the `/internal/pkg` directory (e.g., `/internal/pkg/myprivlib`). 6 | 7 | Examples: 8 | 9 | * https://github.com/hashicorp/terraform/tree/main/internal 10 | * https://github.com/influxdata/influxdb/tree/master/internal 11 | * https://github.com/perkeep/perkeep/tree/master/internal 12 | * https://github.com/jaegertracing/jaeger/tree/main/internal 13 | * https://github.com/moby/moby/tree/master/internal 14 | * https://github.com/satellity/satellity/tree/main/internal 15 | * https://github.com/minio/minio/tree/master/internal 16 | 17 | ## `/internal/pkg` 18 | 19 | Examples: 20 | 21 | * https://github.com/hashicorp/waypoint/tree/main/internal/pkg 22 | -------------------------------------------------------------------------------- /internal/app/_your_app_/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/internal/app/_your_app_/.keep -------------------------------------------------------------------------------- /internal/pkg/_your_private_lib_/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/internal/pkg/_your_private_lib_/.keep -------------------------------------------------------------------------------- /pkg/README.md: -------------------------------------------------------------------------------- 1 | # `/pkg` 2 | 3 | Library code that's ok to use by external applications (e.g., `/pkg/mypubliclib`). Other projects will import these libraries expecting them to work, so think twice before you put something here :-) Note that the `internal` directory is a better way to ensure your private packages are not importable because it's enforced by Go. The `/pkg` directory is still a good way to explicitly communicate that the code in that directory is safe for use by others. The [`I'll take pkg over internal`](https://travisjeffery.com/b/2019/11/i-ll-take-pkg-over-internal/) blog post by Travis Jeffery provides a good overview of the `pkg` and `internal` directories and when it might make sense to use them. 4 | 5 | It's also a way to group Go code in one place when your root directory contains lots of non-Go components and directories making it easier to run various Go tools (as mentioned in these talks: [`Best Practices for Industrial Programming`](https://www.youtube.com/watch?v=PTE4VJIdHPg) from GopherCon EU 2018, [GopherCon 2018: Kat Zien - How Do You Structure Your Go Apps](https://www.youtube.com/watch?v=oL6JBUk6tj0) and [GoLab 2018 - Massimiliano Pippi - Project layout patterns in Go](https://www.youtube.com/watch?v=3gQa1LWwuzk)). 6 | 7 | Note that this is not a universally accepted pattern and for every popular repo that uses it you can find 10 that don't. It's up to you to decide if you want to use this pattern or not. Regardless of whether or not it's a good pattern more people will know what you mean than not. It might a bit confusing for some of the new Go devs, but it's a pretty simple confusion to resolve and that's one of the goals for this project layout repo. 8 | 9 | Ok not to use it if your app project is really small and where an extra level of nesting doesn't add much value (unless you really want to). Think about it when it's getting big enough and your root directory gets pretty busy (especially if you have a lot of non-Go app components). 10 | 11 | The `pkg` directory origins: The old Go source code used to use `pkg` for its packages and then various Go projects in the community started copying the pattern (see [`this`](https://twitter.com/bradfitz/status/1039512487538970624) Brad Fitzpatrick's tweet for more context). 12 | 13 | 14 | Examples: 15 | 16 | * https://github.com/containerd/containerd/tree/main/pkg 17 | * https://github.com/slimtoolkit/slim/tree/master/pkg 18 | * https://github.com/telepresenceio/telepresence/tree/release/v2/pkg 19 | * https://github.com/jaegertracing/jaeger/tree/master/pkg 20 | * https://github.com/istio/istio/tree/master/pkg 21 | * https://github.com/GoogleContainerTools/kaniko/tree/master/pkg 22 | * https://github.com/google/gvisor/tree/master/pkg 23 | * https://github.com/google/syzkaller/tree/master/pkg 24 | * https://github.com/perkeep/perkeep/tree/master/pkg 25 | * https://github.com/heptio/ark/tree/master/pkg 26 | * https://github.com/argoproj/argo-workflows/tree/master/pkg 27 | * https://github.com/argoproj/argo-cd/tree/master/pkg 28 | * https://github.com/heptio/sonobuoy/tree/master/pkg 29 | * https://github.com/helm/helm/tree/master/pkg 30 | * https://github.com/k3s-io/k3s/tree/master/pkg 31 | * https://github.com/kubernetes/kubernetes/tree/master/pkg 32 | * https://github.com/kubernetes/kops/tree/master/pkg 33 | * https://github.com/moby/moby/tree/master/pkg 34 | * https://github.com/grafana/grafana/tree/master/pkg 35 | * https://github.com/influxdata/influxdb/tree/master/pkg 36 | * https://github.com/cockroachdb/cockroach/tree/master/pkg 37 | * https://github.com/derekparker/delve/tree/master/pkg 38 | * https://github.com/etcd-io/etcd/tree/master/pkg 39 | * https://github.com/oklog/oklog/tree/master/pkg 40 | * https://github.com/flynn/flynn/tree/master/pkg 41 | * https://github.com/jesseduffield/lazygit/tree/master/pkg 42 | * https://github.com/gopasspw/gopass/tree/master/pkg 43 | * https://github.com/sosedoff/pgweb/tree/master/pkg 44 | * https://github.com/GoogleContainerTools/skaffold/tree/master/pkg 45 | * https://github.com/knative/serving/tree/master/pkg 46 | * https://github.com/grafana/loki/tree/master/pkg 47 | * https://github.com/bloomberg/goldpinger/tree/master/pkg 48 | * https://github.com/Ne0nd0g/merlin/tree/master/pkg 49 | * https://github.com/jenkins-x/jx/tree/master/pkg 50 | * https://github.com/DataDog/datadog-agent/tree/master/pkg 51 | * https://github.com/dapr/dapr/tree/master/pkg 52 | * https://github.com/cortexproject/cortex/tree/master/pkg 53 | * https://github.com/dexidp/dex/tree/master/pkg 54 | * https://github.com/pusher/oauth2_proxy/tree/master/pkg 55 | * https://github.com/pdfcpu/pdfcpu/tree/master/pkg 56 | * https://github.com/weaveworks/kured/tree/master/pkg 57 | * https://github.com/weaveworks/footloose/tree/master/pkg 58 | * https://github.com/weaveworks/ignite/tree/master/pkg 59 | * https://github.com/tmrts/boilr/tree/master/pkg 60 | * https://github.com/kata-containers/runtime/tree/master/pkg 61 | * https://github.com/okteto/okteto/tree/master/pkg 62 | * https://github.com/solo-io/squash/tree/master/pkg 63 | * https://github.com/google/exposure-notifications-server/tree/main/pkg 64 | * https://github.com/spiffe/spire/tree/main/pkg 65 | * https://github.com/rook/rook/tree/master/pkg 66 | * https://github.com/buildpacks/pack/tree/main/pkg 67 | * https://github.com/cilium/cilium/tree/main/pkg 68 | * https://github.com/containernetworking/cni/tree/main/pkg 69 | * https://github.com/crossplane/crossplane/tree/master/pkg 70 | * https://github.com/dragonflyoss/Dragonfly2/tree/main/pkg 71 | * https://github.com/kubeedge/kubeedge/tree/master/pkg 72 | * https://github.com/kubevela/kubevela/tree/master/pkg 73 | * https://github.com/kubevirt/kubevirt/tree/main/pkg 74 | * https://github.com/kyverno/kyverno/tree/main/pkg 75 | * https://github.com/thanos-io/thanos/tree/main/pkg 76 | * https://github.com/cri-o/cri-o/tree/main/pkg 77 | * https://github.com/fluxcd/flux2/tree/main/pkg 78 | * https://github.com/kedacore/keda/tree/main/pkg 79 | * https://github.com/linkerd/linkerd2/tree/main/pkg 80 | * https://github.com/opencost/opencost/tree/develop/pkg 81 | * https://github.com/antrea-io/antrea/tree/main/pkg 82 | * https://github.com/karmada-io/karmada/tree/master/pkg 83 | * https://github.com/kuberhealthy/kuberhealthy/tree/master/pkg 84 | * https://github.com/submariner-io/submariner/tree/devel/pkg 85 | * https://github.com/trickstercache/trickster/tree/main/pkg 86 | * https://github.com/tellerops/teller/tree/master/pkg 87 | * https://github.com/OpenFunction/OpenFunction/tree/main/pkg 88 | * https://github.com/external-secrets/external-secrets/tree/main/pkg 89 | * https://github.com/ko-build/ko/tree/main/pkg 90 | * https://github.com/lima-vm/lima/tree/master/pkg 91 | * https://github.com/clastix/capsule/tree/master/pkg 92 | * https://github.com/carvel-dev/ytt/tree/develop/pkg 93 | * https://github.com/clusternet/clusternet/tree/main/pkg 94 | * https://github.com/fluid-cloudnative/fluid/tree/master/pkg 95 | * https://github.com/inspektor-gadget/inspektor-gadget/tree/main/pkg 96 | * https://github.com/sustainable-computing-io/kepler/tree/main/pkg 97 | * https://github.com/GoogleContainerTools/kpt/tree/main/pkg 98 | * https://github.com/guacsec/guac/tree/main/pkg 99 | * https://github.com/kubeovn/kube-ovn/tree/master/pkg 100 | * https://github.com/kube-vip/kube-vip/tree/main/pkg 101 | * https://github.com/kubescape/kubescape/tree/master/pkg 102 | * https://github.com/kudobuilder/kudo/tree/main/pkg 103 | * https://github.com/kumahq/kuma/tree/master/pkg 104 | * https://github.com/kubereboot/kured/tree/main/pkg 105 | * https://github.com/nocalhost/nocalhost/tree/main/pkg 106 | * https://github.com/openelb/openelb/tree/master/pkg 107 | * https://github.com/openfga/openfga/tree/main/pkg 108 | * https://github.com/openyurtio/openyurt/tree/master/pkg 109 | * https://github.com/getporter/porter/tree/main/pkg 110 | * https://github.com/sealerio/sealer/tree/main/pkg 111 | * https://github.com/werf/werf/tree/main/pkg 112 | 113 | -------------------------------------------------------------------------------- /pkg/_your_public_lib_/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/pkg/_your_public_lib_/.keep -------------------------------------------------------------------------------- /scripts/README.md: -------------------------------------------------------------------------------- 1 | # `/scripts` 2 | 3 | Scripts to perform various build, install, analysis, etc operations. 4 | 5 | These scripts keep the root level Makefile small and simple. 6 | 7 | Examples: 8 | 9 | * https://github.com/kubernetes/helm/tree/master/scripts 10 | * https://github.com/cockroachdb/cockroach/tree/master/scripts 11 | * https://github.com/hashicorp/terraform/tree/master/scripts 12 | -------------------------------------------------------------------------------- /test/README.md: -------------------------------------------------------------------------------- 1 | # `/test` 2 | 3 | Additional external test apps and test data. Feel free to structure the `/test` directory anyway you want. For bigger projects it makes sense to have a data subdirectory. For example, you can have `/test/data` or `/test/testdata` if you need Go to ignore what's in that directory. Note that Go will also ignore directories or files that begin with "." or "_", so you have more flexibility in terms of how you name your test data directory. 4 | 5 | Examples: 6 | 7 | * https://github.com/openshift/origin/tree/master/test (test data is in the `/testdata` subdirectory) 8 | 9 | 10 | -------------------------------------------------------------------------------- /third_party/README.md: -------------------------------------------------------------------------------- 1 | # `/third_party` 2 | 3 | External helper tools, forked code and other 3rd party utilities (e.g., Swagger UI). 4 | -------------------------------------------------------------------------------- /tools/README.md: -------------------------------------------------------------------------------- 1 | # `/tools` 2 | 3 | Supporting tools for this project. Note that these tools can import code from the `/pkg` and `/internal` directories. 4 | 5 | Examples: 6 | 7 | * https://github.com/istio/istio/tree/master/tools 8 | * https://github.com/openshift/origin/tree/master/tools 9 | * https://github.com/dapr/dapr/tree/master/tools 10 | -------------------------------------------------------------------------------- /vendor/README.md: -------------------------------------------------------------------------------- 1 | # `/vendor` 2 | 3 | Application dependencies (managed manually or by your favorite dependency management tool or the built-in [`modules`](https://go.dev/wiki/Modules) feature). 4 | 5 | Don't commit your application dependencies if you are building a library. 6 | 7 | Note that since [`1.13`](https://golang.org/doc/go1.13#modules) Go also enabled the module proxy feature (using `https://proxy.golang.org` as their module proxy server by default). Read more about it [`here`](https://blog.golang.org/module-mirror-launch) to see if it fits all of your requirements and constraints. If it does, then you won't need the 'vendor' directory at all. 8 | -------------------------------------------------------------------------------- /web/README.md: -------------------------------------------------------------------------------- 1 | # `/web` 2 | 3 | Web application specific components: static web assets, server side templates and SPAs. 4 | -------------------------------------------------------------------------------- /web/app/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/web/app/.keep -------------------------------------------------------------------------------- /web/static/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/web/static/.keep -------------------------------------------------------------------------------- /web/template/.keep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/golang-standards/project-layout/aa203318eacf4e97c8e5b2505b15dafe3a760d6a/web/template/.keep -------------------------------------------------------------------------------- /website/README.md: -------------------------------------------------------------------------------- 1 | # `/website` 2 | 3 | This is the place to put your project's website data if you are not using GitHub pages. 4 | 5 | Examples: 6 | 7 | * https://github.com/hashicorp/vault/tree/master/website 8 | * https://github.com/perkeep/perkeep/tree/master/website 9 | --------------------------------------------------------------------------------