Organizing a Go module

原文：https://go.dev/doc/modules/layout

新的Go開發(fā)者經(jīng)常會提出一個問題：如何組織一個Go項目？這個問題主要指文件和文件夾布局方面。

本文的目標(biāo)是提供一些有助于回答這個問題的準(zhǔn)則。為了充分利用本文，請確保你熟悉Go模塊的基本概念，你可以閱讀下面兩個文檔：

• the tutorial : https://go.dev/doc/tutorial/create-module
• managing module source : https://go.dev/doc/modules/managing-source

Go項目可以包括包、命令行程序或者是這兩者的組合，本文按項目類型來組織。

Basic package

一個基本的Go包可以把所有代碼放在項目的根目錄中。該項目由單個包，即單個模塊組成。

對于最簡單的包，只需要一個Go文件（不包含test文件），項目結(jié)構(gòu)是：

project-root-directory/
  go.mod
  modname.go
  modname_test.go

包名與模塊名的最后一個路徑組件匹配，modname中的包聲明代碼如下：
（譯者注：實際上不同名也可以，但易用性很差，不建議這樣做，或者至少要在文檔中明確說明）

package modname
// ... package code here

如果這個目錄上傳到GitHub存儲庫github.com/someuser/modname，那么go.mod文件中的模塊行應(yīng)表述如下：

module github.com/someuser/modname

用戶若需要依賴這個包，可以按如下方法導(dǎo)入：

import "github.com/someuser/modname"

一個Go包可以被分隔為多個文件，所有文件處于同一目錄中，如：

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth.go
  auth_test.go
  hash.go
  hash_test.go

目錄中的所有文件都需要聲明包名modname。

Basic command

基本的可執(zhí)行程序（或命令行工具）是根據(jù)其復(fù)雜程度和代碼量大小來構(gòu)建的。

最簡單的程序由一個定義了main函數(shù)的Go文件組成。

更大的程序可以將代碼分隔到多個文件中，并且所有文件都聲明包名main，如：

project-root-directory/
  go.mod
  auth.go
  auth_test.go
  client.go
  main.go

這里的main.go文件包含main函數(shù)，但這只是一種慣例。“主”文件也可以被叫做modname.go（以匹配包名）或其他任何名字。

如果這個目錄上傳到GitHub存儲庫github.com/someuser/modname，那么go.mod文件中的模塊行影表述如下：

module github.com/someuser/modname

用戶若需要使用這個程序，可以按如下方法安裝：

$ go install github.com/someuser/modname@latest

Package or command with supporting packages

更大的包或命令行工具（command）受益于將一部分功能分隔到支援包中。
（譯者注：這段翻譯可讀性有點差，我個人覺得主要是原文表意就不太明確，主要想表達的應(yīng)該是更大的包或command基于可讀性和功能隔離等需求，應(yīng)該將部分功能分隔到supporting packages中）

起初，我們建議將這些包放入internal目錄中，這樣可以防止外部依賴或避免不需要的代碼暴露。由于外部程序不能導(dǎo)入我們internal目錄中的代碼，我們可以任意重構(gòu)或者改變代碼，而不會影響外部用戶。

這樣的包的項目結(jié)構(gòu)如下：

project-root-directory/
  internal/
    auth/
      auth.go
      auth_test.go
    hash/
      hash.go
      hash_test.go
  go.mod
  modname.go
  modname_test.go

modname.go文件聲明包名modname，auth.go文件聲明包名auth，依此類推。

modname.go可以按如下方法導(dǎo)入auth包：

import "github.com/someuser/modname/internal/auth"

使用internal目錄保存支援包的命令行工具的布局類似，區(qū)別僅為，根目錄中的文件（都）應(yīng)該聲明包名main。

Multiple packages

一個模塊可以由多個可導(dǎo)入的包組成，每個包都有自己的目錄，并可以分層構(gòu)建，如下：

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
    token/
      token.go
      token_test.go
  hash/
    hash.go
  internal/
    trace/
      trace.go

提醒一下，我們假設(shè)go.mod中的模塊行如下：

import "github.com/someuser/modname"

子包可以被其他用戶用如下方法導(dǎo)入：

