golang1.16內嵌靜態資源指南

今天是萬聖節，也是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