package gzip · Go 标准库中文参考

# package gzip `import "compress/gzip"` gzip包实现了gzip格式压缩文件的读写，参见[RFC 1952](http://tools.ietf.org/html/rfc1952)。 ## Index * [Constants](#pkg-constants) * [Variables](#pkg-variables) * [type Header](#Header) * [type Reader](#Reader) * [func NewReader(r io.Reader) (\*Reader, error)](#NewReader) * [func (z \*Reader) Reset(r io.Reader) error](#Reader.Reset) * [func (z \*Reader) Read(p []byte) (n int, err error)](#Reader.Read) * [func (z \*Reader) Close() error](#Reader.Close) * [type Writer](#Writer) * [func NewWriter(w io.Writer) \*Writer](#NewWriter) * [func NewWriterLevel(w io.Writer, level int) (\*Writer, error)](#NewWriterLevel) * [func (z \*Writer) Reset(w io.Writer)](#Writer.Reset) * [func (z \*Writer) Write(p []byte) (int, error)](#Writer.Write) * [func (z \*Writer) Flush() error](#Writer.Flush) * [func (z \*Writer) Close() error](#Writer.Close) ## Constants ``` const ( NoCompression = flate.NoCompression BestSpeed = flate.BestSpeed BestCompression = flate.BestCompression DefaultCompression = flate.DefaultCompression ) ``` 这些常量都是拷贝自flate包，因此导入"compress/gzip"后，就不必再导入"compress/flate"了。 ## Variables ``` var ( // 当读取的gzip数据的校验和错误时，会返回ErrChecksum ErrChecksum = errors.New("gzip: invalid checksum") // 当读取的gzip数据的头域错误时，会返回ErrHeader ErrHeader = errors.New("gzip: invalid header") ) ``` ## type [Header](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L46 "View Source") ``` type Header struct { Comment string // 注释 Extra []byte // 额外数据 ModTime time.Time // 修改时间 Name string // 文件名 OS byte // 操作系统类型 } ``` gzip文件保存一个头域，提供关于被压缩的文件的一些元数据。该头域作为Writer和Reader类型的一个可导出字段，可以提供给调用者访问。 ## type [Reader](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L68 "View Source") ``` type Reader struct { Header // 内含隐藏或非导出字段 } ``` Reader类型满足io.Reader接口，可以从gzip格式压缩文件读取并解压数据。一般，一个gzip文件可以是多个gzip文件的串联，每一个都有自己的头域。从Reader读取数据会返回串联的每个文件的解压数据，但只有第一个文件的头域被记录在Reader的Header字段里。 gzip文件会保存未压缩数据的长度与校验和。当读取到未压缩数据的结尾时，如果数据的长度或者校验和不正确，Reader会返回ErrCheckSum。因此，调用者应该将Read方法返回的数据视为暂定的，直到他们在数据结尾获得了一个io.EOF。 ### func [NewReader](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L82 "View Source") ``` func NewReader(r io.Reader) (*Reader, error) ``` NewReader返回一个从r读取并解压数据的\*Reader。其实现会缓冲输入流的数据，并可能从r中读取比需要的更多的数据。调用者有责任在读取完毕后调用返回值的Close方法。 ### func (\*Reader) [Reset](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L95 "View Source") ``` func (z *Reader) Reset(r io.Reader) error ``` Reset将z重置，丢弃当前的读取状态，并将下层读取目标设为r。效果上等价于将z设为使用r重新调用NewReader返回的Reader。这让我们可以重用z而不是再申请一个新的。（因此效率更高） ### func (\*Reader) [Read](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L214 "View Source") ``` func (z *Reader) Read(p []byte) (n int, err error) ``` ### func (\*Reader) [Close](https://github.com/golang/go/blob/master/src/compress/gzip/gunzip.go#L255 "View Source") ``` func (z *Reader) Close() error ``` 调用Close会关闭z，但不会关闭下层io.Reader接口。 ## type [Writer](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L27 "View Source") ``` type Writer struct { Header // 内含隐藏或非导出字段 } ``` Writer满足io.WriteCloser接口。它会将提供给它的数据压缩后写入下层io.Writer接口。 ### func [NewWriter](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L51 "View Source") ``` func NewWriter(w io.Writer) *Writer ``` NewWriter创建并返回一个Writer。写入返回值的数据都会在压缩后写入w。调用者有责任在结束写入后调用返回值的Close方法。因为写入的数据可能保存在缓冲中没有刷新入下层。如要设定Writer.Header字段，调用者必须在第一次调用Write方法或者Close方法之前设置。Header字段的Comment和Name字段是go的utf-8字符串，但下层格式要求为NUL中止的ISO 8859-1 (Latin-1)序列。如果这两个字段的字符串包含NUL或非Latin-1字符，将导致Write方法返回错误。 ### func [NewWriterLevel](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L62 "View Source") ``` func NewWriterLevel(w io.Writer, level int) (*Writer, error) ``` NewWriterLevel类似NewWriter但指定了压缩水平而不是采用默认的DefaultCompression。参数level可以是DefaultCompression、NoCompression或BestSpeed与BestCompression之间包括二者的任何整数。如果level合法，返回的错误值为nil。 ### func (\*Writer) [Reset](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L97 "View Source") ``` func (z *Writer) Reset(w io.Writer) ``` Reset将z重置，丢弃当前的写入状态，并将下层输出目标设为dst。效果上等价于将w设为使用dst和w的压缩水平重新调用NewWriterLevel返回的\*Writer。这让我们可以重用z而不是再申请一个新的。（因此效率更高） ### func (\*Writer) [Write](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L161 "View Source") ``` func (z *Writer) Write(p []byte) (int, error) ``` Write将p压缩后写入下层io.Writer接口。压缩后的数据不一定会立刻刷新，除非Writer被关闭或者显式的刷新。 ### func (\*Writer) [Flush](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L231 "View Source") ``` func (z *Writer) Flush() error ``` Flush将缓冲中的压缩数据刷新到下层io.Writer接口中。本方法主要用在传输压缩数据的网络连接中，以保证远端的接收者可以获得足够的数据来重构数据报。Flush会阻塞直到所有缓冲中的数据都写入下层io.Writer接口后才返回。如果下层的io.Writetr接口返回一个错误，Flush也会返回该错误。在zlib包的术语中，Flush方法等价于Z_SYNC_FLUSH。 ### func (\*Writer) [Close](https://github.com/golang/go/blob/master/src/compress/gzip/gzip.go#L250 "View Source") ``` func (z *Writer) Close() error ``` 调用Close会关闭z，但不会关闭下层io.Writer接口。