golang1.16内嵌静态资源指南

时间 2020-11-01

标签 css html linux git github golang web docker windows 后端栏目 Go 繁體版

原文原文链接

今天是万圣节，也是golang1.16新特性冻结的日子。不得不说自从go2路线发布以后golang新特性的迭代速度也飞速提高，1.16中有至关多的重要更新，包括io标准库的重构，语言内置的静态资源嵌入等。css

本次将要介绍的是新的静态资源嵌入功能，虽然以前已经有相关的提案，但实际的api和提案还有些出入，今天新特性冻结也就意味着1.16的api已经趋于稳定，是时候学习新知识了。html

为何咱们须要嵌入静态资源

先问是否是，再问为何。linux

咱们确实须要把静态资源嵌入在程序里，缘由无外乎如下几点：git

部署程序更简单。传统部署要么须要把静态资源和编译好的程序一块儿打包上传，要么使用docker和dockerfile自动化前者，心智负担较重；
保证程序完整性。运行中发生静态资源损坏或丢失每每会影响程序的正常运行；
能够自主控制程序须要的静态资源。

最多见的，好比一个静态网站的后端程序，原本须要把程序和它依赖的html模板，css，js，图片一块儿上传至生产服务器，同时还要正确配置静态资源在web服务器中的路径才能让用户正常访问。如今咱们把这些资源所有嵌入在程序中，部署时只须要部署一个二进制文件，配置也只须要针对这个程序自己进行，部署流程被大大简化了。github

另外一个更常见的例子是Qt。Qt提供了qrc进行静态资源的嵌入，将图片，声音等资源嵌入在程序中，Qt程序能够更方便地在各个平台上进行分发安装，同时还能提供较为一致的用户体验。golang

golang1.16前如何嵌入静态资源

在1.16以前咱们须要借助工具来实现。这些工具都是借助代码生成来完成资源嵌入的，咱们拿使用的最多的_packr_举例，项目连接在这里：https://github.com/gobuffalo/packr。web

首先咱们建立一个项目：docker

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文件夹，整个项目看起来以下：windows

而后是咱们的代码：后端

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