用 SQL 编写 Go 代码？sqlc 让你彻底告别繁琐的 ORM 与手写 SQL 映射！

icy 昨天 7 抢沙发

默认

摘要： 重新定义 Go 语言数据库交互：sqlc 深度解析与实战指南在 Go 语言的生态中，我们通常在两种极端之间做选择：要么使用 GORM 这样功能强大的 ORM（对象关系映射），但代...

重新定义 Go 语言数据库交互：sqlc 深度解析与实战指南

在 Go 语言的生态中，我们通常在两种极端之间做选择：要么使用 GORM 这样功能强大的 ORM（对象关系映射），但代价是复杂的黑盒机制、潜在的性能损耗以及对 SQL 控制力的丧失；要么选择 database/sql 或 sqlx 手写原生 SQL，虽然性能极致且透明，但面对大量重复的 rows.Scan 映射代码，开发者往往陷入枯燥的体力劳动中。

sqlc 提供了一种第三条道路：SQL-First 的类型安全代码生成方案。

什么是 sqlc？

sqlc 是一个编译器，它通过读取你的 SQL 模式（Schema） 和 查询语句（Queries），自动为你生成类型安全的 Go 代码。

它的核心逻辑非常简单： 1. 编写 SQL：你直接写标准的 SQL 语句（如 PostgreSQL, MySQL, SQLite）。 2. 编译生成：sqlc 分析这些 SQL，推断出输入参数和返回结果的类型。 3. 调用方法：你调用生成的 Go 函数，无需手动处理 Scan 或定义复杂的结构体映射。

它不是 ORM。它不尝试用 Go 语言来模拟 SQL，而是将 SQL 作为“真理来源”，将类型检查前移到了编译阶段。

为什么选择 sqlc 而不是 ORM？

1. 极致的性能

由于生成的代码本质上就是原生的 database/sql 调用，没有任何运行时反射（Reflection）或动态 SQL 构建，其性能与手写原生 SQL 完全一致。

2. 真正的类型安全

在 ORM 中，如果你写错了字段名，通常要到运行时才会报错。而 sqlc 在生成代码时就会检查 SQL 语法。如果你的 SQL 语句在数据库中无法执行，sqlc 在生成阶段就会报错。

3. 掌控感

你拥有对 SQL 的 100% 控制权。你可以使用复杂的 JOIN、窗口函数、CTE（公共表表达式）等高级特性，而无需在 ORM 的 DSL（领域特定语言）中苦苦寻找对应的 API。

4. 消除样板代码

再也不需要写：

text

var name string
var age int
err := row.Scan(&name, &age)

sqlc 会自动为你生成对应的结构体并完成赋值。

快速上手实例

假设我们要构建一个简单的用户管理系统。

第一步：定义 Schema (`schema.sql`)

首先，定义你的数据库表结构。

text

CREATE TABLE authors (
  id   BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
  name TEXT NOT NULL,
  bio  TEXT
);

第二步：编写查询语句 (`query.sql`)

使用特殊的注释 -- name: 函数名 : 动作 来告诉 sqlc 如何生成 Go 函数。

text

-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1 LIMIT 1;

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

-- name: CreateAuthor :one
INSERT INTO authors (name, bio)
VALUES ($1, $2)
RETURNING *;

-- name: UpdateAuthorBio :exec
UPDATE authors
SET bio = $2
WHERE id = $1;

第三步：配置 `sqlc.yaml`

创建配置文件，指定数据库方言和输出路径。

text

version: "2"
sql:
  - schema: "schema.sql"
    queries: "query.sql"
    engine: "postgresql"
    gen:
      go:
        package: "db"
        out: "db"

第四步：生成代码

在终端运行：

text

sqlc generate

sqlc 将在 db 目录下生成 models.go（结构体定义）、db.go（基础接口）和 query.sql.go（具体的业务方法）。

如何在 Go 代码中使用？

生成的代码非常简洁，你可以直接将其注入到你的 Service 层中。

text

package main

import (
	"context"
	"database/sql"
	"fmt"
	"log"

	"your-project/db" // 导入生成的包
	_ "github.com/lib/pq"
)

func main() {
	ctx := context.Background()
	
	// 1. 建立标准数据库连接
	conn, err := sql.Open("postgres", "postgres://user:pass@localhost:5432/mydb?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}

	// 2. 初始化 sqlc 生成的 Queries 结构体
	queries := db.New(conn)

	// 3. 调用生成的方法：创建作者
	newAuthor, err := queries.CreateAuthor(ctx, db.CreateAuthorParams{
		Name: "鲁迅",
		Bio:  "中国现代文学的奠基人",
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("创建成功: %s (ID: %d)\n", newAuthor.Name, newAuthor.ID)

	// 4. 调用方法：查询作者
	author, err := queries.GetAuthor(ctx, newAuthor.ID)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("查询到作者: %s, 简介: %s\n", author.Name, author.Bio)

	// 5. 调用方法：获取作者列表
	authors, err := queries.ListAuthors(ctx)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("共有 %d 位作者\n", len(authors))
}

核心机制深度分析

1. 类型推断

sqlc 并不是简单的字符串替换。它内部包含了一个 SQL 解析器，能够分析数据库的元数据。例如，如果你在 SQL 中使用了 COUNT(*)，sqlc 知道结果应该是 int64；如果你使用了 JSONB 字段，它会将其映射为 []byte 或相应的 Go 类型。

2. 动作指令详解

在 query.sql 中，:one, :many, :exec 决定了生成的函数签名： - :one \(\rightarrow\) 返回 (Model, error)。如果没找到记录，会返回 sql.ErrNoRows。 - :many \(\rightarrow\) 返回 ([]Model, error)。 - :exec \(\rightarrow\) 返回 error。适用于不需要返回数据的 UPDATE 或 DELETE 操作。