Golang 数据扫描插件库 scan 使用指南

scan 是一个轻量级的 Go 语言库，用于将数据库查询结果直接扫描到结构体、切片或基本类型中，简化了数据库操作的数据映射过程。

安装

go get github.com/blockloop/scan

基本用法

1. 扫描到结构体

package main

import (
	"database/sql"
	"fmt"
	"github.com/blockloop/scan"
	_ "github.com/mattn/go-sqlite3"
)

type User struct {
	ID   int    `db:"id"`
	Name string `db:"name"`
	Age  int    `db:"age"`
}

func main() {
	db, err := sql.Open("sqlite3", ":memory:")
	if err != nil {
		panic(err)
	}
	defer db.Close()

	// 创建表
	_, err = db.Exec(`
		CREATE TABLE users (
			id INTEGER PRIMARY KEY,
			name TEXT,
			age INTEGER
		);
		INSERT INTO users (name, age) VALUES ('Alice', 25);
		INSERT INTO users (name, age) VALUES ('Bob', 30);
	`)
	if err != nil {
		panic(err)
	}

	// 查询并扫描到结构体
	rows, err := db.Query("SELECT * FROM users WHERE id = ?", 1)
	if err != nil {
		panic(err)
	}
	defer rows.Close()

	var user User
	if err := scan.Row(&user, rows); err != nil {
		panic(err)
	}

	fmt.Printf("%+v\n", user) // 输出: {ID:1 Name:Alice Age:25}
}

2. 扫描到切片

// 查询所有用户并扫描到切片
rows, err := db.Query("SELECT * FROM users")
if err != nil {
	panic(err)
}
defer rows.Close()

var users []User
if err := scan.Rows(&users, rows); err != nil {
	panic(err)
}

fmt.Printf("%+v\n", users) 
// 输出: [{ID:1 Name:Alice Age:25} {ID:2 Name:Bob Age:30}]

3. 扫描到基本类型

// 扫描单个值
rows, err := db.Query("SELECT COUNT(*) FROM users")
if err != nil {
	panic(err)
}
defer rows.Close()

var count int
if err := scan.Row(&count, rows); err != nil {
	panic(err)
}

fmt.Println("Total users:", count) // 输出: Total users: 2

高级特性

1. 自定义列名映射

默认情况下，scan 使用 db 标签或字段名的小写形式作为列名映射。你也可以自定义映射函数：

scan.SetMapper(func(s string) string {
	// 自定义映射逻辑
	return strings.ToUpper(s)
})

2. 处理 NULL 值

type UserWithNullable struct {
	ID     int            `db:"id"`
	Name   string         `db:"name"`
	Age    sql.NullInt64  `db:"age"`  // 可空整数
	Email  sql.NullString `db:"email"` // 可空字符串
}

3. 使用指针接收结果

var userPtr *User
if err := scan.Row(&userPtr, rows); err != nil {
	panic(err)
}

性能考虑

scan 库在性能上做了优化：

1. 使用反射但缓存了反射结果
2. 支持预编译扫描器
3. 比标准库的 sql.Rows.Scan() 更高效

与标准库对比

标准库方式：

rows, err := db.Query("SELECT id, name, age FROM users")
if err != nil {
	panic(err)
}
defer rows.Close()

var users []User
for rows.Next() {
	var u User
	if err := rows.Scan(&u.ID, &u.Name, &u.Age); err != nil {
		panic(err)
	}
	users = append(users, u)
}

scan 库方式：

rows, err := db.Query("SELECT id, name, age FROM users")
if err != nil {
	panic(err)
}
defer rows.Close()

var users []User
if err := scan.Rows(&users, rows); err != nil {
	panic(err)
}

总结

scan 库提供了简洁的 API 将数据库查询结果映射到 Go 数据结构中，减少了样板代码，提高了开发效率。它特别适合在以下场景使用：

1. 需要快速将查询结果映射到结构体
2. 处理多行结果到切片
3. 需要简洁的代码风格

对于更复杂的需求，也可以考虑使用更完整的 ORM 库如 GORM 或 XORM。