今天是萬聖節，也是golang1.16新特性凍結的日子。不得不說自從go2路線釋出之後golang新特性的迭代速度也飛速提升，1.16中有相當多的重要更新，包括io標準庫的重構，語言內建的靜態資源嵌入等。
本次將要介紹的是新的靜態資源嵌入功能，雖然之前已經有相關的提案，但實際的api和提案還有些出入，今天新特性凍結也就意味著1.16的api已經趨於穩定，是時候學習新知識了。
為什麼我們需要嵌入靜態資源
先問是不是，再問為什麼。
我們確實需要把靜態資源嵌入在程式裡，原因無外乎以下幾點：
- 部署程式更簡單。傳統部署要麼需要把靜態資源和編譯好的程式一起打包上傳，要麼使用docker和dockerfile自動化前者，心智負擔較重；
- 保證程式完整性。執行中發生靜態資源損壞或丟失往往會影響程式的正常執行；
- 可以自主控制程式需要的靜態資源。
最常見的，比如一個靜態網站的後端程式，本來需要把程式和它依賴的html模板，css，js，圖片一起上傳至生產伺服器，同時還要正確配置靜態資源在web伺服器中的路徑才能讓使用者正常訪問。現在我們把這些資源全部嵌入在程式中，部署時只需要部署一個二進位制檔案，配置也只需要針對這個程式本身進行，部署流程被大大簡化了。
另一個更常見的例子是Qt。Qt提供了qrc進行靜態資源的嵌入，將圖片，聲音等資源嵌入在程式中，Qt程式可以更方便地在各個平臺上進行分發安裝，同時還能提供較為一致的使用者體驗。
golang1.16前如何嵌入靜態資源
在1.16之前我們需要藉助工具來實現。這些工具都是藉助程式碼生成來完成資源嵌入的，我們拿使用的最多的_packr_舉例，專案連結在這裡：https://github.com/gobuffalo/packr。
首先我們建立一個專案：
mkdir pk && cd pk
go mod init my.mod/pk
go get -u github.com/gobuffalo/packr/v2/... # 安裝庫
go get -u github.com/gobuffalo/packr/v2/packr2 # 安裝資源打包工具
然後我們複製一個png圖片和一個錄屏軟體製造的巨型gif檔案進images資料夾，整個專案看起來如下：
然後是我們的程式碼：
package main
import (
"fmt"
"github.com/gobuffalo/packr/v2"
)
func main() {
box := packr.New("myBox", "./images") // 建立內嵌資源
data, err := box.Find("screenrecord.gif") // 查詢內嵌資源
if err != nil {
log.Fatal(err)
}
fmt.Println(len(data))
}
想要完成資源嵌入，我們需要執行packr2命令，之後直接執行go build即可，順利執行後專案會是這樣：
packr的思路就是將資原始檔編碼成合法的golang原始檔，然後利用golang把這些程式碼化的資源編譯程式序裡。這是比較主流的嵌入資源實現方案。
從上面的例子裡我們可以看到這類方法有不少缺點：
- 需要安裝額外的工具
- 會生成超大體積的生產程式碼（是靜態資源的兩倍大，因為需要對二進位制資料進行一定的編碼才能正常儲存在go原始檔裡）
- 編譯完成的程式體積也是資原始檔的兩倍多
- 程式載入時間長，上圖中程式執行花費了6秒，我們程式是存放在ssd上的，慢是因為庫需要對編碼的資源進行處理
前兩點通過語言內建工具或機制就可以得到解決，而對於後兩點，靜態資源本身在計算機上也是二進位制儲存的，重複編碼解碼浪費時間，如果可以直接把資源放程式序裡該多好。同時告別了生成程式碼還可以讓我們的專案結構更清晰。
所以，golang1.16的官方內建版靜態資源嵌入方案誕生了。
準備工作
golang的embed需要在１.16及之後的版本才能執行，不過我們已經可以自行編譯嚐鮮了(需要電腦已經安裝了穩定版本的golang)：
mkdir -p ~/go-next && cd ~/go-next
git clone https://github.com/golang/go
cd go/src && bash ./make.bash
export GOROOT=~/go-next/go
alias newgo=${GOROOT}/bin/go
驗證一下安裝：
$ newgo version
go version devel +256d729c0b Fri Oct 30 15:26:28 2020 +0000 linux/amd64
至此準備工作就結束了。
如何匹配靜態資源
想要嵌入靜態資源，首先我們得利用embed這個新的標準庫。在宣告靜態資源的檔案裡我們需要引入這個庫。
對於我們想要嵌入程式序的資源，需要使用//go:embed指令進行宣告，注意//之後不能有空格。具體格式如下：
//go:embed pattern
// pattern是path.Match所支援的路徑萬用字元
具體的萬用字元如下，如果你是在linux系統上，可以用man 7 glob檢視更詳細的教程：
| 萬用字元 | 釋義 |
|---|---|
| ? | 代表任意一個字元（不包括半形中括號） |
| * | 代表0至多個任意字元組成的字串（不包括半形中括號） |
| [...]和[!...] | 代表任意一個匹配方括號裡字元的字元，!表示任意不匹配方括號中字元的字元 |
| [a-z]、[0-9] | 代表匹配a-z任意一個字元的字元或是0-9中的任意一個數字 |
| ** | 部分系統支援，*不能跨目錄匹配，**可以，不過目前個golang中和*是同義詞 |
我們可以在embed的pattern裡自由組合這些萬用字元。
golang的embed預設的根目錄從module的目錄開始，路徑開頭不可以帶/，不管windows還是其他系統路徑分割副一律使用/。如果匹配到的是目錄，那麼目錄下的所有檔案都會被嵌入（有部分資料夾和檔案會被排除，後面詳細介紹），如果其中包含有子目錄，則對子目錄進行遞迴嵌入。
下面舉一些例子，假設我們的專案在/tmp/proj：
//go:embed images
這是匹配所有位於/tmp/proj/images及其子目錄中的檔案
//go:embed images/jpg/a.jpg
匹配/tmp/proj/images/jpg/a.jpg這一個檔案
//go:embed a.txt
匹配/tmp/proj/a.txt
//go:embed images/jpg/*.jpg
匹配/tmp/proj/images/jpg下所有.jpg檔案
//go:embed images/jpg/a?.jpg
匹配/tmp/proj/images/jpg下的a1.jpg a2.jpg ab.jpg等
//go:embed images/??g/*.*
匹配/tmp/proj/images下的jpg和png資料夾裡的所有有字尾名的檔案，例如png/123.png jpg/a.jpeg
//go:embed *
直接匹配整個/tmp/proj
//go:embed a.txt
//go:embed *.png *.jpg
//go:embed aa.jpg
可以指定多個//go:embed指令行，之間不能有空行，也可以用空格在一行裡寫上對個模式匹配，表示匹配所有這些檔案，相當於並集操作
可以包含重複的檔案或是模式串，golang對於相同的檔案只會嵌入一次，很智慧
另外，萬用字元的預設目錄和原始檔所在的目錄是同一目錄，所以我們只能匹配同目錄下的檔案或目錄，不能匹配到父目錄。舉個例子：
.
├── code
│ └── main.go
├── go.mod
├── imgs
│ ├── jpg
│ │ ├── a.jpg
│ │ ├── b.jpg
│ │ └── c.jpg
│ ├── png
│ │ ├── a.png
│ │ ├── b.png
│ │ └── c.png
│ └── screenrecord.gif
└── texts
├── en.txt
├── jp.txt
└── zh.txt
5 directories, 12 files
考慮如上的目錄結構。
在這裡的main.go可見的資源只有code目錄及其子目錄裡的檔案，而imgs和texts裡的檔案是無法匹配到的。
如何使用嵌入的靜態資源
在瞭解瞭如何指定需要的靜態資源之後，我們該學習如何使用它們了，還記得我們前面提到的embed標準庫嗎？
對於一個完整的嵌入資源，程式碼中的宣告是這樣的：
//go:embed images
var imgs embed.FS
//go:embed a.txt
var txt []byte
//go:embed b.txt
var txt2 string
一共有三種資料格式可選：
| 資料型別 | 說明 |
|---|---|
| []byte | 表示資料儲存為二進位制格式，如果只使用[]byte和string需要以import (_ "embed")的形式引入embed標準庫 |
| string | 表示資料被編碼成utf8編碼的字串，因此不要用這個格式嵌入二進位制檔案比如圖片，引入embed的規則同[]byte |
| embed.FS | 表示儲存多個檔案和目錄的結構，[]byte和string只能儲存單個檔案 |
下面看個具體例子，目錄結構如下：
$ tree -sh .
.
├── [ 487] embed_fs.go
├── [ 235] embed_img.go
├── [ 187] embed_img2.go
├── [ 513] embed_img_fs.go
├── [ 211] embed_text.go
├── [ 660] embed_text_fs.go
├── [ 30] go.mod
├── [ 0] imgs
│ ├── [ 0] jpg
│ │ ├── [606K] a.jpg
│ │ ├── [976K] b.jpg
│ │ └── [342K] c.jpg
│ ├── [ 0] png
│ │ ├── [4.7M] a.png
│ │ ├── [1.4M] b.png
│ │ └── [1.7M] c.png
│ └── [ 77M] screenrecord.gif
├── [ 98K] macbeth.txt
└── [ 0] texts
├── [ 12] en.txt
├── [ 25] jp.txt
└── [ 16] zh.txt
4 directories, 18 files
目錄包含了一些靜態圖片，一個錄屏檔案，一個莎士比亞的麥克白劇本。當然還有我們的測試程式碼。
處理單個檔案
我們先來看用[]byte和string嵌入單個檔案的例子：
package main
import (
"fmt"
_ "embed"
)
//go:embed macbeth.txt
var macbeth string
func main(){
fmt.Println(len(macbeth)) // 麥克白的總字元數
//go:embed texts/en.txt
var hello string
fmt.Println(hello) // Output: Hello, world
}
如你所見，嵌入內容宣告可以放進任意作用域，但變數一定要求用var宣告。直接使用newgo run embed_txt.go或go build embed_txt.go && ./embed_txt即可完成編譯執行，過程中不會生成任何中間程式碼。另外變數是否是公開的（首字母是否大小寫）並不會對資源的嵌入產生影響。
再來看看二進位制檔案的例子，embed_img.go如下所示：
package main
import (
"fmt"
_ "embed"
)
//go:embed imgs/screenrecord.gif
var gif []byte
//go:embed imgs/png/a.png
var png []byte
func main() {
fmt.Println("gif size:", len(gif)) // gif size: 81100466
fmt.Println("png size:", len(png)) // png size: 4958264
}
如果編譯執行這個程式，你會發現二進位制檔案的大小是89M（不同系統會有差異），比我們之前使用packr建立的要小了許多。
處理多個檔案和目錄
下面就要進入本文的重頭戲了，新的標準庫embed的使用。
如果你newgo doc embed的話會發現整個標準庫裡只有一個FS型別（之前按提案被命名為Files，後來考慮到用目錄結構組織多個資源更類似新的io/fs.FS介面，故改名），而我們對靜態資源的操作也全都依賴這個FS。下面接著用例子說明：
package main
import (
"fmt"
"embed"
)
//go:embed texts
var dir embed.FS
// 兩者沒什麼區別
//go:embed texts/*
var files embed.FS
func main(){
zh, err := files.ReadFile("texts/zh.txt")
if err != nil {
fmt.Println("read zh.txt error:", err)
} else {
fmt.Println("zh.txt:", string(zh))
}
jp, err := dir.ReadFile("jp.txt")
if err != nil {
fmt.Println("read jp.txt error:", err)
} else {
fmt.Println("jp.txt:", string(jp))
}
jp, err = dir.ReadFile("texts/jp.txt")
if err != nil {
fmt.Println("read jp.txt error:", err)
} else {
fmt.Println("jp.txt:", string(jp))
}
}
執行結果：
zh.txt: 你好，世界
read jp.txt error: open jp.txt: file does not exist
jp.txt: こんにちは、世界
我們想讀取單個檔案需要用ReadFile方法，它接受一個path字串做引數，從中查詢對應的檔案然後返回([]byte, error)。
要注意的是檔案路徑必須要明確寫出自己的父級目錄，否則會報錯，因為嵌入資源是按它儲存路徑相同的結構儲存的，和萬用字元怎麼指定無關。
Open是和ReadFile類似的方法，只不過返回了一個fs.File型別的io.Reader，因此這裡就不再贅述，需要使用Open還是ReadFile可以由開發者根據自身需求決定。
embed.FS自身是隻讀的，所以我們不能在執行時新增或刪除嵌入的檔案，fs.File也是隻讀的，所以我們不能修改嵌入資源的內容。
如果只是提供了一個查詢讀取資源的能力，那未免小看了embed。在golang1.16裡任意實現了io/fs.FS介面的型別都可以表現的像是真實存在於檔案系統中的目錄一樣，哪怕它其實是在記憶體裡的類map資料結構。因此我們也可以像遍歷目錄一樣去處理embed.FS:
package main
import (
"embed"
"fmt"
)
// 更推薦直接用imgs去匹配
//go:embed imgs/**
var dir embed.FS
// 遍歷當前目錄，有興趣你可以改成遞迴版本的
func printDir(name string) {
// 返回[]fs.DirEntry
entries, err := dir.ReadDir(name)
if err != nil {
panic(err)
}
fmt.Println("dir:", name)
for _, entry := range entries {
// fs.DirEntry的Info介面會返回fs.FileInfo，這東西被從os移動到了io/fs，介面本身沒有變化
info, _ := entry.Info()
fmt.Println("file name:", entry.Name(), "\tisDir:", entry.IsDir(), "\tsize:", info.Size())
}
fmt.Println()
}
func main() {
printDir("imgs")
printDir("imgs/jpg")
printDir("imgs/png")
}
執行結果：
dir: imgs
file name: jpg isDir: true size: 0
file name: png isDir: true size: 0
file name: screenrecord.gif isDir: false size: 81100466
dir: imgs/jpg
file name: a.jpg isDir: false size: 620419
file name: b.jpg isDir: false size: 999162
file name: c.jpg isDir: false size: 349725
dir: imgs/png
file name: a.png isDir: false size: 4958264
file name: b.png isDir: false size: 1498303
file name: c.png isDir: false size: 1751934
唯一和真實的目錄不一樣的地方是目錄檔案的大小，在ext4等檔案系統上目錄會儲存子專案的元資訊，所以大小通常不為0。
如果想要內嵌整個module，則在引用的時候需要使用"."這個名字，但除了單獨使用之外路徑裡不可以包含..或者.，換而言之，embed.FS不支援相對路徑，把上面的程式碼稍加修改：
package main
import (
"fmt"
"embed"
)
//go:embed *
var dir embed.FS
func main() {
printDir(".")
//printDir("./texts/../imgs") panic: open ./texts/../imgs: file does not exist
}
程式輸出：
dir: .
file name: embed_fs.go isDir: false size: 484
file name: embed_img.go isDir: false size: 235
file name: embed_img2.go isDir: false size: 187
file name: embed_img_fs.go isDir: false size: 692
file name: embed_text.go isDir: false size: 211
file name: embed_text_fs.go isDir: false size: 603
file name: go.mod isDir: false size: 30
file name: imgs isDir: true size: 0
file name: macbeth.txt isDir: false size: 100095
file name: texts isDir: true size: 0
因為使用了錯誤的檔名或路徑會在執行時panic，所以要格外小心。（當然//go:embed是在編譯時檢查的，而且同樣不支援相對路徑，同時也不支援超出了module目錄的任何路徑，比如go module在/tmp/proj，我們指定了/tmp/proj2）
你也可以用embed.FS處理單個檔案，但我個人認為單個檔案就沒必要再多包裝一層了。
由於是golang內建的支援，所以上述的程式碼無需呼叫任何第三方工具，也沒有煩人的生成程式碼，不得不說golang對工程控制的把握上還是相當可靠的。
一些陷阱
方便的功能背後往往也會有陷阱相隨，golang的內建靜態資源嵌入也不例外。
資源是否應該被壓縮
靜態資源嵌入的提案被接受後爭論最多的就是是否應該對資源採取壓縮，壓縮後的資源更緊湊，不會浪費太多儲存空間，特別是一些大文字檔案。同時更大的程式執行載入時間越長，cpu快取利用率可能會變低。
而反對意見認為壓縮和執行時的解壓一個浪費編譯的時間一個浪費執行時的效率，在使用者沒有明確指定的情況下使用者需要為自己不需要的功能花費代價。
目前官方採用的實現是不壓縮嵌入資源，並預計在後續版本加入控制是否啟用壓縮的選項。
而真正的陷阱是接下來的內容。
潛在的嵌入資源副本
前文中提到過重複的匹配和相同的檔案golang會自動只保留一份在變數中。沒錯，然而這是針對同一個變數的多個匹配說的，如果考慮下面的程式碼：
package main
import (
_ "embed"
"fmt"
)
//go:embed imgs/screenrecord.gif
var b []byte
//go:embed imgs/screenrecord.gif
var a []byte
func main() {
fmt.Printf("a: %p %d\n", &a, len(a))
fmt.Printf("b: %p %d\n", &b, len(b))
}
猜猜輸出是什麼：
a: 0x9ff5a50 81100466
b: 0x9ff5a70 81100466
a和b的地址不一樣！那也沒關係，我們知道slice是引用型別，底層說不定引用了同一個陣列呢？那再來看看檔案大小：
tree -sh .
.
├── [ 484] embed_fs.go
├── [ 230] embed_img2.go
├── [157M] embed_img2
├── ...
├── [ 0] imgs
│ ├ ...
│ └── [ 77M] screenrecord.gif
├── ...
4 directories, 19 files
程式是資源的兩倍大，這差不多就可以說明問題了，資源被複制了一份。不過從程式碼的角度來考慮，a和b是兩個不同的物件，所以引用不同的資料也說的過去，但在開發的時候一定要小心，不要讓兩個資源集合出現交集，否則就要付出高昂的儲存空間代價了。
過大的可執行檔案帶來的效能影響
程式檔案過大會導致初次執行載入時間的增長，這是眾所周知的。
然而過大的程式檔案還可能會降低執行效率。程式需要利用現代的cpu快速快取體系來提高效能，而更大的二進位制檔案意味著對於反覆執行的熱點功能cpu的快速快取很可能會面臨更多的快取失效，因為快取的大小有限，需要兩次三次的讀取和重新整理才能執行完一個熱點程式碼片段。這就是為什麼幾乎所有的編譯器都會自行指定函式是否會被內聯化而不是把這種控制權利移交給使用者的原因。
然而嵌入靜態檔案之後究竟會對效能有多少影響呢？目前缺乏實驗證據，所以沒有定論。
通過修改二進位制檔案的一部分格式也可以讓程式碼部分和資源部分分離從而程式碼在cpu看來更加緊湊，當然這麼做會不會嚴重破壞相容，是否真的有用也未可知。
會被忽略的目錄
前面說過，embed會遞迴處理目錄，出來以下的幾個：
- .git
- .svn
- .bzr
- .hg
這些都是版本控制工具的目錄，資源裡理應不包含他們，因此是被忽略的。會被忽略的目錄列在src/cmd/go/internal/load/pkg.go的isBadEmbedName函式裡。
.idea不在此列，小心：P
總結
使用golang1.16你可以更輕鬆地建立嵌入資源，不過在享受便利的同時也要注意利弊取捨，使用docker管理資源和部署也不失為一種好方法。
想要進一步測試也可以在這裡下載本文的程式碼：https://github.com/apocelipes/embed-example
參考
https://go.googlesource.com/proposal/+/master/design/draft-embed.md
https://github.com/golang/go/commit/25d28ec55aded46e0be9c2298f24287d296a9e47
大神的embed demo： https://github.com/mattn/go-embed-example