govips 手写 API、vipsgen 生成 API 与惯用模式

govips v2.19.0 通过两层 API 封装 libvips：精心维护的手写函数负责 I/O、导出、流式处理和复杂工作流，自动生成的类型安全语言绑定（binding）覆盖 193+ 个像素级操作。本页解释两者的关系，涵盖 v2.18.0 以来的重要变化（pipeline 包移除、最低 libvips 版本提升至 8.14、OpenImageRefs 泄漏检测），以及 v2.19.0 新增的流式 I/O（LoadImageFromReader / SaveToWriter / TranscodeStream）和生产环境生命周期规则。

两层 API

手写函数（Hand-written）

这些函数位于主包中，提供生命周期管理、文件/缓冲区/流 I/O、编解码，以及 GObject 内省代码生成器无法覆盖的便利封装：

类别	关键函数
生命周期	`Startup(nil)`（必须检查错误）、`Shutdown()`、`OpenImageRefs()`、`AssertNoLeaks()`
输入	`NewImageFromFile`、`NewImageFromBuffer`、`NewThumbnailFromFile`、`LoadImageFromReader`、`NewImageFromMemory`
几何	`Resize`、`ExtractArea`、`Similarity`、`Flip`、`Rotate`
颜色	`Modulate`（LCH 色彩空间）
Alpha	`Flatten`、`HasAlpha`、`Bands`
导出	`ExportWebp`、`ExportPng`、`ExportJpeg`、`SaveToWriter`（及其格式特定变体）
流式处理	`TranscodeStream`、`SetPipeReadLimit`、`SetStreamDiscThreshold`
取消	`SetKill`

每个程序必须在任何操作之前调用 vips.Startup(nil) 并检查错误，之后 defer vips.Shutdown()。每个 *vips.ImageRef 使用完毕必须关闭：

if err := vips.Startup(nil); err != nil {
    return fmt.Errorf("start libvips: %w", err)
}
defer vips.Shutdown()

image, err := vips.NewImageFromFile("input.jpg")
if err != nil {
    return err
}
defer image.Close()

生成操作（Generated Operations）

govips 的代码生成器在构建期读取 libvips GObject 内省数据，生成底层封装代码。其中的 vipsGen* 是包内私有实现；面向使用者的 ImageRef 方法和部分导出函数再对这些实现做类型安全的封装。截至 v2.19.0，覆盖了 193+ 个操作，分布在九个类别：

arithmetic（算术）、colour（颜色）、conversion（转换）、convolution（卷积）、create（创建）、
freqfilt（频域滤波）、histogram（直方图）、morphology（形态学）、resample（重采样）

应用代码调用公开的 ImageRef 方法。vipsGen* 留在 govips 内部，不作为业务代码直接调用的一层。代码生成器只在 govips 自身开发维护时运行。

流式 I/O（v2.19.0 新增）

govips v2.19.0 引入了完整的 io.Reader / io.Writer 流式支持：

LoadImageFromReader(r io.Reader, params *ImportParams)：从 Reader 创建 ImageRef。不传 AccessSequential 时，返回前会实体化（materialise，即完整解码并缓冲到内存或临时文件）；只有显式设置顺序访问才把像素读取推迟到消费阶段。
SaveToWriter(w io.Writer, format ImageType, params *ExportParams)：把编码块写入 Writer。也提供 SaveToWriterJpeg、SaveToWriterWebp 等变体。
TranscodeStream(r io.Reader, w io.Writer, opts *TranscodeOptions)：把读取、可选自动旋转和写出封装在一次调用里。它目前不接收 context.Context。
SetKill(true)：从另一个 goroutine 请求停止当前求值。调用结束后应把标志设回 false。在 v2.19.0 上，导出前设置 kill 会使该次导出返回错误。

两种解码策略：

顺序快速路径：显式指定 AccessSequential 且后续操作不需要随机读取时，像素在消费阶段才从 Reader 读出。内存仍受编解码器和行缓冲缓存影响，不能视作与图像尺寸无关的固定常量上限。
实体化路径：默认导入，或后续需要随机访问时，解码结果先进入内存或临时文件。

out, err := os.Create("output.jpg")
if err != nil {
    return err
}
defer out.Close()

image, err := vips.LoadImageFromReader(os.Stdin, nil)
if err != nil {
    return err
}
defer image.Close()

if err := image.AutoRotate(); err != nil {
    return err
}
return image.SaveToWriter(out, vips.ImageTypeJPEG, &vips.ExportParams{Quality: 85})

生产环境生命周期规则

每进程调用一次 Startup，必须检查错误。 初始化 libvips 内部状态。v2.18.0+ 的 Startup 可能返回错误。
Shutdown 一次，务必 defer。 释放全局 libvips 资源。遗漏可能导致资源未释放。
每个 ImageRef 都要 Close。 每次载入操作都会分配 libvips 原生内存。完成后应 defer image.Close() 或显式关闭。
v2.18.0 起可用 OpenImageRefs() / AssertNoLeaks(t)。 在开发与测试阶段追踪未关闭的 ImageRef。
严禁在关闭后继续使用图片。 libvips 可能崩溃或返回损坏数据，在 Go 中表现为 panic 或静默错误。

func process(inputPath string) error {
    image, err := vips.NewImageFromFile(inputPath)
    if err != nil {
        return err
    }
    defer image.Close()

    // 在此处进行操作
    return nil
}

v2.18.0 破坏性变化

pipeline 包已移除。 之前只是约 40 种操作的薄封装，现在直接使用 ImageRef 方法即可。
最低 libvips 版本从 8.10 提升至 8.14。
ImageRef 拆分为 8 个关注点文件，公共 API 表面保持不变。
startupIfNeeded 不再 panic，改为返回错误。

内存与性能说明

libvips 使用 GLib 进行内存分配，在高并发下可能产生分配器碎片。两种方式有助于缓解：

MALLOC_ARENA_MAX=2：减少 GLib malloc arena 数量，建议优先尝试。
Jemalloc：替换系统分配器，构建时添加 CGO_LDFLAGS="-ljemalloc"。

两者都不是万能方案——请在自己的工作负载上实际测量后再决定是否采用。

不需要关心的内部细节

vipsgen 不是第五个入口，也不是独立的语言绑定，而是 govips 内部的代码生成器。
vipsGen* 不是应用要调用的 API。公开入口是 ImageRef 方法；生成函数是这些方法的内部实现。
导入路径是 github.com/davidbyttow/govips/v2/vips。手写封装和生成操作共用 *vips.ImageRef，业务代码只需调用公开方法。

已验证版本

govips v2.19.0，libvips 8.17.3。复核日期 2026-10-12。SetKill 的失败路径已在该版本上实际执行验证。