import "github.com/someuser/modname/auth"
import "github.com/someuser/modname/auth/token"
import "github.com/someuser/modname/hash"

而放在internal/trace目錄中的trace包則不能被外部模塊導(dǎo)入。

建議盡可能的將包保存在internal目錄下。
（譯者注：這個說法原文并沒有給出明確的解釋，理由和是否遵循這一建議大家可以各自發(fā)揮）

Multiple commands

一個項目中的多個可執(zhí)行程序通常有不同的目錄，如下：

project-root-directory/
  go.mod
  internal/
    ... shared internal packages
  prog1/
    main.go
  prog2/
    main.go

在各自的目錄中，程序的Go文件聲明包名main。頂級的internal目錄可以存放多個程序共用的包。

用戶可以按如下方法安裝這些程序：

$ go install github.com/someuser/modname/prog1@latest
$ go install github.com/someuser/modname/prog2@latest

一個常見的約定是將同一個倉庫的命令行程序都放入cmd目錄。

在一個只由命令行程序構(gòu)成的項目中，這不是嚴(yán)格必須的。

但在由可導(dǎo)出包和命令行程序構(gòu)成的混合倉庫中，這種用法是非常有效的，接下來便會討論。

Packages and commands in the same repository

有時候一個倉庫既提供可導(dǎo)出包，也提供具有相關(guān)功能的可安裝命令行程序。如下：

project-root-directory/
  go.mod
  modname.go
  modname_test.go
  auth/
    auth.go
    auth_test.go
  internal/
    ... internal packages
  cmd/
    prog1/
      main.go
    prog2/
      main.go

假設(shè)這個模塊被命名為github.com/someuser/modname。

用戶可以按照下面的方法導(dǎo)入模塊，或者安裝命令：

Go文件中：

import "github.com/someuser/modname"
import "github.com/someuser/modname/auth"

命令行中：

$ go install github.com/someuser/modname/cmd/prog1@latest
$ go install github.com/someuser/modname/cmd/prog2@latest

Server project

Go是實現(xiàn)服務(wù)器的常用語言。

考慮到服務(wù)器的種類繁多，比如協(xié)議（REST、gRPC等）、部署、前端、容器化、腳本等等，這類項目的目錄結(jié)構(gòu)存在很大差異。

我們重點介紹其中Go語言編寫的項目部分。

由于服務(wù)器通常是一個（或多個）自包含的二進制文件，因此服務(wù)器程序通常不需要對外導(dǎo)出包，所以建議將提供服務(wù)器邏輯的Go模塊放入internal目錄。

另外，由于程序可以包含其他非Go文件，所以將所有Go命令行程序放在cmd目錄下是個好主意。

如下：

project-root-directory/
  go.mod
  internal/
    auth/
      ...
    metrics/
      ...
    model/
      ...
  cmd/
    api-server/
      main.go
    metrics-analyzer/
      main.go
    ...
  ... the project's other directories with non-Go code

考慮到服務(wù)器倉庫可能產(chǎn)生一些對外部程序也十分有用的包，最好的方法是將這些包剝離出來形成單獨的模塊。
（譯者注：這里并沒有詳細說明建議剝離出的包是當(dāng)前項目導(dǎo)出包還是拆分成單獨的項目，大家各自發(fā)揮）

譯者結(jié)語

前面的內(nèi)容基本就是原文的翻譯了。

簡單總結(jié)如下：

Go的包隔離層級為：目錄。同一個目錄下的Go文件都聲明為同一個包。

Go語言的包管理遵循下面的幾條原則：

• 簡便。最簡便的包和程序不需要復(fù)雜的布局。
• 私用。盡量使用internal目錄隔離不需要對外導(dǎo)出的功能。internal目錄約束在1.4版本中引入。
• 隔離。隔離保證復(fù)雜功能布局下的可讀性，如cmd目錄。
• 拆包。如果一個模塊的功能本身在一定程度上是完備的，可以考慮拆分。

以上就是Go模塊布局管理文檔翻譯理解的詳細內(nèi)容，更多關(guān)于Go模塊布局管理的資料請關(guān)注腳本之家其它相關(guān)文章！

最新評論