1 · 标准库 io#

io 包是 Go 里最基础的 I/O 抽象层，核心作用是把”读、写、关闭、定位”能力统一成一组通用接口。

io 主要定义”接口和组合方式”，不负责具体实现。

1.1 · 核心接口

// 读：读了n个byte到p里，p是缓冲区
// 看作数据源：从Reader读数据到p
// 最多读 len(p) 个字节，不保证读满
// 返回实际读到的字节数 n
//
// go doc io.Reader
type Reader interface {
	Read(p []byte) (n int, err error)
}

// 写：把p里面的数据，写出了n个byte
// 看作数据目标：把p的数据写到Writer
// 返回实际写出的字节数 n
// go doc io.Writer
type Writer interface {
	Write(p []byte) (n int, err error)
}

// 关闭
// go doc io.Closer
type Closer interface {
	Close() error
}

// 定位：设置读/写操作的当前位置偏移量
// 2nd 参数表示位置是开始/当前/末尾
// go doc io.Seeker
type Seeker interface {
	Seek(offset int64, whence int) (int64, error)
}

// Seek whence values.
const (
	SeekStart   = 0 // seek relative to the origin of the file
	SeekCurrent = 1 // seek relative to the current offset
	SeekEnd     = 2 // seek relative to the end
)

// !!! 以及：这四个基础能力可以按需组合成更具体的接口

1.1.1 · 变体(更强约束、特殊语义)

// 随机访问接口
type ReaderAt interface {
	ReadAt(p []byte, off int64) (n int, err error)
}
type WriterAt interface {
	WriteAt(p []byte, off int64) (n int, err error)
}

// 目标端主动从 r 读取数据到自己这里
type ReaderFrom interface {
	ReadFrom(r Reader) (n int64, err error)
}

// 源端主动把自己的数据写到 w
type WriterTo interface {
	WriteTo(w Writer) (n int64, err error)
}

1.2 · 适配器(实现)

// 返回一个新的 Writer，写一次，相当于同时写多个目标
// go doc io.MultiWriter
func MultiWriter(writers ...Writer) Writer

// 返回一个新的 Reader，按顺序读多个输入源
// go doc io.MultiReader
func MultiReader(readers ...Reader) Reader

// 返回一个新的 Reader，读取时同时把读到的数据写进 w
// go doc io.TeeReader
func TeeReader(r Reader, w Writer) Reader

// 返回一个新的 Reader，但最多只能读 n 字节
// go doc io.LimitReader
func LimitReader(r Reader, n int64) Reader

// 返回一个新的 ReadCloser，Close() 是空实现
// go doc io.NopCloser
func NopCloser(r Reader) ReadCloser

1.3 · 工具函数

// go doc io.ReadAll
func ReadAll(r Reader) ([]byte, error)

// 读入数据到buf，读满
func ReadFull(r Reader, buf []byte) (n int, err error)

// 读入数据到buf，读至少min个字节
func ReadAtLeast(r Reader, buf []byte, min int) (n int, err error)

// go doc io.WriteString
func WriteString(w Writer, s string) (n int, err error)

// go doc io.Copy
func Copy(dst Writer, src Reader) (written int64, err error)

// 只拷贝N个字节
func CopyN(dst Writer, src Reader, n int64) (written int64, err error)

// 缓存区caller提供
func CopyBuffer(dst Writer, src Reader, buf []byte) (written int64, err error)

// go doc io.Pipe
func Pipe() (*PipeReader, *PipeWriter)

1.4 · 错误、值

# 正常读到结尾
go doc io.EOF

# 本来还该有数据，但提前结束
go doc io.ErrUnexpectedEOF

# 写入不完整
go doc io.ErrShortWrite

# 缓冲区太小
go doc io.ErrShortBuffer

# 对已关闭的管道读写
go doc io.ErrClosedPipe

# 多次 Read 都没有进展
go doc io.ErrNoProgress

# 值：类“黑洞”，写进去的数据直接丢弃
# var Discard Writer = discard{}
go doc io.Discard