sqlc 怎么用命名参数生成可读的查询参数结构体

在 SQL 查询里用 sqlc.arg(参数名) 为输入指定名字，再执行 sqlc generate，就能让生成的 Params 字段采用对应的业务名称。例如 sqlc.arg(display_title) 对应 DisplayTitle，sqlc.arg(item_id) 对应 ItemID。参数类型仍由查询、表结构和生成配置共同决定，命名并不替代类型推断。

sqlc 官方地址：https://docs.sqlc.dev/en/stable/

下面用 PostgreSQL 与 Go 的最小项目演示，在编辑器中完成配置、查询编辑和生成文件阅读。sqlc 是命令行生成工具，编辑器只是文件操作入口；不会提供一个虚构的“命名参数生成”按钮。示例无需数据库连接信息。

1. 打开项目配置并固定生成目录

在 VS Code 类编辑器通过 File → Open Folder… 打开项目目录，再从左侧 Explorer 点击 sqlc.yaml。独立演示项目可新建下面的三个文件；已有项目则沿用自己的生成配置，不要直接覆盖其他查询或表结构。

# 在项目根目录保存为sqlc.yaml。
version: "2"
sql:
  - engine: "postgresql"
    schema: "schema.sql"
    queries: "query.sql"
    gen:
      go:
        package: "db"
        out: "db"
        sql_package: "pgx/v5"

-- schema.sql为代码生成提供表结构，不要求在本教程中连接数据库。
CREATE TABLE inventory_item (
    id BIGINT PRIMARY KEY,
    title TEXT NOT NULL
);

保存后，文件树应能看到 sqlc.yaml、schema.sql 与 query.sql 的预定位置，配置中的 out 指向 db。先固定这些路径，后面才知道生成文件该去哪里找。本文按已核实的官方文档用法撰写，不将某个界面版本或任意 sqlc 历史版本都视为相同。

示例表的 id 为 BIGINT，title 为非空 TEXT，查询只修改一个指定物料的标题。这使字段名称、SQL 类型与业务含义都容易对应。对于已有大型 schema，应保留真实结构，不能为了让例子看起来简单而把可空列或自定义类型删掉。

2. 在查询文件中显式命名参数

在 Explorer → query.sql 中填入下面的查询，使用 File → Save 保存。注意参数名字写在 sqlc.arg 内部，而不是给 SQL 结果列增加 AS 别名。查询注释里的 RenameInventoryItem 是方法名称，两个参数名则决定输入字段的命名线索。

-- query.sql中的名称决定生成的查询方法名。
-- name: RenameInventoryItem :exec
-- display_title和item_id显式表达输入参数含义。
UPDATE inventory_item
SET title = sqlc.arg(display_title)::text
WHERE id = sqlc.arg(item_id)::bigint;

完成此步时，query.sql 中应能直接找到 display_title 和 item_id，两处都位于 sqlc.arg 内。PostgreSQL 的类型转换让例子明确指定 text 与 bigint；它不是把参数拼接成 SQL 字符串。生成后的查询仍使用数据库参数占位，不需要调用方用字符串替换宏。

有些位置参数能被 sqlc 正确推断命名，不必为了形式统一强行改写全部查询。但在复杂表达式里，上下文可能不足，字段名就不够直观。此时显式命名能减少调用方对 Column1 一类字段含义的猜测。

3. 生成代码并查看 Params 字段

保存输入文件后，在项目根目录执行生成命令。若工具报解析或配置错误，先修复该错误，不要打开旧的生成文件后误以为改动已经生效。

# 在包含sqlc.yaml的项目根目录生成代码；错误时先处理错误信息。
sqlc generate

回到编辑器，沿 Explorer → db → query.sql.go 打开生成文件，使用 Edit → Find 查找 RenameInventoryItemParams。核对输入字段与 SQL 中命名参数是否对应，而不是直接在生成文件中手动改字段名。

// 字段对应关系示意，非本文实际运行生成的文件。
type RenameInventoryItemParams struct {
    DisplayTitle string
    ItemID       int64
}

上面是字段对应关系的说明片段，本文没有运行生成命令，三张图片均为原创界面说明图。实际生成结果还可能受命名重写、初始缩写、JSON tag 和其他 Go 配置影响；可空输入的类型也可能随驱动与覆盖配置变化。阅读生成文件时，应以当前项目设置为准。

若业务希望允许输入 NULL，应另外理解 sqlc.narg 的语义。它明确要求生成可空参数，不只是替 sqlc.arg 换一个名字；@ 简写也没有对应的可空简写。本文不展开可空更新策略，避免把字段命名与空值行为混在一起。

可以把所有 sqlc.arg 改成 @名字吗？官方支持部分方言使用这种简写，但 MySQL 不支持 @ 作为 sqlc.arg 的替代写法。本文采用显式写法，示例中的 :: 类型转换仍然是 PostgreSQL 语法，不能原样移植到其他方言。

改了参数名，为什么生成类型没变？名称与类型是不同维度，类型仍来自 SQL 与 schema。若连名称也没更新，先确认文件已保存、生成目录正确，以及本次生成是否成功。

能直接修改 Params 字段吗？不建议。应修改查询输入或命名配置后重新生成，否则后续生成会覆盖手工改动，调用方与 SQL 也可能失去对应关系。

最终交接时，将 query.sql 和生成代码的变更一起审阅：参数名称应能让调用者理解用途，查询条件仍保持原有业务约束。命名参数改善的是可读性，不负责创建动态 SQL 或改变查询逻辑。

参考：sqlc 命名参数说明；sqlc PostgreSQL 生成配置。