04.4.8.1 SQLx 查询宏与运行时
所属:全栈开发面试题库 / 04 后端语言与运行时 / 04.4 Rust / 04.4.8 数据访问
04.4.8.1-001 query! 宏与 query 函数的核心差异是什么?
一句话结论
sqlx::query! 是编译期宏:编译时连开发库(或读离线元数据)校验 SQL 并由数据库返回列信息,自动生成返回类型;sqlx::query 是运行时函数:SQL 字符串原样下发,列与类型在运行时从 Row 手动解码,编译期不校验 SQL。
概念解释
两者都走同一套异步执行与参数绑定管线,区别只在「校验时机」和「类型推导」。宏版本依赖 macros feature,需要在编译期可访问数据库 schema;函数版本不依赖编译期数据库,适合 SQL 完全动态、或编译环境无法连库的场景。宏版本返回匿名记录类型,函数版本返回通用 Row,需要配合 query_as 或手动 row.try_get。
原理流程
- 宏展开时读取 SQL 文本与绑定参数类型,向数据库(或
.sqlx离线缓存)发起 prepare。 - 数据库返回列名、类型、可空性,宏据此生成结构体字段与 Rust 类型。
- 函数版本不做 prepare 校验,运行时把 SQL 与绑定参数发给服务端。
- 结果行通过
FromRow或try_get在运行时解码,类型不匹配会在取数时报错。
代码或图示
// 宏:编译期校验,返回匿名记录,字段名来自列名
let row = sqlx::query!("SELECT id, name FROM users WHERE id = $1", id)
.fetch_one(&pool)
.await?;
// 函数:运行时下发,手动解码
let row = sqlx::query("SELECT id, name FROM users WHERE id = $1")
.bind(id)
.fetch_one(&pool)
.await?;
let name: String = row.try_get("name")?;
常见误区
- 以为
query!不需要数据库也能在本地编译:默认需要开发库,离线模式依赖.sqlx元数据。 - 以为函数版本和宏版本性能有本质差别:性能差异主要来自语句缓存与解码方式,而非校验时机。
追问
- 想把结果直接映射到已有结构体用哪个?答:宏用
query_as!,函数用query_as::<_, T>。 - SQL 字符串在运行时才拼出来怎么办?答:只能走
query/query_as函数版本或QueryBuilder,宏要求 SQL 字面量在编译期可见。
04.4.8.1-002 SQLx 在 Rust 数据访问生态里的定位是什么?
一句话结论
SQLx 是「异步纯 Rust SQL 工具包」,不是 ORM:它直接写 SQL,提供编译期查询校验、类型映射、内置连接池与迁移工具,不做表到对象的关系映射与关联预加载。
概念解释
与 Diesel 这类 DSL/ORM 不同,SQLx 不把表操作翻译成链式表达式,而是让开发者写原生 SQL,再通过宏或 FromRow 把行映射到结构体。它支持 PostgreSQL、MySQL/MariaDB、SQLite,驱动以纯 Rust 实现为主(SQLite 驱动内部依赖 C 绑定,待确认:具体绑定实现以 docs.rs 当前版本为准)。定位决定了它更适合「熟 SQL、想保留 SQL 控制力、又要类型安全」的后端项目。
原理流程
- 选择后端 feature 与异步运行时 feature,装配驱动与连接池。
- 业务代码写 SQL 文本,通过宏或函数提交。
- 驱动完成协议交互、语句准备与缓存、行流式读取。
- 解码层按 Rust 类型把列值转成
Option<T>/T,映射到结构体。
代码或图示
SQLx 定位分层
├── 驱动层:Postgres / MySql / Sqlite 协议实现
├── 连接层:Pool、Connection、Transaction、语句缓存
├── 查询层:query/query_as/query! 系列、QueryBuilder
├── 映射层:FromRow、Type、Encode、Decode
└── 工程层:migrate 迁移、sqlx::test 测试、离线元数据
常见误区
- 把 SQLx 当成轻量 ORM:它没有 model 关联、has_many 预加载那套抽象。
- 以为 SQLx 屏蔽了方言:占位符、枚举、JSON 类型仍需按后端方言处理。
追问
- 项目要求复杂对象关联预加载,SQLx 够吗?答:需要自己用多次查询或 join 组装,关联预加载能力弱于 Diesel/SeaORM。
- SQLx 支持 MSSQL 吗?答:旧版本曾支持,0.7 之后 MSSQL 驱动已移除重写,当前以 docs.rs 当前版本为准。
04.4.8.1-003 Cargo.toml 中 SQLx 的 feature 体系怎么拆?
一句话结论
SQLx 的 feature 分成三类:异步运行时与 TLS(如 runtime-tokio-rustls)、数据库后端(postgres/mysql/sqlite)、额外类型与工具(chrono/uuid/json/migrate/macros/derive 等),按需开启,避免编译不需要的驱动。
概念解释
运行时 feature 决定挂在哪个异步执行器上、用哪个 TLS 栈:常见组合是 Tokio + rustls,也有 Tokio + native-tls、async-std 组合。后端 feature 决定编译进哪个驱动。类型扩展 feature 把对应 crate 的类型接入编解码;macros 提供 query! 系列,derive 提供 FromRow/Type/Encode/Decode derive,migrate 提供迁移管理与 migrate! 宏。
原理流程
- 在
[dependencies]里选一个运行时 TLS 组合作为必填项。 - 按目标数据库勾选对应后端 feature。
- 按字段类型需要勾选
chrono/uuid/json/time/bigdecimal等。 - 用到宏或 derive 时再开
macros/derive,启动迁移时开migrate。
代码或图示
[dependencies]
sqlx = { version = "0.8", features = [
"runtime-tokio-rustls",
"postgres",
"chrono",
"uuid",
"json",
"macros",
"derive",
"migrate",
] }
常见误区
- 同时开多个后端:包体积与编译时间上升,还可能引入类型歧义。
- 开了
chrono又用time类型:两者并存时宏的类型选择以 feature 优先级与文档为准,混用容易解码报错。
追问
- 只连 MySQL 却开了
postgresfeature 有什么问题?答:多编一份驱动,且离线元数据与类型映射容易混淆,应关闭。 macros与derive能只开一个吗?答:可以;只用手写query/FromRow时不必开macros,不用 derive 时不必开derive。
04.4.8.1-004 三种数据库后端与 Any 驱动如何取舍?
一句话结论
确定只连一种数据库就直接用 Pool<Postgres> / Pool<MySql> / Pool<Sqlite>,拿编译期类型保证;需要同一套代码在运行时按连接串切换驱动,才用 Any 后端与 AnyPool,代价是类型与方言能力被收敛到公共子集。
概念解释
单后端模式下,查询类型、错误类型、列类型都绑定具体后端,宏校验也针对该方言。Any 是一个运行时驱动抽象:连接串 scheme 决定实际后端,AnyConnection 在内部分发到对应后端实现。Any 适合中间件、通用框架等需要兼容多库的场景;业务系统通常不建议为了「以后可能换库」而提前上 Any。
原理流程
- 勾选对应后端 feature;使用
Any时额外启用anyfeature。 Pool::connect根据 URL scheme 选择驱动后端。- 查询通过
Executor下发,Any层做后端适配与错误归一。 - 解码时只能依赖三端公共类型,后端特有类型需要降级处理。
代码或图示
// 单后端
let pool: sqlx::PgPool = sqlx::PgPool::connect(&url).await?;
// Any 后端:运行时按 scheme 选择 postgres / mysql / sqlite
let pool: sqlx::AnyPool = sqlx::AnyPool::connect(&url).await?;
常见误区
- 以为
Any能抹平方言差异:占位符、JSON、枚举、分页语法仍需自己兼容。 - 在业务核心路径默认
Any:丢失单后端的类型检查与宏校验精度。
追问
AnyPool与Pool<AnyConnection>是什么关系?答:AnyPool是Pool<Any>的类型别名,内部连接为AnyConnection。- 同一进程能混连两种数据库吗?答:可以分别建立
PgPool与MySqlPool,但不要把它们塞进同一个AnyPool后期望方言互通。
04.4.8.1-005 连接串格式与 DATABASE_URL 分别是什么样?
一句话结论
连接串按后端 scheme 组织:postgres://、mysql://、sqlite://,常见字段含用户名、密码、主机、端口、库名与参数;SQLx 约定从环境变量 DATABASE_URL 读取,宏与 CLI 默认都认这个变量。
概念解释
PostgreSQL 形如 postgres://user:password@host:port/dbname,也支持 postgresql:// scheme;MySQL 形如 mysql://user:password@host:port/dbname;SQLite 形如 sqlite://path/to/db.sqlite,内存库常用 sqlite::memory:。连接串尾部可带 ?sslmode=require 等参数。密码含特殊字符时需要 URL 编码。DATABASE_URL 是约定俗成的环境变量名,并非 SQLx 独有,CLI 与测试同样依赖它。
原理流程
- 启动程序时读取
DATABASE_URL环境变量(常由 dotenvy 从.env载入)。 - 连接选项解析 scheme,选择对应后端驱动。
- 解析主机、凭证、库名与查询参数,建立连接。
- 宏在编译期也读取同一变量去 prepare 查询。
代码或图示
postgres://app:secret@db.internal:5432/shop?sslmode=require
mysql://app:secret@db.internal:3306/shop
sqlite://./data/shop.sqlite?mode=rwc
sqlite::memory:
常见误区
- 密码里有
@、/未编码,导致解析错位。 - 把生产库连接串写进源码或提交进版本库;应放环境变量或
.env(.env进.gitignore)。
追问
- 连接超时、SSL 模式能在连接串里配吗?答:部分可在串上配,精细控制用各后端的
ConnectOptions类型,以 docs.rs 当前版本为准。 - SQLite 的
mode=rwc是什么含义?答:打开读写并在文件不存在时创建;具体取值以后端文档为准。
04.4.8.1-006 .env 与 dotenvy 加载 DATABASE_URL 的顺序要注意什么?
一句话结论
通常在 main 最开头调用 dotenvy::dotenv()(或等价加载)把 .env 中的变量注入进程环境,再读 DATABASE_URL;宏在编译期由 cargo 构建脚本阶段读取环境变量,与运行时加载不是同一时机,离线/在线编译都要保证变量可见。
概念解释
dotenvy 在程序启动时解析项目根的 .env,覆盖或补齐环境变量;运行时 Pool::connect 读到的是进程环境。但 query! 宏在 cargo 编译阶段执行,此时若终端未导出 DATABASE_URL、也没有 .env 被构建工具加载,宏会因连不上库而报错。CI 中要么注入环境变量,要么走离线元数据。
原理流程
- 本地开发:
.env写DATABASE_URL,main开头dotenvy::dotenv().ok()。 - 编译期:宏需要环境里有
DATABASE_URL(或离线模式),IDE 与 cargo 各自的环境要对齐。 - 运行期:进程环境变量被连接池读取建立连接。
- 部署环境:由容器环境变量或密钥管理注入,不依赖
.env文件。
代码或图示
// main 入口尽早加载
fn main() -> Result<(), sqlx::Error> {
dotenvy::dotenv().ok();
let url = std::env::var("DATABASE_URL")?;
// ... 构建运行时与连接池
Ok(())
}
常见误区
- 先建连接池再
dotenv():读到的是空变量。 - 以为运行时
.env加载了,编译期宏就能连上库:两者时机不同。
追问
.env该不该提交仓库?答:不应提交真实凭证;可提交.env.example列出需要的变量名。- 多环境配置怎么区分?答:按环境加载不同文件(如
.env.development),或直接由部署平台注入环境变量。
04.4.8.1-007 Pool<DB>、AnyPool 与单连接 Connection 有什么区别?
一句话结论
Pool<DB> 是可克隆共享的连接池,AnyPool 是多后端池别名,Connection 是单条物理连接;Web 服务全局共享池,业务代码从池里借连接,只有长事务或批量脚本才直接持有单连接。
概念解释
池内部维护空闲连接队列与在借计数,Pool 自身实现 Clone,可放进应用状态到处传递;借连接通过 acquire 得到 PoolConnection,归还发生在其 drop 时。Connection 没有池化复用,反复建立/销毁成本高,且一次只能服务一条链路。AnyPool 对应 Pool<Any>,内部连接是 AnyConnection。
原理流程
- 启动时用
PoolOptions构建池,按最小连接数预热。 - 请求到达时从池里
acquire一个连接。 - 查询执行完,连接包装器 drop,连接回到空闲队列。
- 池关闭后再借连接会返回
PoolClosed类错误。
代码或图示
let pool = sqlx::postgres::PgPoolOptions::new()
.max_connections(10)
.connect(&url)
.await?;
// Pool 可克隆,放入 axum State
let conn = pool.acquire().await?; // 显式借连接
let row = sqlx::query("SELECT 1").fetch_one(&pool).await?; // 也可直接传池
常见误区
- 把
Connection放进全局状态长期持有:失去并发复用。 - 以为传
&pool和传&mut conn完全等价:前者每次取借连接,后者复用已借连接。
追问
- 池包装器 drop 时连接一定归还吗?答:正常 drop 归还;若连接中途出错被判定不可用,池会丢弃并重建。
- 一个请求里多次查询该传池还是传连接?答:同一事务内必须传同一个
&mut tx;无事务的多次独立查询可传池,由池决定复用哪条连接。
04.4.8.1-008 连接串之外,ConnectOptions 能控制哪些细节?
一句话结论
连接串负责基本定位与凭证,精细控制(连接超时、语句缓存、TLS 配置、应用名等)走各后端的 ConnectOptions 类型构建后再传给池;不同后端的选项字段不完全一致。
概念解释
Postgres 对应 PgConnectOptions,MySQL 对应 MySqlConnectOptions,SQLite 对应 SqliteConnectOptions。它们提供 TLS、statement cache、应用名、命令选项等设置。连接串能表达常见参数,复杂场景(自定义 TLS 根证书、关闭语句缓存、设置后端参数)需要结构化选项。具体字段名以后端 docs.rs 当前版本为准,不确定项标注待确认。
原理流程
- 从 URL 解析出基础选项,或直接
::new()。 - 链式调用选项方法设置超时、TLS、缓存等。
PoolOptions::connect_with(options)用选项建池。- 每条新连接按同一选项模板建立。
代码或图示
use sqlx::postgres::PgConnectOptions;
let opts = PgConnectOptions::new()
.host("db.internal")
.database("shop")
.username("app")
.password("secret");
let pool = sqlx::postgres::PgPoolOptions::new()
.max_connections(10)
.connect_with(opts)
.await?;
常见误区
- 在连接串里塞后端不识别的参数,被静默忽略。
- 把所有调优都堆在池选项上:池负责复用,连接级参数归
ConnectOptions。
追问
- 语句缓存在哪一层?答:默认在连接级别缓存预处理语句,
ConnectOptions可调整缓存容量或行为;具体配置项以文档为准。 - 想要每条连接带统一会话参数怎么做?答:用
ConnectOptions或PoolOptions::after_connect钩子执行初始化语句。
04.4.8.1-009 SQLx 与 tokio-postgres、SeaORM、Diesel 的定位差异是什么?
一句话结论
tokio-postgres 是最底层的异步协议客户端,SQLx 在其上提供池化、宏校验与多后端抽象,Diesel 是编译期 DSL ORM,SeaORM 是异步 ORM/实体框架;选型沿「底层控制 → 类型安全 SQL → ORM 抽象」递进。
概念解释
tokio-postgres 只做 Postgres 协议通信,连接池、映射、迁移都要自己组合。SQLx 收编了池、宏校验、类型映射与迁移,但 SQL 仍由人写。Diesel 用 Rust 表达式 DSL 生成 SQL,类型检查在编译期,模型与关联抽象强,但默认同步、生态围绕 Postgres 最早成熟。SeaORM 提供实体定义、关系、查询构建器与异步运行,偏 ORM 体验。
原理流程
- 先确定团队对 SQL 控制力与 ORM 抽象的偏好。
- 只服务 Postgres 且要协议级控制,考虑 tokio-postgres。
- 要原生 SQL + 编译期校验 + 多后端,选 SQLx。
- 要强类型 DSL、模型关联与同步工程,选 Diesel;要异步实体 ORM,选 SeaORM。
代码或图示
抽象层级(由低到高)
tokio-postgres / mysql_async / rusqlite
→ SQLx(池 + 宏校验 + 类型映射 + 迁移)
→ SeaORM(实体 / 关系 / 异步查询构建器)
→ Diesel(编译期 DSL / model / 关联,默认同步)
常见误区
- 把 Diesel 当异步库直接在 tokio handler 里跑:标准 Diesel 是同步的,异步要走 diesel-async。
- 以为 SQLx 和 SeaORM 是同一层:SeaORM 内部可基于 SQLx 驱动,抽象层级更高。
追问
- 已有大量手写 SQL 的项目迁到 Rust,优先哪个?答:SQLx 最平滑,SQL 文本可直接复用。
- 团队希望少写 SQL、靠模型 CRUD,选哪个?答:SeaORM 或 Diesel 更贴合,按同步/异步偏好定。
04.4.8.1-010 为什么要用 no-default-features 裁剪 SQLx feature?
一句话结论
SQLx 默认 feature 会带上常用后端与运行时,显式 default-features = false 后按需勾选,可以避免编入用不到的驱动、TLS 栈与类型扩展,缩短编译时间、缩小产物体积。
概念解释
默认特性组合面向开箱即用,可能包含你不需要的后端或 TLS 后端。生产依赖裁剪时,先关闭默认 feature,再列出运行时、后端、类型扩展与工具宏。feature 选择还影响离线元数据目录内容:只声明实际启用的后端,prepare 生成的缓存才与构建配置一致。
原理流程
- 写
sqlx = { version = "0.8", default-features = false, features = [...] }。 - 勾选唯一运行时 TLS 组合与目标后端。
- 补齐字段类型与工程工具所需 feature。
cargo build后检查编译树,确认无多余驱动被拉入。
代码或图示
sqlx = { version = "0.8", default-features = false, features = [
"runtime-tokio-rustls",
"sqlite",
"macros",
"derive",
] }
常见误区
- 关闭默认 feature 后忘了开
macros,导致query!找不到宏。 - 为图省事保留默认全量 feature,产物里带上用不到的数据库驱动。
追问
- dev-dependencies 与 dependencies 的 feature 会合并吗?答:cargo feature 是按 crate 合并的,dev 依赖开启的 feature 也会进常规构建,需要留意。
- 裁剪后编译报「feature 未启用某类型」怎么办?答:按报错补对应后端或类型扩展 feature。
04.4.8.1-011 SQLx 的版本与 edition 前提怎么表述才稳妥?
一句话结论
面试与文档中统一表述为「Rust stable 工具链、edition 2021,SQLx 版本以 docs.rs 当前版本为准」;具体次版本 API 差异不写死,遇到版本敏感行为标注「待确认」并给验证方式。
概念解释
SQLx 跨 0.7 到 0.9 期间有错误类型、特性名、API 签名调整,写死 0.7/0.8 容易与读者本地版本不符。工程实践中应在 Cargo.toml 锁定实际版本,文档描述只保留稳定概念(池、事务、宏、迁移)。规范要求:不确定的 API 名、feature、CLI 子命令写「待确认」,并注明去 docs.rs/crates.io 核对。
原理流程
Cargo.toml声明语义化版本区间,Cargo.lock锁定实际解析版本。- 文档与题库描述稳定概念与通用流程。
- 版本敏感 API 在阅读源码或文档时二次核对。
- 升级时按 release notes 迁移签名与 feature 调整。
代码或图示
# 工程内锁定实际版本;文档不写死次版本细节
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres"] }
常见误区
- 把某版本才有的方法当成长期稳定 API 写入答案。
- 看到本地版本行为与教程不一致就怀疑代码错误,实际是版本差异。
追问
- 如何确认某个 API 是否存在于当前版本?答:查 docs.rs/sqlx 当前版本文档,或
cargo doc --open本地生成。 - 大版本升级要注意什么?答:先看 release notes 的迁移章节,重点核对 feature 改名、错误类型与宏行为。
04.4.8.1-012 「纯 Rust 驱动」在 SQLx 语境下意味着什么?
一句话结论
纯 Rust 指 Postgres/MySQL 协议用 Rust 实现,不依赖 libpq、libmysqlclient 这类 C 客户端库;SQLite 后端因 SQLite 本身是 C 库,仍通过绑定接入,属于例外。
概念解释
纯 Rust 驱动避免了 C 编译链、原生库链接与跨平台 ABI 问题,交叉编译更简单,内存安全边界也更清晰。但「纯 Rust」不等于零 unsafe:协议解析与绑定层内部仍可能有 unsafe,对外 API 保持安全。理解这一点可以避免在选型时把「纯 Rust」误读成「无 C 依赖」。
原理流程
- 驱动按数据库协议在 Rust 内完成握手、认证、消息编解码。
- 连接池与事务管理建立在协议连接之上。
- SQLite 路径通过绑定调用 SQLite C 库完成存储访问。
- 对外暴露统一的
Database/Connection/Executor抽象。
代码或图示
Postgres 协议 → Rust 实现(纯 Rust)
MySQL 协议 → Rust 实现(纯 Rust)
SQLite 存储引擎 → C 库 + Rust 绑定(例外)
常见误区
- 认为纯 Rust 驱动性能一定超过 C 客户端:实际取决于协议实现与缓存策略,需压测。
- 以为纯 Rust 就没有 unsafe:内部实现细节不对外承诺无 unsafe。
追问
- 交叉编译时纯 Rust 驱动有什么好处?答:不需要目标平台对应的 C 客户端开发库,工具链链上少一层原生依赖。
- SQLite 绑定用的是哪个 crate?答:待确认,以当前 SQLx 文档依赖树为准。
04.4.8.1-013 query、query_as、query_scalar 三个运行时函数怎么选?
一句话结论
query 返回原始 Row 手动解码;query_as 把整行映射到实现 FromRow 的结构体;query_scalar 只取单列标量值;按「需要整行结构体 / 单列值 / 手动取列」选择。
概念解释
三者返回的都是可流式执行的查询对象,差异在结果映射阶段。query_as::<_, T> 在取行时尝试把列按名称或位置塞进 T;query_scalar::<_, T> 取第一列并按标量解码,适合 SELECT count(*)、SELECT id 这类单值查询。原始 query 留给需要动态读列、列结构不固定的场景。
原理流程
- 写 SQL 文本并
bind参数。 - 选择映射方式:结构体 / 标量 / 原始行。
- 调用
fetch_one/fetch_optional/fetch_all/fetch执行。 - 解码错误在取行阶段以
Decode类错误返回。
代码或图示
#[derive(sqlx::FromRow)]
struct User { id: i64, name: String }
let user: User = sqlx::query_as::<_, User>("SELECT id, name FROM users WHERE id = $1")
.bind(id)
.fetch_one(&pool)
.await?;
let count: i64 = sqlx::query_scalar("SELECT count(*) FROM users")
.fetch_one(&pool)
.await?;
常见误区
query_scalar用于多列查询:它只取第一列,其余列被忽略。- 结构体字段名与列名不一致又不做映射:
FromRow按默认列名匹配失败。
追问
query_as要求 T 实现什么?答:FromRow,通常#[derive(FromRow)]即可。- 标量是可空列时类型写什么?答:写
Option<T>,与列可空性对齐。
04.4.8.1-014 query!、query_as!、query_scalar! 宏各自生成什么类型?
一句话结论
query! 生成匿名记录结构体;query_as! 把结果映射到你指定的结构体;query_scalar! 直接生成单列标量类型;列名、类型与可空性都来自编译期数据库返回的元数据。
概念解释
宏在编译期 prepare SQL,拿到每列的名称、类型 OID、是否可空,再据此生成 Rust 类型。query! 的返回行是宏内联生成的匿名记录,字段即列名;query_as! 在生成代码里完成到目标结构体的赋值;query_scalar! 跳过行包装直接产出标量。宏要求 SQL 是字面量,参数通过 bind 位置传入。
原理流程
- 宏解析 SQL 字面量与参数列表。
- 连接开发库 prepare(或读
.sqlx离线缓存)取列元数据。 - 按元数据生成记录字段与 Rust 类型,可空列包
Option。 - 执行阶段把行解码进生成类型或目标结构体。
代码或图示
// 匿名记录:row.id、row.name
let row = sqlx::query!("SELECT id, name FROM users WHERE id = $1", id)
.fetch_one(&pool)
.await?;
// 映射到已有结构体
let user: User = sqlx::query_as!(User, "SELECT id, name FROM users WHERE id = $1", id)
.fetch_one(&pool)
.await?;
// 单列标量
let count: i64 = sqlx::query_scalar!("SELECT count(*) FROM users")
.fetch_one(&pool)
.await?;
常见误区
- 以为
query_as!不检查结构体字段与列是否对应:不匹配仍会在编译期或取数时报错。 - 把宏生成的匿名记录传给其它函数当具体类型用:匿名类型无法在函数签名间直接传递,需要转结构体。
追问
- 匿名记录能赋值给结构体吗?答:不能自动转换;需要
query_as!指定结构体,或手动构造。 - 列别名会成为字段名吗?答:会,宏按结果列名(含
AS别名)生成字段。
04.4.8.1-015 宏生成的匿名记录与 FromRow 结构体有什么区别?
一句话结论
匿名记录由宏按查询结果现场生成,类型只在当前作用域可见;FromRow 结构体是你自己定义、可跨函数复用的模型类型;接口边界处应暴露结构体而非匿名记录。
概念解释
匿名记录的字段集合由 SQL 决定,换一条查询字段就不同,无法作为稳定函数签名。FromRow 结构体与表/DTO 对应,可在 handler、service、测试间传递。工程实践里:内部快速取数可用匿名记录,对外返回与跨层传递一律定义结构体并用 query_as!/query_as 映射。
原理流程
- 写宏查询时先判断结果是否要跨函数传递。
- 仅当前作用域使用:接受匿名记录。
- 需要复用或进响应 DTO:定义结构体并 derive
FromRow,用query_as!。 - 重构时把匿名记录字段逐个对齐到结构体字段。
代码或图示
#[derive(sqlx::FromRow, Debug)]
struct UserSummary { id: i64, name: String }
async fn summarize(pool: &sqlx::PgPool, id: i64) -> Result<UserSummary, sqlx::Error> {
let u = sqlx::query_as!(
UserSummary,
"SELECT id, name FROM users WHERE id = $1",
id
)
.fetch_one(pool)
.await?;
Ok(u)
}
常见误区
- 把匿名记录作为
async fn返回类型:编译期类型写不出来,只能存成内部类型。 - 为了省事全部用匿名记录,导致 service 层到处泄漏 SQL 列结构。
追问
FromRow支持按位置还是按名称映射?答:derive 默认按列名匹配字段;位置映射需手写实现,以文档为准。- 结构体字段比查询列多会怎样?答:缺失列按可空性处理,非空字段取不到值会解码失败。
04.4.8.1-016 query_as! 绑定结构体时字段名与列名如何映射?
一句话结论
默认按列名与结构体字段名同名匹配(忽略大小写差异由 derive 规则处理),列名与字段名不一致时用 SQL 别名对齐,或在结构体上用字段属性指定列名。
概念解释
FromRow derive 读取结果集的列标签,与结构体字段一一对应:同名直接赋值;数据库列带下划线、字段用 camelCase 时,需要在 SQL 里 AS 成字段名,或借助 derive 属性声明映射。列缺失或类型不匹配会在编译期(宏)或解码期(函数版本)暴露。
原理流程
- 定义结构体,字段名对齐预期列名。
- SQL 中用
AS把异构列名映射成字段名。 query_as!把列值解码到对应字段。- 某列为空而字段非
Option时返回解码错误。
代码或图示
#[derive(sqlx::FromRow)]
struct User {
id: i64,
display_name: String,
}
let u = sqlx::query_as!(
User,
"SELECT id, display_name AS display_name FROM users WHERE id = $1",
id
)
.fetch_one(&pool)
.await?;
常见误区
- 列名是
user_name,字段是userName,又不写别名:匹配失败。 - 给字段加了 serde 属性就以为
FromRow也认:serde 与 FromRow 是两套属性,不要混用。
追问
- 能不能给字段起个别名而不改 SQL?答:查
FromRowderive 支持的列映射属性;具体属性名以 docs.rs 当前版本为准,不确定写待确认。 - 一个结构体映射多个查询时怎么办?答:保持字段与列命名约定一致,或为不同视图定义不同 DTO。
04.4.8.1-017 fetch_one、fetch_optional、fetch_all、fetch、fetch_scalar 有何差异?
一句话结论
fetch_one 要求恰好一行,零行报 RowNotFound、多行取第一行并视情况报错;fetch_optional 零行返回 None、一行返回 Some;fetch_all 取全部行成 Vec;fetch 返回流式 Stream;fetch_scalar 取单列标量。
概念解释
选择取决于结果基数:明确唯一用 fetch_one;可能不存在用 fetch_optional;列表用 fetch_all;大数据集用 fetch 流式拉取;单值聚合用 fetch_scalar。fetch_one 对多行的处理以当前版本文档为准,常见语义是期望单行,多行会触发错误或取首行,不要假设其静默忽略多余行。
原理流程
- 确定业务上结果是 0/1/多/流式。
- 选择对应 fetch 方法。
- 执行查询并按映射方式解码。
- 基数不符时返回对应错误或
None。
代码或图示
let one: User = query_as(...).fetch_one(&pool).await?;
let opt: Option<User> = query_as(...).fetch_optional(&pool).await?;
let all: Vec<User> = query_as(...).fetch_all(&pool).await?;
let mut stream = query_as(...).fetch(&pool); // 逐行消费
let scalar: i64 = query_scalar(...).fetch_one(&pool).await?;
常见误区
- 可能查不到记录却用
fetch_one,把正常空结果变成 404 错误链路。 - 大表用
fetch_all一次性加载,内存被全部结果撑爆。
追问
fetch_optional多行时行为如何?答:以当前版本文档为准;需要严格单行应加LIMIT 1。- 流式
fetch中途出错怎么处理?答:在流的next循环里处理Err,并确保流被消费或丢弃以归还连接。
04.4.8.1-018 一行多列与单列标量查询分别怎么取值?
一句话结论
多列用结构体、元组或匿名记录按列读取;单列用 query_scalar/query_scalar! 直接得到标量;多列也可以按位置取元组 (T1, T2, ...)。
概念解释
SQLx 支持把行解码为元组:列顺序与元组位置一一对应,适合临时返回两三个值的统计查询。单列场景走标量路径,避免再包一层单行结构体。元组列数有限制(常用上限以文档为准,超出建议定义结构体)。列值可空时对应位置必须是 Option<T>。
原理流程
- 判断结果列数:一列走标量,多列走结构体或元组。
- 元组按 SQL 列顺序排列类型。
- fetch 时按位置或名称解码。
- 类型与可空性不匹配返回
Decode错误。
代码或图示
let pair: (i64, String) = sqlx::query_as(
"SELECT id, name FROM users ORDER BY id LIMIT 10"
).fetch_all(&pool).await?;
let name: String = sqlx::query_scalar(
"SELECT name FROM users WHERE id = $1", id
).fetch_one(&pool).await?;
常见误区
- 元组顺序与 SQL 列顺序写反:编译可能通过,运行时解码类型报错。
- 用结构体只取一列,多写样板代码。
追问
- 元组支持多少列?答:常见为固定上限(如 10 余个),超出定义结构体;具体数字以 docs.rs 为准。
- 标量列是可空枚举怎么办?答:标量类型写
Option<枚举类型>,解码规则同普通列。
04.4.8.1-019 execute 与 fetch_* 的区别是什么?
一句话结论
execute 用于不关心返回行的写操作(INSERT/UPDATE/DELETE/DDL),返回 PgQueryResult 之类结果,可取 rows_affected();fetch_* 用于读取结果集,逐行解码。
概念解释
写语句没有结果集需要遍历,execute 把语句发到服务端并返回执行摘要,包括影响行数、最后插入行号(后端支持时)。读语句用 fetch 系列拿行。混用后果:写操作误用 fetch 会多走行解码路径;读操作误用 execute 则拿不到数据。
原理流程
- 判断语句类型:写/DDL 走
execute,读走 fetch。 execute完成后取rows_affected做业务判断。- fetch 系列按映射方式逐行解码。
- 批量写可结合多行 VALUES 一次
execute。
代码或图示
let result = sqlx::query("UPDATE users SET name = $2 WHERE id = $1")
.bind(id)
.bind(new_name)
.execute(&pool)
.await?;
println!("affected: {}", result.rows_affected());
常见误区
- 用
rows_affected() == 0判断记录不存在:要先区分是条件未命中还是数据问题,必要时配合fetch_optional。 - 以为
execute不返回行就不需要事务:多步写仍要在事务里保证一致性。
追问
- 最后自增 ID 怎么拿?答:Postgres 用
RETURNING id配合 fetch;MySQL 可从结果的 last insert id 取,具体 API 以后端文档为准。 - DDL 语句能在事务里跑吗?答:取决于后端,Postgres 多数 DDL 可事务化,MySQL 部分 DDL 隐式提交。
04.4.8.1-020 各后端的占位符写法有什么不同?
一句话结论
PostgreSQL 用 $1、$2 位置占位符;MySQL 与 SQLite 用 ? 占位符;绑定顺序与占位符位置对应,跨后端移植 SQL 时首先要改占位符语法。
概念解释
SQLx 的 bind 按位置提交参数,占位符方言由后端决定。PG 命名参数支持情况以后端文档为准;MySQL/SQLite 的 ? 不编号,重复出现时按绑定先后对应。编写跨库代码时,占位符是少数无法被驱动完全抹平的方言差异之一,Any 模式下尤其要注意。
原理流程
- 按目标后端写对应占位符。
bind调用顺序与占位符出现顺序一致。- 驱动把参数按协议编码随语句发送。
- 占位符数量与绑定数量不符时在 prepare 或执行阶段报错。
代码或图示
// PostgreSQL
sqlx::query("SELECT id FROM users WHERE name = $1 AND age > $2")
.bind(name).bind(age);
// MySQL / SQLite
sqlx::query("SELECT id FROM users WHERE name = ? AND age > ?")
.bind(name).bind(age);
常见误区
- PG 语句里混用
?,prepare 直接失败。 - 多个
?时bind顺序写反,导致条件错位且不易察觉。
追问
- 能不能用命名占位符?答:PG 驱动支持情况以文档为准;工程上通常统一位置占位符最稳妥。
- 绑定数组展开成多个占位符怎么做?答:动态场景用
QueryBuilder生成片段与参数,不要手写字符串拼占位符。
04.4.8.1-021 为什么宏要求参数类型可在编译期推断,动态参数列表怎么办?
一句话结论
宏在编译期要把每个绑定参数的类型发给数据库做类型校验,因此参数必须是编译期可知类型;参数数量或取值完全运行时决定时,改用 query/query_as 函数版本配合 QueryBuilder。
概念解释
query! 的参数出现在宏调用语法里,编译器能推导出 String、i64 等具体类型,宏据此生成绑定代码。运行时才决定「绑定几个参数、每个参数什么类型」的场景,宏无法展开出固定绑定列表,只能走运行时 API。这也是动态 SQL 必须退出宏路径的根本原因。
原理流程
- 参数固定且类型明确:使用宏,获得编译期校验。
- 参数数量/类型运行时变化:放弃宏。
- 用
QueryBuilder按条件 append 片段与bind。 - 最终
query_as执行并映射结构体。
代码或图示
// 固定参数:宏可用
sqlx::query!("SELECT * FROM users WHERE id = $1", id);
// 参数动态:函数版本 + QueryBuilder
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new("SELECT * FROM users WHERE 1=1");
if let Some(name) = name_filter {
qb.push(" AND name = ").push_bind(name);
}
let rows = qb.build_query_as::<User>().fetch_all(&pool).await?;
常见误区
- 试图把
Vec<Value>直接塞进宏的绑定列表:宏不接受动态参数集合。 - 为了用宏把动态条件硬写成多条 SQL 分支,维护成本高于运行时构造。
追问
QueryBuilder的push_bind与宏 bind 的类型检查强度一样吗?答:运行时解码校验,编译期不做 SQL 与类型对账。- 动态参数都是同一种类型能否简化?答:可以用数组绑定或展开占位符的
QueryBuilder写法,具体语法以后端支持为准。
04.4.8.1-022 SQL 列名不存在或语法错误,宏在什么时机暴露?
一句话结论
宏在编译期(连库 prepare 或读离线元数据时)暴露列名不存在、语法错误、类型不匹配;函数版本则在运行时执行到该语句才报错。
概念解释
宏把 SQL 交给数据库解析器做 prepare:语法错误、表/列不存在、类型无法隐式转换都会在 prepare 阶段返回错误,宏把它转成编译错误。离线模式下,校验依据是 .sqlx 缓存的元数据;缓存过期时错误信息可能与真实库状态不符。函数版本不做 prepare 校验,问题延迟到运行时,配合测试与日志才能发现。
原理流程
- 编写带宏的查询,触发 cargo 编译。
- 宏环境连库 prepare(或读离线缓存)。
- 数据库返回解析/绑定错误,宏转为编译错误并标注 SQL 片段。
- 修复 SQL 或 schema 后重新编译;函数版本问题在运行期
Error::Database中体现。
代码或图示
编译期(宏)
SQL 文本 → prepare → 数据库解析 → 列/类型校验 → 生成 Rust 类型
运行时(函数)
SQL 文本 → 下发服务端 → 执行 → 错误经 sqlx::Error 返回
常见误区
- 以为宏报错是 Rust 类型问题,实际是数据库拒绝了 SQL。
- 离线元数据没更新,编译通过但线上库 schema 已变。
追问
- 离线模式下宏还能查出列名拼错吗?答:能比对缓存元数据;但缓存本身过期时,新列名错误可能查不出来。
- 如何在 CI 保证宏校验不过期?答:CI 跑
cargo sqlx prepare --check,元数据与代码一起提交。
04.4.8.1-023 宏生成记录的字段命名与可空性规则是什么?
一句话结论
字段名取结果列名(含别名),Rust 标识符不合法时宏做规范化;列可空则字段类型为 Option<T>,非空为 T;类型映射遵循后端类型到 Rust 类型的默认规则。
概念解释
数据库列的可空性来自 prepare 返回的元数据:允许 NULL 的列在宏结果里包一层 Option,避免取出空值时直接解引用panic。字段命名按列名转换为 Rust 习惯的标识符形式;若列名是关键字或含特殊字符,需要用别名规避。想把可空列当非空使用,应在 SQL 层 COALESCE 或在结构体里自行处理。
原理流程
- prepare 返回每列的类型 OID 与 nullability。
- 按类型映射表选 Rust 基础类型。
- 可空列在外层包
Option。 - 列名规范化为合法字段名,冲突时用别名区分。
代码或图示
let row = sqlx::query!(
"SELECT id, name, nickname FROM users WHERE id = $1", id
).fetch_one(&pool).await?;
// row.id: i64
// row.name: String
// row.nickname: Option<String>
常见误区
- 把可空字段当成非空类型直接用,编译期就会因
Option类型不匹配报错。 - 列名重复(多表同名列)不写别名,生成字段冲突。
追问
- 数据库标记可空但业务上不可能为 NULL,怎么取非空?答:SQL 用
COALESCE给默认值,或在代码里unwrap/ok_or显式处理。 - 字段名大小写怎么处理?答:以宏生成规则为准, camelCase 列建议用
AS别名对齐结构体。
04.4.8.1-024 FromRow derive 与手写实现分别适用什么场景?
一句话结论
常规结构体用 #[derive(FromRow)] 按列名映射即可;列名异构、需要按位置解码或做字段级转换时手写 FromRow 实现。
概念解释
derive 覆盖了大多数「结构体字段 = 结果列」的场景。复杂情况包括:列名与字段名无规则对应、需要把多个列合并成一个嵌套结构、解码后做二次校验或类型转换。手写实现时从 Row 取列,调用 row.try_get 并自行处理缺失与解码错误。FromRow 与 query_as/query_as! 配合使用。
原理流程
- 先尝试 derive,检查字段与列名是否对齐。
- 映射规则不满足时移除 derive,手写
impl FromRow。 - 逐列
try_get,失败时返回解码错误。 - 嵌套结构可在实现里递归调用内部类型的
FromRow。
代码或图示
use sqlx::{FromRow, Row};
#[derive(FromRow)]
struct User { id: i64, name: String }
struct Profile { display: String }
impl FromRow<'_, sqlx::postgres::PgRow> for Profile {
fn from_row(row: &sqlx::postgres::PgRow) -> sqlx::Result<Self> {
let first: String = row.try_get("first")?;
let last: String = row.try_get("last")?;
Ok(Profile { display: format!("{first} {last}") })
}
}
常见误区
- 把 serde 的
rename属性套到FromRow上:两套属性互不认识。 - 手写实现时忽略列不存在错误,直接
unwrap导致运行期 panic。
追问
FromRow的生命周期参数是什么含义?答:实现绑定行类型与借用生命周期,保证解码不持有超越行的引用;具体签名以 docs.rs 为准。- 同一结构体被不同后端复用时怎么办?答:按后端分别实现,或用
AnyRow抽象,注意公共类型子集。
04.4.8.1-025 多语句批处理与流式查询的边界在哪里?
一句话结论
简单 unprepared 查询可一次发送多条语句并取所有结果集;高层 query API 走预处理语句缓存并按行流式读取;批处理写操作建议用多行 VALUES 单条 execute,不要依赖多语句拼接。
概念解释
SQLx 区分高层预处理查询与简单查询路径:高层 API 自动 prepare 并按连接缓存语句;简单查询路径支持批量执行多条语句。生产代码里动态多语句拼接有注入与权限风险,批量插入优先 INSERT ... VALUES (...), (...), ...。流式读取通过 fetch 返回 Stream,逐行从网络解码,避免一次性落内存。
原理流程
- 判断是单条读、单条写还是批量写。
- 批量写构造多行 VALUES,一次
execute。 - 大结果集用
fetch流式消费。 - 多语句仅在可信 DDL/初始化脚本场景使用。
代码或图示
// 批量插入:多行 VALUES
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
"INSERT INTO users (name) VALUES "
);
qb.push_values(names, |mut b, name| { b.push_bind(name); });
qb.build().execute(&pool).await?;
常见误区
- 用字符串拼接把多条 SQL 拼成一条执行,既难绑定参数又扩大注入面。
- 误以为流式
fetch会自动把连接归还:流未耗尽时连接仍被占用。
追问
- 预处理语句缓存在哪一层?答:按连接缓存,缓存容量与行为由连接选项控制,以文档为准。
- 流式消费到一半返回错误,连接怎么处理?答:丢弃流后连接回到池前会做可用性判定,坏连接被重建。
04.4.8.1-026 query! 宏的编译期校验是如何工作的?
一句话结论
编译到含宏的代码时,宏进程读取 SQL 文本与参数类型,连接开发数据库执行 prepare,由数据库解析 SQL 并返回列信息,宏据此生成 Rust 类型;这一步把 SQL 语法、表列存在性与类型可绑定性提前到编译期检查。
概念解释
校验主体是数据库本身,SQLx 不内置 SQL 解析器:宏只是把语句发给服务端做 prepared statement 解析。参数类型按绑定位置编码发送,数据库据此校验类型兼容。校验需要编译期环境可访问开发库;离线模式下改为读取 .sqlx 目录中缓存的 prepare 元数据,不再连库。
原理流程
- cargo 编译到宏调用,宏展开为构建期检查逻辑。
- 读取
DATABASE_URL,连接开发库(或走离线缓存)。 - 发送 prepare,数据库返回列名、类型、可空性。
- 宏生成对应 Rust 代码;prepare 失败转为编译错误。
- 正常编译产物运行时只做执行与解码。
代码或图示
源码 query!("SELECT id, name FROM users WHERE id = $1", id)
→ 编译期 prepare("SELECT ...", 参数类型)
→ 数据库返回列元数据
→ 生成记录 { id: i64, name: String }
→ 运行时 fetch_one 解码到记录
常见误区
- 以为 SQLx 本地解析 SQL 做静态检查:实际依赖服务端解析能力。
- 以为编译期校验覆盖所有运行期问题:数据约束冲突、连接故障仍在运行期暴露。
追问
- 没有开发库能否做编译期校验?答:不能连库时只能用离线元数据;两者都没有则宏无法生成类型。
- 校验发生在 cargo 的哪个阶段?答:宏展开在编译期,不是运行时;IDE 插件也会单独发起一次 prepare 以提供补全与报错。
04.4.8.1-027 离线模式解决什么问题?
一句话结论
离线模式让 query! 系列宏在编译期不连接数据库,改读本地缓存的 prepare 元数据,解决 CI、无库开发机、构建容器里没有数据库也能编译的问题。
概念解释
默认在线模式要求编译环境能访问开发库,流水线和干净检出的 CI 通常不挂数据库。离线模式把某次连库 prepare 的结果(SQL 哈希、列类型、可空性等)序列化到 .sqlx 目录并提交版本库;之后编译按缓存对账,不发网络请求。代价是缓存必须随 schema 演进及时刷新,否则校验依据过期。
原理流程
- 开发机连库跑一次
cargo sqlx prepare,生成离线元数据。 - 提交
.sqlx目录到版本库。 - CI 或无库环境设置离线模式,宏只读缓存。
- schema 或 SQL 变更后重新 prepare 并提交更新缓存。
代码或图示
在线:宏 → 开发库 prepare → 生成类型
离线:宏 → .sqlx/<查询哈希>.json 缓存 → 生成类型
常见误区
- 认为离线模式等于「不校验 SQL」:仍按缓存元数据校验,只是数据源变成本地快照。
- 把
.sqlx加进.gitignore:CI 离线编译会直接失败。
追问
- 离线缓存什么时候必须刷新?答:改了 SQL 文本、表结构、列类型或可空性之后。
- 离线模式下新增一条宏查询会怎样?答:缓存里找不到该查询,按配置报错或回退尝试连库,取决于环境变量与配置。
04.4.8.1-028 cargo sqlx prepare 具体做了什么?
一句话结论
cargo sqlx prepare 编译工程并为每个 query! 宏收集 prepare 元数据,写入项目 .sqlx 目录,供离线编译使用;它是 sqlx-cli 提供的 cargo 子命令入口。
概念解释
prepare 流程触发一次带宏检查的构建,把每条宏 SQL 的 prepare 结果落盘。默认目录为项目根的 .sqlx/,按查询内容哈希组织文件。执行前需要本地有可连的开发库,DATABASE_URL 指向它。prepare 之后 .sqlx 目录应当随源码一起提交,保证他人与 CI 能离线复现相同校验。
原理流程
- 安装 sqlx-cli,设置
DATABASE_URL指向开发库。 - 在工程根执行
cargo sqlx prepare。 - 工具编译并收集所有宏查询的元数据。
- 元数据写入
.sqlx/。 - 检查 git 状态,把新增/变更的缓存文件一并提交。
代码或图示
cargo install sqlx-cli
# 确保 DATABASE_URL 指向开发库
cargo sqlx prepare
常见误区
- 把
sqlx migrate命令与cargo sqlx prepare混为一谈:前者管 schema 版本,后者管宏缓存。 - prepare 后不检查
.sqlx变更,新查询的缓存没进版本库。
追问
prepare会不会修改数据库?答:只做 prepare 元数据收集,不执行 DDL/DML;结构变更走 migrate。- 多 crate workspace 里缓存放在哪?答:以当前版本工具约定为准,通常与含宏的 crate 对应;不确定时查 sqlx-cli 文档。
04.4.8.1-029 cargo sqlx prepare --check 在 CI 里怎么用?
一句话结论
--check 模式只比对现有 .sqlx 缓存与当前宏查询是否一致,不一致就以非零退出码失败,用于 CI 拦截「改了 SQL 却没刷新离线元数据」的提交。
概念解释
常规 prepare 会写缓存文件,--check 不写盘,只报告差异。CI 流水线在构建前跑一次:如果开发者本地改了 query! 但忘记 prepare 并提交 .sqlx,check 失败,防止离线缓存落后于源码。这与 cargo fmt --check、cargo clippy 同属提交前质量门禁。
原理流程
- CI 检出代码,
.sqlx已在版本库。 - 执行
cargo sqlx prepare --check(离线环境亦可)。 - 工具逐条对账宏查询与缓存。
- 一致则通过;不一致列出过期/缺失查询并退出非零。
- 修复方式:本地连库 prepare,提交更新后的缓存。
代码或图示
CI 步骤:
1. cargo sqlx prepare --check
2. cargo build / cargo test
常见误区
- CI 里只跑
cargo build不开 check:缓存过期不会被门禁发现。 - 用普通 prepare 替代 check:普通命令会写盘掩盖差异,失去拦截意义。
追问
- check 需要连数据库吗?答:离线缓存齐全时不需要;行为以当前版本为准。
- check 报某查询缺失,开发者本地怎么做?答:连开发库执行
cargo sqlx prepare,把.sqlx变更提交。
04.4.8.1-030 SQLX_OFFLINE 环境变量如何控制在线与离线?
一句话结论
SQLX_OFFLINE=true 强制宏只读离线缓存、不尝试连库;未设置或为 false 时优先连开发库 prepare,连不上再按缓存/报错处理;它是编译期行为开关,不影响运行时连接。
概念解释
该变量作用于宏的编译期解析路径,用于在 CI、干净环境里强制离线,避免环境里残留的 DATABASE_URL 指向不可达库导致编译卡住。反过来,本地开发想强制刷新校验时要确保不处于离线状态。运行时建池读的仍是 DATABASE_URL,与这个开关无关。
原理流程
- 编译期宏读取
SQLX_OFFLINE。 - 为真:直接查
.sqlx缓存,不发起网络连接。 - 为假:连接
DATABASE_URL对应数据库 prepare。 - 运行期忽略该变量,按连接串建池。
代码或图示
# 强制离线编译
$env:SQLX_OFFLINE = "true"
cargo build
常见误区
- 以为
SQLX_OFFLINE控制运行时是否连库:它只影响编译期宏路径。 - 本地忘记取消离线,schema 已变仍用旧缓存编译。
追问
- 离线缓存缺失时
SQLX_OFFLINE=true会怎样?答:宏报错并提示离线元数据缺失,需本地 prepare。 - 能否在
.env里设这个变量?答:可以作为环境约定,但 CI 通常显式注入,避免本地配置污染流水线。
04.4.8.1-031 为什么 .sqlx 目录要提交进版本库?
一句话结论
.sqlx 是离线编译与 CI 校验的输入,不提交则他人检出代码后宏无法离线生成类型,prepare --check 也失去对账基准;它属于构建元数据而非生成物,应当入库。
概念解释
与 target/ 不同,.sqlx 不依赖本机工具链产物,而是源码查询的 prepare 快照,必须随代码演进保持一致。提交它的代价是多一批 JSON 文件,收益是干净环境可复现编译与校验。仓库策略上要把它纳入代码评审:缓存变更与 SQL/schema 变更一起看。
原理流程
- 本地 prepare 后
.sqlx出现新增或修改文件。 - 评审确认变更与 SQL 改动对应。
- 随源码 commit 入库。
- 他人与 CI 检出后直接离线编译或 check。
代码或图示
不应提交:target/、_site/、真实 .env
应当提交:.sqlx/ 离线元数据、migrations/ 迁移脚本
常见误区
- 把
.sqlx当构建产物加入.gitignore。 - 只提交
.rs不提交缓存变更,导致 CI 离线失败。
追问
- 缓存文件太大怎么办?答:按后端与 feature 裁剪,避免同时开用不到的后端;具体目录结构以当前版本为准。
- 回退代码后缓存会冲突吗?答:缓存按查询哈希组织,回退后旧查询哈希对应文件仍在;多余文件一般不影响编译,必要时重新 prepare 整理。
04.4.8.1-032 schema 变更后离线元数据为什么会过期?
一句话结论
缓存保存的是某次 prepare 时的列名、类型与可空性快照;表结构或列类型改了之后,快照与真实库不一致,宏继续按旧快照生成类型,可能编译通过但运行期解码失败,必须重新 prepare。
概念解释
典型过期场景:加列、删列、改列类型、把列从可空改非空、改枚举值。迁移应用到开发库后,未刷新的 .sqlx 仍是旧结构。离线模式不会主动连库发现差异,只有重新 prepare 才能拿到新元数据。prepare --check 可以在 CI 暴露这种滞后。
原理流程
- 迁移改了表结构并应用到开发库。
- 代码中的宏查询尚未重新 prepare。
- 离线编译按旧缓存生成类型。
- 运行期真实列类型/可空性与生成类型不符,解码报错。
- 修复:连库
cargo sqlx prepare并提交新缓存。
代码或图示
旧缓存:nickname: Option<String>
迁移后:nickname NOT NULL
未刷新 → 代码按 Option 解码 → 运行期行为与实际 schema 脱节
常见误区
- 只跑了数据库迁移,忘记刷新
.sqlx。 - 以为 CI 在线构建能自动纠正缓存:CI 若走离线模式不会连库纠错。
追问
- 怎么发现缓存过期?答:
cargo sqlx prepare --check报差异;运行期出现类型解码错误也要回头核对缓存。 - 改了列名但 SQL 里写了别名,缓存还会过期吗?答:prepare 仍按新列结构解析,缓存哈希与元数据会变,需要重新 prepare。
04.4.8.1-033 新增或修改一条 query! 后的完整流程是什么?
一句话结论
改 SQL → 确保开发库 schema 最新 → 本地编译触发在线 prepare → cargo sqlx prepare 刷新缓存 → 提交源码与 .sqlx → CI 跑 check 与构建。
概念解释
这套流程保证「代码、迁移、离线缓存」三者一致。任何一步跳过都会留下隐患:schema 没更新会 prepare 失败;缓存没提交会让 CI 离线失败;不跑 check 会让过期缓存溜进主干。团队约定里应把 prepare 作为改宏查询后的固定动作。
原理流程
- 编写或修改
query!/query_as!查询。 - 应用相关迁移到本地开发库。
- 本地编译,确认宏校验通过、类型正确。
- 执行
cargo sqlx prepare更新.sqlx。 - 评审并提交源码与缓存;CI 执行
--check与构建。
代码或图示
sqlx migrate run
cargo build
cargo sqlx prepare
git add .sqlx src
常见误区
- 先提交代码再补缓存,中间状态 CI 失败。
- 多人并行改查询,缓存合并冲突时直接选一边:应重新 prepare 解决。
追问
- 缓存合并冲突怎么处理?答:保留双方源码,连库重新
cargo sqlx prepare生成合并后的缓存,不要手动编辑 JSON。 - 只改注释不改 SQL 会刷新缓存吗?答:SQL 文本哈希不变则缓存不变;注释不影响 prepare 内容。
04.4.8.1-034 离线模式下宏还能校验什么,不能校验什么?
一句话结论
离线模式仍能比对 SQL 文本与缓存元数据、检查列名/类型/可空性是否与快照一致;不能校验快照之外的真实库状态,也无法发现缓存生成之后线上 schema 的漂移。
概念解释
校验依据从「实时服务端」换成「本地快照」:快照里有的列与类型对账照常进行;快照本身的时效性不被验证。新查询缺缓存、SQL 与缓存哈希不符都会报错;但缓存生成后开发库又改了结构,离线编译察觉不到。因此离线模式不能替代对 schema 一致性的流程管控。
原理流程
- 宏按 SQL 文本哈希查
.sqlx缓存。 - 命中:按快照列元数据生成类型并对账参数类型。
- 未命中:报错要求 prepare。
- 快照与真实库是否漂移:离线模式不检查。
代码或图示
离线可校验:SQL 与缓存是否匹配、列名/类型/可空性对账
离线不可校验:缓存生成后库端 schema 变化、服务端新版本语法兼容性
常见误区
- 以为离线编译通过就等于 SQL 在当前库里合法。
- 在离线模式下排查「编译过但运行报错」,反复改 Rust 类型而不刷新缓存。
追问
- 如何兼顾离线速度与真实校验?答:CI 中除离线 check 外,用测试库跑真实查询与集成测试。
- 缓存里保存了哪些信息?答:查询 SQL、参数与结果列的类型/可空性等 prepare 结果;具体字段结构以
.sqlx实际文件与文档为准。
04.4.8.1-035 开发库与生产库 schema 不一致有什么风险?
一句话结论
宏按开发库校验,生产库结构不同会让编译期安全承诺失效:索引、约束、列类型、可空性差异可能在运行期才暴露,甚至只有特定数据量下触发。
概念解释
常见差异包括:开发库缺迁移、列类型宽松、唯一索引未建、默认值不同、扩展(如 Postgres 扩展)未安装。编译期校验只反映开发库状态,生产执行时可能遇到约束冲突、类型无法解码、功能不可用。治理手段是迁移纳入版本管理、测试库与生产同构、CI 用临时库跑迁移后测试。
原理流程
- 开发库通过迁移保持与目标环境同构。
- 宏校验基于该结构生成类型。
- 部署前在测试库执行同一批迁移。
- 集成测试暴露结构与约束问题。
- 生产发布时结构已是最新。
代码或图示
迁移脚本 → 开发库(宏校验)→ 测试库(集成测试)→ 生产库
三者结构必须来自同一批 migrations/
常见误区
- 直接在生产库手动改表结构,不走迁移脚本。
- 开发库为了调试放宽约束(去掉唯一索引),问题被带到生产。
追问
- 怎么检测环境间结构漂移?答:对比各库
information_schema/系统目录,或让迁移在所有环境按同一版本记录执行。 - 跨环境类型差异(如字符集)影响解码吗?答:会,字符集与排序规则差异可能导致字符串解码或比较异常,需在环境配置层对齐。
04.4.8.1-036 宏连不上数据库且离线元数据缺失时会报什么错?
一句话结论
编译期宏既无法连接 DATABASE_URL 对应库、又在 .sqlx 找不到缓存时,编译失败并提示需要建立数据库连接或运行 cargo sqlx prepare;错误归属为宏校验错误,而不是普通运行时错误。
概念解释
报错信息通常包含连接失败原因(DNS、认证、拒绝连接)或离线元数据缺失提示。排查顺序:先确认 DATABASE_URL 是否存在且可达,再确认是否应离线构建、.sqlx 是否完整。这类错误发生在 cargo build 阶段,不要去运行日志里找。
原理流程
- 编译到宏调用,读取环境变量与离线配置。
- 在线尝试连接失败,记录连接错误。
- 回退查离线缓存,未命中。
- 宏终止编译并给出提示。
- 修复连接或补齐缓存后重新编译。
代码或图示
cargo build
→ query! 宏准备校验
→ 连接 dev DB 失败 / 离线缓存缺失
→ 编译错误:无法完成查询校验
→ 处理:检查 DATABASE_URL,或执行 cargo sqlx prepare
常见误区
- 在运行日志里找编译期宏错误。
- 看到连接错误就改运行时池配置:先区分是编译期宏连接还是运行期连接。
追问
- 如何让编译明确走离线而不尝试连库?答:设置
SQLX_OFFLINE=true,避免残留环境变量引发长等待。 - 密码错误导致的连接失败怎么定位?答:先手动用 CLI 或客户端连同一连接串,确认凭证与网络。
04.4.8.1-037 prepare 之后改了 SQL 却没重新 prepare 会发生什么?
一句话结论
离线编译会按旧缓存对账,SQL 文本哈希已变,通常直接报查询未在缓存中找到;在线编译则重新 prepare 并覆盖旧结果,若此时不刷新提交,他人离线构建又会失败。
概念解释
缓存按查询内容关联:SQL 文本一改,对应哈希就变。未重新 prepare 时,离线模式找不到新哈希;在线模式虽然本地能编译,但仓库里的 .sqlx 仍是旧版本。两种情况都需要把 prepare 作为 SQL 改动后的收尾动作。
原理流程
- 修改宏内 SQL 文本。
- 离线编译:新哈希无缓存,宏报错。
- 在线编译:本地重新 prepare 成功,但缓存文件未更新入库。
- 他人检出后离线构建失败。
- 补跑
cargo sqlx prepare并提交。
代码或图示
改 SQL → 在线本地编译通过(看似正常)
→ 忘记 prepare
→ CI 离线:缓存哈希不匹配,构建失败
常见误区
- 以为本地在线编译通过就完成了改动。
- 只改了 WHERE 条件不认为影响缓存:任何 SQL 文本变化都改变哈希。
追问
- 旧缓存文件会残留吗?答:被替换的查询对应文件可能保留在目录中,下次 prepare 会整理;不影响编译,但目录会随版本增长。
- 批量重构 SQL 后怎么快速核对?答:跑
prepare --check,列出所有未对齐查询。
04.4.8.1-038 多后端或多 feature 组合下离线元数据如何存放?
一句话结论
离线缓存按启用的后端/feature 组合分别记录 prepare 结果;同时开启多个后端时,缓存需要覆盖每个组合的校验,具体目录组织与命名以 sqlx 当前版本文档为准(待确认:跨 feature 缓存是否分目录隔离)。
概念解释
宏校验结果与后端方言、启用类型 feature 有关:同一条 SQL 在 Postgres 与 MySQL 下列类型映射可能不同。工程上推荐一个服务只绑定一个后端,避免缓存矩阵膨胀。若确需多后端编译,要在每种 feature 组合下分别 prepare,并确认 .sqlx 内容完整。
原理流程
- 确定需要编译的 feature 组合。
- 切换到对应后端连接串执行 prepare。
- 检查缓存覆盖该组合的全部宏查询。
- 多组合时重复 prepare,避免某组合缺缓存。
代码或图示
待确认:.sqlx 是否按 feature/后端分子目录隔离;
验证方式:docs.rs/sqlx 当前版本离线模式章节,或 prepare 后查看目录结构。
常见误区
- 用 Postgres 的缓存去离线编译 MySQL 构建:方言与类型映射对不上。
- 临时加 feature 调试后不还原,缓存与默认 feature 配置脱节。
追问
- 库只服务一种数据库还需要考虑多缓存吗?答:不需要,单后端单连接串 prepare 即可。
- feature 增减后旧缓存怎么清理?答:重新 prepare 生成当前配置所需缓存;历史文件处理以工具行为为准。
04.4.8.1-039 SQL 列类型到 Rust 基础类型如何映射?
一句话结论
常见映射:整数按宽度对应 i16/i32/i64,浮点 f32/f64,布尔 bool,文本 String,字节 Vec<u8>,可空列外层包 Option;具体映射随后端类型与启用的类型 feature 变化。
概念解释
映射由解码层按后端列类型 OID/类型名选择 Rust 类型。数据库整数可能有 signed/unsigned 差异,字符串有 text/varchar/char,时间与 JSON 需要额外 feature。编写结构体时先对齐列类型,解码错误通常就是 Rust 类型与 SQL 类型对不上。完整对照表以 docs.rs 各后端「类型映射」章节为准。
原理流程
- 查看表结构的列类型与可空性。
- 按映射表选 Rust 基础类型。
- 可空列加
Option。 - 编译或解码期校验,不匹配返回
Decode错误。
代码或图示
int2/smallint → i16
int4/integer → i32
int8/bigint → i64
boolean → bool
text/varchar → String
bytea/BLOB → Vec<u8>
numeric/decimal → bigdecimal::BigDecimal(需对应 feature)
常见误区
- 把数据库
bigint映射成i32:宽位不匹配,解码失败。 - 忽略无符号类型在 Rust 侧的对应方式,按有符号类型取值。
追问
- 金额字段用
f64还是定点类型?答:金额避免浮点,用BigDecimal或定点整数分单位存储,具体以后端与 feature 支持为准。 - 字符串列允许 NULL 时结构体怎么写?答:字段为
Option<String>,不要写String。
04.4.8.1-040 可空列为什么映射成 Option<T>?
一句话结论
数据库 NULL 没有对应的非空 Rust 值,解码层只能用 Option 表达「可能为空」;非空列在元数据上标记 NOT NULL,宏/解码直接产出 T。
概念解释
这样设计把空值检查从运行期解引用提前到类型系统:编译器强制你在使用前判断 Some/None,避免 NULL 取数后直接解包 panic。列可空性来自 prepare 元数据;函数版本手写映射时也要主动用 Option 接收可空列。COALESCE 可以在 SQL 层把可空列变成非空默认值。
原理流程
- prepare 元数据标记列是否可空。
- 可空:生成/解码为
Option<T>。 - 取数时按
Option分支处理。 - 非空列误写
Option通常可兼容,可空列误写非空类型会解码失败。
代码或图示
#[derive(sqlx::FromRow)]
struct User {
id: i64,
name: String, // NOT NULL
nickname: Option<String>, // 允许 NULL
}
常见误区
- 可空字段直接
unwrap:把数据库空值变成运行期 panic。 - 以为结构体里写
Option就能让非空列变可空:映射方向由列元数据决定。
追问
- 查询用了
COALESCE(nickname, ''),字段还需要Option吗?答:结果不再可能为 NULL,可按非空String接收,以 prepare 元数据为准。 - 两表 join 后外表列为空怎么标?答:左连接外表列可空,对应字段用
Option。
04.4.8.1-041 Uuid 类型怎么映射,需要哪个 feature?
一句话结论
启用 uuid feature 后,SQLx 支持把 Postgres uuid、MySQL/SQLite 的对应字符/字节列与 Rust uuid::Uuid 互相编解码;主键常用 Uuid 作为应用层标识。
概念解释
Uuid 类型来自 uuid crate,SQLx 通过 Type/Encode/Decode 实现接入。Postgres 原生 uuid 类型直接映射;其它后端若用字符或二进制存储,列类型需与编解码约定一致。结构体字段类型写 Uuid(非空)或 Option<Uuid>(可空)。版本(v4 等)由应用生成,与数据库映射无关。
原理流程
Cargo.toml开启uuidfeature,并引入uuidcrate。- 表主键定义为对应后端 UUID 列类型。
- 结构体字段写
Uuid。 - 插入时绑定
Uuid值,查询时解码为Uuid。
代码或图示
sqlx = { version = "0.8", features = ["runtime-tokio-rustls", "postgres", "uuid"] }
uuid = { version = "1", features = ["v4", "serde"] }
use uuid::Uuid;
#[derive(sqlx::FromRow)]
struct Account { id: Uuid, name: String }
常见误区
- 开启了 SQLx 的
uuidfeature 却没引uuidcrate,类型名找不到。 - MySQL 用字符列存 UUID 却按二进制解码,格式不匹配。
追问
- UUID 作主键有什么取舍?答:无序插入可能影响聚簇索引页分裂,存储空间比自增大;权衡以业务写入模式为准。
- 字符串形式的 UUID 列能直接解码成
Uuid吗?答:以后端类型映射支持为准;不支持时先解String再Uuid::parse_str。
04.4.8.1-042 chrono 与 time 两套日期时间 crate 怎么选?
一句话结论
SQLx 同时提供 chrono 与 time 两套类型 feature,二选一接入项目现有时间体系;两者都启用时宏的类型选择优先级与文档为准,避免混用导致解码歧义。
概念解释
chrono 是生态中历史最久的时间库,time 是较新的替代品。SQLx 各自提供对应类型编解码。工程选型跟随项目既有依赖:项目已用 chrono 就开 chrono,新项目可评估 time。不要在同一模型里混用两套时间类型,跨边界转换要显式进行。日期时间列的时区语义(带时区/不带时区)比 crate 选择更影响正确性。
原理流程
- 盘点项目现有时间依赖。
- 在 SQLx 开启对应 feature。
- 结构体字段使用对应 crate 类型。
- 按列类型(timestamp/ timestamptz/date/time)选择精确到字段的类型。
代码或图示
features = ["runtime-tokio-rustls", "postgres", "chrono"]
# 或
features = ["runtime-tokio-rustls", "postgres", "time"]
常见误区
- 两个 feature 都开,字段类型在两者间摇摆,编译报类型歧义。
- 忽略时区:把带时区列解码成无时区类型,丢失偏移信息。
追问
DateTime<Utc>与NaiveDateTime分别对应什么列?答:前者适合带时区列,后者适合无时区本地时间列;具体对应以后端文档为准。- 跨服务传递时间用什么格式?答:对外序列化为 UTC 时间字符串,内部再解码为对应本地类型。
04.4.8.1-043 JSON/JSONB 列如何映射到 Rust 类型?
一句话结论
启用 json feature 后,JSON 列可解码为 sqlx::Json<T>(包裹实现 serde::Serialize/Deserialize 的结构体)或 serde_json::Value;Postgres 常用 jsonb,MySQL/SQLite 用 JSON/文本列,方言细节有差异。
概念解释
Json<T> 是 newtype 包装,取出 .0 得到 T;Value 适合结构不固定的动态 JSON。编解码依赖 serde:T 要实现 Serialize/Deserialize。把 JSON 整列映射为结构体,避免在应用层再做字符串解析。注意 JSON 列内的查询条件走后端 JSON 函数,不属于 Rust 映射层。
原理流程
- 开启
jsonfeature,引入 serde 与对应结构体。 - 表列定义为后端 JSON/JSONB 类型。
- 结构体字段写
Json<T>或Value。 - 写入时绑定包装值,读出时解构使用。
代码或图示
use sqlx::types::Json;
use serde::{Serialize, Deserialize};
#[derive(Serialize, Deserialize)]
struct Meta { theme: String }
#[derive(sqlx::FromRow)]
struct Article {
id: i64,
meta: Json<Meta>,
}
// 读取
let meta: Meta = row.meta.0;
常见误区
- 字段直接写
Meta而不包Json:解码类型不匹配。 - 把 JSON 列当字符串读出再手动
from_str,丢掉类型安全。
追问
serde_json::Value什么时候用?答:列结构不稳定、需要动态遍历字段时;结构稳定时优先Json<T>。- JSON 列建索引/查询怎么处理?答:依赖后端 JSON 表达式与索引,SQLx 只负责存取映射。
04.4.8.1-044 Postgres 枚举如何映射到 Rust 枚举?
一句话结论
Postgres 原生 enum 可通过 sqlx::Type derive(配合相应 feature)映射到 Rust 枚举;Rust 枚举变体名与数据库枚举值对齐,写入绑定、读出解码都走同一映射。
概念解释
PG enum 是数据库内独立类型,建表时 CREATE TYPE ... AS ENUM (...)。SQLx 的 derive 读取类型元数据生成映射;变体命名要与枚举标签一致,命名风格差异需用属性调整。无法映射的取值会在解码期报错。MySQL/SQLite 没有同等级原生 enum,通常用字符串或整数列表达。
原理流程
- 迁移中创建 PG enum 类型并用于列。
- Rust 枚举 derive
Type(及必要的 Encode/Decode)。 - 变体名与枚举值对齐。
- 查询解码为 Rust 枚举,写入绑定枚举值。
代码或图示
#[derive(sqlx::Type, Debug, Clone, Copy)]
#[sqlx(type_name = "order_status")]
enum OrderStatus { Pending, Paid, Shipped }
常见误区
- Rust 变体用 camelCase 而库值是 snake_case,未做映射导致解码失败。
- 数据库新增枚举值后,Rust 枚举未加变体,读到新值解码报错。
追问
- 枚举映射需要哪个 feature?答:通常依赖
derive与对应后端 feature;具体 derive 可用性以 docs.rs 当前版本为准。 - 枚举值改名怎么办?答:迁移要处理旧值转换,Rust 侧同步变体并重新 prepare。
04.4.8.1-045 MySQL/SQLite 下枚举一般用什么表示?
一句话结论
MySQL 有 ENUM 列类型,SQLite 无原生枚举;工程上更常见的做法是用字符串列或整数列在应用层用 Rust 枚举约束,避免后端方言绑定过深。
概念解释
MySQL ENUM 在 schema 层约束取值,SQLx 对其映射支持以文档为准;SQLite 只有亲和类型,枚举完全靠应用层保证。跨后端项目倾向统一用 TEXT 列存枚举标签,Rust 枚举负责编解码校验。这样迁移到其它后端时列结构不用改。
原理流程
- 确定后端是否有原生枚举类型。
- 原生可用则按原生映射;否则选字符串/整数列。
- Rust 枚举实现序列化/解码到列表示。
- 非法值在解码层转换为错误或默认值。
代码或图示
Postgres:原生 enum 类型 + sqlx::Type 映射
MySQL:ENUM 列或 VARCHAR,映射方式以文档为准
SQLite:TEXT/INTEGER,应用层枚举约束
常见误区
- 把 PG 原生 enum 方案照搬到 SQLite,列类型不存在。
- 整数枚举不记录取值含义,后续维护困难。
追问
- 字符串枚举如何防止脏数据写入?答:在应用层枚举校验,必要时数据库加 CHECK 约束。
- 跨后端模型复用同一枚举可行吗?答:可行,前提是列表示统一(如都用 TEXT),映射层按后端分别适配。
04.4.8.1-046 自定义类型如何实现 Type、Encode、Decode?
一句话结论
常用 newtype 或枚举直接 derive 相关 trait;类型需要特殊编解码规则时手写实现 Type(声明后端类型)、Encode(写入绑定)、Decode(读取转换),三者配合完成映射。
概念解释
Type 声明 Rust 类型对应哪个后端 SQL 类型;Encode 负责把值编码进绑定参数;Decode 负责从行列值还原为 Rust 值。derive 覆盖标准映射;手写场景包括:自定义金额类型、包装加密值、把内部结构映射到二进制/文本列。实现要考虑可空性与错误转换。
原理流程
- 判断标准 derive 是否满足列映射。
- 不满足时声明结构体/枚举并手写三个 trait。
Type绑定后端 SQL 类型元数据。Encode写值,Decode读值并处理失败。- 在查询中作为字段或绑定参数使用。
代码或图示
struct Money(i64);
// 标准场景优先 derive;以下仅示意为手写边界,
// 具体 trait 方法签名与关联类型以 docs.rs 当前版本为准。
常见误区
- 只实现
Encode忘了Decode,能写不能读。 - 手写解码不处理 NULL,对可空列直接解包导致 panic。
追问
- 外部 crate 类型无法 impl trait(孤儿规则)怎么办?答:用 newtype 包装本地类型,在包装上实现 trait。
- 自定义类型要进宏校验需要什么?答:确保其实现的映射类型在后端存在,宏才能对账参数与列类型。
04.4.8.1-047 Vec<u8>、bytea、BLOB 如何映射?
一句话结论
二进制列在 Rust 侧通常映射为 Vec<u8>,读取也可用 &[u8] 视图;Postgres 为 bytea,MySQL/SQLite 为 BLOB/二进制类型,大字段要考虑流式与内存占用。
概念解释
二进制内容(图片字节、序列化负载、文件片段)走字节列。Vec<u8> 拥有所有权,适合结构体字段;借用切片仅在行存活期间有效。大对象不建议整列加载进内存,应分块或落盘。二进制与文本列的编解码路径不同,不要把字节列当字符串解码。
原理流程
- 表列定义为后端二进制类型。
- 结构体字段写
Vec<u8>(或按文档使用字节类型)。 - 写入绑定字节切片,读出得到
Vec<u8>。 - 大对象评估内存与分块策略。
代码或图示
#[derive(sqlx::FromRow)]
struct Attachment { id: i64, payload: Vec<u8> }
sqlx::query("INSERT INTO attachments (payload) VALUES ($1)")
.bind(&bytes[..])
.execute(&pool)
.await?;
常见误区
- 二进制列解码成
String:非 UTF-8 内容解码失败。 - 数据库存大文件(如整图)而应用一次性
fetch_all:内存峰值过高。
追问
- 大文件在数据库里的取舍?答:大对象通常存对象存储,库里只存引用;数据库内大字段要评估行宽与缓存影响。
- 字节列可空怎么写?答:字段为
Option<Vec<u8>>。
04.4.8.1-048 numeric/decimal 与 f64 如何取舍?
一句话结论
金额、计量等要求精确小数的字段用定点类型(如 BigDecimal,需对应 feature),不要用 f64;f64 只适合可容忍误差的科学计算与统计场景。
概念解释
浮点二进制表示无法精确表达十进制小数,累加后产生舍入误差,财务场景不可接受。数据库 numeric/decimal 是定点类型,Rust 侧对应 BigDecimal(或项目约定的定点类型)。启用对应 feature 后编解码自动完成;若未启用,可先读写字符串/整数再转换。选择前先确认后端列类型与 Rust 侧类型都精确。
原理流程
- 字段语义判断:金额/计费 → 定点;采样/统计 → 可浮点。
- 表列用
numeric/decimal。 - 开启定点类型 feature,结构体字段用对应类型。
- 序列化对外时明确精度与小数位。
代码或图示
features = ["runtime-tokio-rustls", "postgres", "bigdecimal"]
use bigdecimal::BigDecimal;
#[derive(sqlx::FromRow)]
struct Product { id: i64, price: BigDecimal }
常见误区
- 金额列用
double precision+f64,对账出现尾差。 - 定点类型未开 feature,编译找不到类型。
追问
- 不用
BigDecimal还有什么精确方案?答:用最小货币单位整数(分)存储,展示层换算;避免浮点参与累加。 numeric精度与标度在哪里定义?答:建表 DDL 中声明,解码后类型保留值,展示层按业务格式化。
04.4.8.1-049 日期时间精度与时区有哪些坑?
一句话结论
先分清列是带时区还是不带时区,Rust 类型与之对齐;跨服务、跨时区统一以 UTC 存储与传输,本地展示再转换;精度(秒/毫秒/微秒)由后端列类型决定。
概念解释
Postgres timestamp with time zone 存 UTC 瞬时点,timestamp without time zone 是本地墙上时间;MySQL/SQLite 语义各有差异。混用类型容易出现时区偏移错误、夏令时问题。应用内部统一 DateTime<Utc> 一类 UTC 类型,落库列语义保持一致;日志与 API 输出再格式化。
原理流程
- 确认表列时区语义与精度。
- 选择对应 Rust 时间类型(UTC 瞬时 / 无时区本地时间)。
- 业务内部统一 UTC 计算与传递。
- 展示层按用户时区转换。
代码或图示
timestamptz → DateTime<Utc>(瞬时时间)
timestamp → NaiveDateTime(无时区本地时间)
date → NaiveDate / chrono::NaiveDate 类
常见误区
- 把无时区列当带时区时间用,部署到不同时区后时间偏移。
- 序列化本地时间不带偏移,跨服务接收方误判时区。
追问
- 数据库服务器时区影响结果吗?答:不带时区列的解释受会话/服务器时区影响;带时区列按 UTC 存储,影响较小。
- 历史时间迁移要注意什么?答:记录原始时区信息,转换时避免重复偏移。
04.4.8.1-050 类型解码失败在哪个阶段暴露?
一句话结论
宏路径下列类型对账在编译期;实际值解码失败(值与 Rust 类型不符、空值进非空字段)发生在取行阶段,返回 Decode 类 sqlx::Error。
概念解释
编译期只能校验类型与可空性元数据,无法检查具体行的值。运行时每行解码:字符串到数字转换失败、字节列转 UTF-8 失败、枚举值无对应变体、空值进非空字段,都会在 fetch_one/fetch_all/流的下一步返回错误。定位时先看错误类型与列名,再回表核对数据与类型映射。
原理流程
- 编译期完成 SQL 与类型元数据对账。
- 运行期服务端返回结果行。
- 解码层逐列按目标类型转换。
- 转换失败返回
Decode错误,携带列名与原因。 - 业务层映射为应用错误或记录脏数据。
代码或图示
编译期:SQL/列/类型元数据对账
运行期:行 → 逐列 Encode/Decode → 解码失败 → sqlx::Error::Decode
常见误区
- 编译通过就认定数据读取一定成功:脏数据仍会触发解码错误。
- 解码错误笼统当成「数据库连接问题」处理。
追问
- 解码错误里能看到是哪一列吗?答:错误通常携带列名或索引,按
Error提供的字段排查;具体字段以当前版本 API 为准。 - 如何容忍个别脏数据?答:按需在映射层降级为默认值或记录异常行,不要全局吞掉解码错误。
04.4.8.1-051 为什么不能用 format! 把用户输入拼进 SQL?
一句话结论
用户输入进入 SQL 文本会被数据库当作语句的一部分解析,拼接引号、注释符或语句片段即可篡改查询逻辑;必须把值作为绑定参数下发,SQL 文本本身只由代码常量构成。
概念解释
参数化查询把「SQL 结构」与「参数值」分开传输:服务端先解析语句结构,再按占位符代入值,值永远不参与语法解析。format! 拼字符串则把值混进结构文本,输入里的引号、--、OR 1=1 都会改变语义。Rust 字符串安全只保证内存安全,不保证 SQL 注入安全。
原理流程
- 区分 SQL 片段(代码常量)与值(外部输入)。
- 片段直接写进查询文本。
- 值通过
bind或QueryBuilder::push_bind提交。 - 服务端解析结构后绑定值执行。
代码或图示
// 危险:输入进入 SQL 文本
let bad = format!("SELECT * FROM users WHERE name = '{}'", input);
// 安全:值走绑定
let rows = sqlx::query("SELECT * FROM users WHERE name = $1")
.bind(input)
.fetch_all(&pool)
.await?;
常见误区
- 以为转义引号就能安全拼接:转义规则随后端方言变化,遗漏即出漏洞。
- 内部系统、后台接口就不防注入:后台账号权限同样可被利用。
追问
- 存储过程/动态执行语句里也有注入风险吗?答:有,只要外部输入进入被执行的 SQL 文本就存在风险。
- 绑定参数能防哪些攻击?答:防值层面的语句篡改;标识符与排序方向仍需另做白名单。
04.4.8.1-052 QueryBuilder 是什么,基本使用流程是什么?
一句话结论
QueryBuilder<DB> 是 SQLx 的动态 SQL 构造器:以可变对象逐步 push SQL 片段、push_bind 绑定参数,最终生成可执行查询;解决条件不确定、片段动态组合的场景。
概念解释
宏与固定函数查询要求 SQL 文本在编译期基本确定;QueryBuilder 在运行期按条件追加片段和参数,内部维护 SQL 文本与参数列表。它仍然通过绑定提交值,不把参数拼进文本。常用方法包括 push(片段)、push_bind(值)、push_values(批量 VALUES)、build_query/build_query_as(产出查询对象)。
原理流程
- 以基础 SQL 片段初始化
QueryBuilder。 - 按条件
push片段、push_bind参数。 - 需要分隔符时用
separated模式处理列表拼接。 - 调用
build_query_as等生成查询对象并执行。
代码或图示
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
"SELECT id, name FROM users WHERE 1=1"
);
if let Some(name) = name_filter {
qb.push(" AND name LIKE ").push_bind(format!("%{name}%"));
}
if let Some(min_age) = age_filter {
qb.push(" AND age >= ").push_bind(min_age);
}
let users = qb.build_query_as::<User>().fetch_all(&pool).await?;
常见误区
- 用
push直接追加用户输入的值:片段接口不做转义,必须走push_bind。 - 忘记基础片段里的
WHERE 1=1之类锚点,首个条件拼不出合法 WHERE。
追问
QueryBuilder生成的查询还能被宏校验吗?答:不能,动态文本在运行期下发,校验强度等同函数版本。- 用完的
QueryBuilder能复用吗?答:实例按单次查询构建;需要多次构建时新建实例,具体复用行为以文档为准。
04.4.8.1-053 QueryBuilder 的片段与参数是怎么分离提交的?
一句话结论
push 只写 SQL 文本片段,push_bind 把值追加到独立参数表;最终语句由片段拼出的模板加位置占位符组成,值随协议绑定发送,二者在生成阶段就已分离。
概念解释
构造器内部维护 SQL 字符串与绑定参数队列。每 push_bind 一次,模板里追加对应后端占位符,值进参数队列。执行时驱动按占位符顺序编码参数。这与手写 query("... $1 ...").bind(v) 是同一机制,只是片段组合由构造器完成。
原理流程
push片段追加到模板文本。push_bind追加占位符并登记参数。- 模板完成后,参数队列按占位符顺序排列。
build_query*产出查询对象,执行时下发模板与参数。
代码或图示
push(" AND age >= ")
push_bind(18)
→ 模板片段:AND age >= $1
→ 参数表:[18]
常见误区
- 以为
push_bind会把值转义后写进文本:它进参数表,不进入模板。 - 占位符编号随
push_bind顺序递增,中间插入片段不影响参数顺序对应。
追问
- 同一参数重复使用要绑定几次?答:按占位符出现次数绑定,或用后端命名参数能力;位置参数不做去重复用。
- 构造器支持
push_bind一个结构体吗?答:批量场景用push_values;单结构体展开写法以后端与文档为准。
04.4.8.1-054 可选过滤条件动态拼 WHERE 的标准写法是什么?
一句话结论
以 WHERE 1=1(或等价恒真条件)作为锚点,每个可选条件各自 push " AND 片段" 并 push_bind 对应值;条件为空就不追加,避免处理首个条件要不要写 AND 的分支。
概念解释
动态 WHERE 的麻烦在于条件数量不定、连接词难处理。恒真锚点让每个条件都能统一加 AND,代码分支只判断「加不加」。条件内部的值仍走绑定;列名、操作符来自代码白名单,不来自输入。这种写法可读性好,也便于测试各条件组合。
原理流程
- 初始化带恒真条件的查询模板。
- 逐个判断可选参数是否存在。
- 存在则追加
AND片段与绑定值。 - 最终执行查询,空条件集合等价于无过滤。
代码或图示
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
"SELECT id, name FROM users WHERE 1=1"
);
if let Some(q) = keyword {
qb.push(" AND name ILIKE ").push_bind(format!("%{q}%"));
}
if let Some(status) = status {
qb.push(" AND status = ").push_bind(status);
}
let users = qb.build_query_as::<User>().fetch_all(&pool).await?;
常见误区
- 首个条件单独判断「有没有 WHERE」,后续条件再拼 AND,分支容易漏。
- 把可选列名也做成参数传入,绕过白名单。
追问
WHERE 1=1在性能上有影响吗?答:优化器通常忽略恒真条件;保留它是为了代码结构,不是性能需要。- 条件很多时如何组织?答:把过滤参数收敛到一个结构体,构造器方法按字段批量处理。
04.4.8.1-055 IN 列表如何绑定参数?
一句话结论
IN 的值集合要展开成占位符列表再逐个绑定;Postgres 可用数组绑定配合 = ANY($1),MySQL/SQLite 通常展开多个 ?;空列表要单独处理成永假条件,不能生成空 IN ()。
概念解释
参数不能直接代表「一组值展开成多个占位符」,需要在构造器里生成与列表长度对应的占位符。Postgres 数组绑定是另一种路径:把数组作为单个参数传给 ANY。空列表在 SQL 里没有合法的 IN () 形式,应显式拼 AND 1=0 或在应用层提前返回空结果。
原理流程
- 接收 ID 列表,判断是否为空。
- 非空:生成占位符序列,逐个
push_bind。 - Postgres 可选数组 +
ANY路径。 - 空列表:拼接永假条件或短路返回空集。
代码或图示
let ids: &[i64] = &[1, 2, 3];
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
"SELECT id, name FROM users WHERE id IN ("
);
qb.push_values(ids.iter(), |mut b, id| { b.push_bind(*id); });
qb.push(")");
let users = qb.build_query_as::<User>().fetch_all(&pool).await?;
常见误区
- 把整个列表
format!拼进IN (...):既是注入面又类型不安全。 - 空列表生成
IN ():语法错误或语义错误。
追问
- 列表很长有什么风险?答:占位符数量与数据包大小上升,需分批处理;后端占位符上限也要留意。
ANY($1)绑定什么类型?答:Postgres 数组类型(如Vec<i64>),具体映射以后端文档为准。
04.4.8.1-056 表名、列名、排序方向为什么不能参数化?
一句话结论
绑定参数只能替换值,不能替换标识符与语法结构;表名、列名、排序方向、函数名都属于 SQL 结构,必须由代码白名单校验后内联,不能接受任意输入。
概念解释
数据库协议里参数占位符只绑定字面量值,标识符位置不接受参数。动态排序、动态选列是常见注入点:前端传 sort=name,若直接拼 ORDER BY {sort},传入 id; DROP TABLE ... 就出问题。正确做法是在代码里维护输入到合法标识符的映射,命中白名单才内联,否则拒绝。
原理流程
- 接收前端字段名/排序方向输入。
- 与代码内白名单映射表比对。
- 命中:取对应的合法列名/方向关键字内联进片段。
- 未命中:返回参数错误,不拼接 SQL。
代码或图示
let sort_col = match sort.as_str() {
"name" => "name",
"age" => "age",
_ => return Err(ApiError::InvalidSort),
};
let dir = match direction.as_str() {
"asc" => "ASC",
"desc" => "DESC",
_ => return Err(ApiError::InvalidSort),
};
qb.push(format!(" ORDER BY {sort_col} {dir}"));
常见误区
- 以为绑定参数能覆盖标识符:协议层就不支持。
- 白名单只校验排序方向,不校验列名。
追问
- 表名动态选择怎么防注入?答:同样走枚举映射到固定表名,不直接拼接请求字符串。
- 白名单映射放哪里?答:放在查询构造模块内,与 SQL 片段同处一层,便于审计。
04.4.8.1-057 参数化查询下仍可能出现注入的位置有哪些?
一句话结论
值绑定安全,但标识符、动态表/列名、排序方向、LIKE 模式构造、动态 SQL 函数调用、拼接进文本的存储过程参数仍是注入面;审计要逐一看「是否有外部输入进入 SQL 片段」。
概念解释
只要输入最终出现在 SQL 文本而非参数表,就脱离了参数化保护。典型位置:ORDER BY 字段、SELECT 列名、JOIN 表名、LIKE 通配处理、COLLATE 子句、后端 EXECUTE 动态语句。参数化降低了值层面风险,不能自动消除结构层面拼接风险。
原理流程
- 列出查询中所有来自外部的片段。
- 值类输入确认走
bind/push_bind。 - 结构类输入确认经过白名单映射。
- 无法归类的动态片段按高风险处理,重构为固定 SQL 分支。
代码或图示
安全:值 → bind
风险:表名 / 列名 / 排序方向 / 函数名 / 分隔符 → 必须白名单内联
常见误区
- 用了 ORM 或参数化就认为全链路无注入。
- 把列名校验放在前端,后端不复查。
追问
- LIKE 里的用户关键词本身安全吗?答:值可绑定,但
%/_通配符会改变匹配范围;按产品需要决定是否转义通配符。 - 审计时先看哪类代码?答:先找
format!、字符串push、字符串拼接出现在 SQL 构造处的位置。
04.4.8.1-058 LIKE/ILIKE 模糊匹配要做什么转义处理?
一句话结论
关键词作为值绑定,但其中的 %、_(以及后端转义符)是通配符,需要按产品预期决定转义;不要把用户输入直接包成 %{q}% 就忽略通配符语义。
概念解释
% 匹配任意串、_ 匹配单字符,用户输入本身含这些字符时会被当通配符,导致匹配范围扩大。严格关键词匹配应转义通配符并声明 ESCAPE;仅做宽松搜索时可接受通配行为,但要在产品说明里明确。转义规则随后端 LIKE 实现,不要假设通用转义字符。
原理流程
- 确认搜索是否允许通配符语义。
- 需要严格匹配:转义关键词中的通配符与转义符。
- 绑定转义后的值,必要时带
ESCAPE子句。 - 前后通配包裹由代码控制,不来自输入。
代码或图示
// 宽松搜索:值绑定,通配符由代码包裹
let pattern = format!("%{keyword}%");
qb.push(" AND name ILIKE ").push_bind(pattern);
// 严格搜索时:先转义 keyword 中的 % _ 与转义符,具体转义写法以后端文档为准
常见误区
- 关键词里的
_被当成单字符通配,返回意外结果。 - 转义规则按其它数据库方言照抄到当前后端。
追问
- 大小写不敏感用哪个?答:Postgres 用
ILIKE;MySQL 依赖列排序规则;SQLite 按编译选项与COLLATE,方言不同。 - 模糊搜索性能怎么保证?答:前后通配的 LIKE 难以走普通索引,大数据量考虑全文检索方案。
04.4.8.1-059 QueryBuilder 与宏查询混合使用的边界是什么?
一句话结论
同一条查询要么是固定文本走宏/固定函数,要么完全由 QueryBuilder 动态构造;不要尝试把宏返回的片段与运行时拼接结果混进同一条语句,校验边界与方言占位符都不一致。
概念解释
宏在编译期生成固定查询对象,QueryBuilder 在运行期产出查询对象,二者是不同构造路径。工程上按查询形态拆分:条件固定、字段固定的报表查询用宏拿类型校验;筛选条件动态的列表接口用构造器。混合场景(基础固定 + 少量动态)一般整体走构造器,宏不参与片段拼装。
原理流程
- 评估查询文本是否在编译期完全确定。
- 确定:选
query!/query_as!。 - 含运行时分支:整体用
QueryBuilder。 - 两种路径的结果分别映射到对应结构体。
代码或图示
固定查询 → query_as!(User, "SELECT ... WHERE id = $1", id)
动态查询 → QueryBuilder → build_query_as::<User>()
常见误区
- 想让宏「校验一部分」再拼接剩余片段:宏不输出可拼接片段。
- 动态构造后又套用宏生成的类型,可空性与列名未必对齐。
追问
- 构造器结果怎么映射结构体?答:
build_query_as::<T>(),T 实现FromRow。 - 动态查询还想保留编译期校验怎么办?答:无法两全;把动态条件收敛成固定分支,或在集成测试覆盖各组合。
04.4.8.1-060 动态排序与动态分页参数如何安全构造?
一句话结论
排序列与方向走白名单映射后内联;页码、页大小作为数值参数绑定,并限制页大小上限;分页偏移量由数值计算,不接受字符串拼接。
概念解释
动态排序是结构拼接,必须白名单;分页数值是值,走绑定。页大小要设上限防止一次拉取过大结果;页码偏移量公式 (page - 1) * size 在应用层计算并校验非负。深分页性能问题(大 offset)另由 keyset 分页解决,不属于注入范畴。
原理流程
- 解析排序字段与方向,白名单映射到合法列/方向。
- 校验页码与页大小,限制 size 上限。
- 计算偏移量,作为参数绑定。
- 构造
ORDER BY ... LIMIT ... OFFSET ...执行。
代码或图示
let limit: i64 = page_size.clamp(1, 100);
let offset: i64 = (page - 1) * limit;
qb.push(format!(" ORDER BY {sort_col} {dir} "))
.push(" LIMIT ").push_bind(limit)
.push(" OFFSET ").push_bind(offset);
常见误区
- 页大小不设上限,请求
size=100000打垮内存。 - 排序字段直接来自请求字符串内联。
追问
- 大偏移分页有什么优化?答:用 keyset/游标分页,按排序键继续翻页,避免扫描前导行。
- 排序键不唯一会导致分页重复/丢行吗?答:排序键需唯一(通常追加主键兜底),保证分页稳定。
04.4.8.1-061 批量插入多行 VALUES 怎么构造?
一句话结论
用 QueryBuilder::push_values 遍历值列表生成多行 VALUES (...), (...),每行字段逐个 push_bind,一次 execute 提交;避免循环单行插入造成多次往返。
概念解释
批量插入把多条记录合并成一条多值语句,减少网络往返与事务开销。push_values 接收迭代器,闭包里为每行绑定各列值。值列表为空时不要生成空语句,应提前返回或按业务跳过。多行插入仍受后端参数数量上限约束,超大列表要分批。
原理流程
- 收集待插入结构体或值列表。
- 非空时初始化
INSERT INTO table (cols) VALUES。 push_values遍历生成行元组与绑定。- 一次
execute,取受影响行数。
代码或图示
let mut qb = sqlx::QueryBuilder::<sqlx::Postgres>::new(
"INSERT INTO users (name, age) VALUES "
);
qb.push_values(items, |mut b, item| {
b.push_bind(item.name).push_bind(item.age);
});
qb.build().execute(&pool).await?;
常见误区
- 循环
INSERT单行提交,往返次数等于行数。 - 列表过大不分批,超出后端参数上限或数据包大小限制。
追问
- 批量插入冲突如何处理?答:在语句上加
ON CONFLICT子句(PG)或对应后端 upsert 语法,列冲突目标写死在片段里。 - 批量插入要回主键吗?答:用
RETURNING配合 fetch 取回,逐行主键回填,具体以支持情况为准。
04.4.8.1-062 一份防注入审计清单应包含哪些检查项?
一句话结论
逐项确认:SQL 片段只来自代码常量,外部值全部绑定,标识符经白名单,排序/表名/列名不接受裸输入,LIKE 通配有处理,无字符串拼接语句,动态执行语句单独评审。
概念解释
审计从代码入口追到查询构造:请求参数、配置值、消息体内容是否进入 SQL 文本。值走绑定即安全;结构位置必须有映射表。历史遗留的 format! 拼 SQL、存储过程动态执行是重点排查对象。清单结果应落到具体查询与责任人,而不是笼统「已评审」。
原理流程
- 列出所有查询构造点(宏、函数、构造器、原生 SQL 调用)。
- 标注每个外部输入的去向:绑定 / 片段 / 未使用。
- 片段输入核对白名单。
- 风险项重构为固定分支或绑定。
- 补充针对注入用例的测试。
代码或图示
审计项:
[ ] 外部值是否全部 bind
[ ] 表/列/排序方向是否走白名单
[ ] 是否存在 format! / 字符串拼接进 SQL
[ ] LIKE 通配是否按预期处理
[ ] 动态执行语句是否隔离评审
常见误区
- 只看新增代码,不扫遗留查询。
- 认为绑定了主条件就放过动态排序片段。
追问
- 自动化工具能覆盖哪些?答:依赖扫描与静态分析可发现部分拼接模式;标识符白名单与业务上下文仍需人工评审。
- 测试怎么模拟注入用例?答:在集成测试里用含引号、注释、
OR 1=1的输入断言结果未被篡改。
04.4.8.1-063 如何启动一个事务?
一句话结论
从池或连接调用 begin() 得到 Transaction,后续查询借用该事务句柄执行,最后 commit() 提交或 rollback() 回滚;未显式结束时 drop 自动回滚。
概念解释
Pool::begin 从池借一条连接并在其上开启事务,返回 Transaction<'c, DB>;Connection::begin 对已有连接开启。事务句柄实现 Executor,查询通过 &mut *tx 借用执行。事务期间连接被占用,结束后连接归还池。事务返回的是拥有事务状态的包装,不是单独的连接句柄。
原理流程
pool.begin().await?借连接并BEGIN。- 把
&mut tx传给各数据访问函数。 - 所有语句在同一连接上执行。
- 成功
tx.commit().await?;失败或早退tx.rollback().await?或 drop。
代码或图示
let mut tx = pool.begin().await?;
sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
.bind(amount).bind(from_id)
.execute(&mut *tx)
.await?;
sqlx::query("UPDATE accounts SET balance = balance + $1 WHERE id = $2")
.bind(amount).bind(to_id)
.execute(&mut *tx)
.await?;
tx.commit().await?;
常见误区
- 事务内一部分查询传
&pool:那些语句不在事务连接上,脱离事务边界。 begin后忘记 commit,函数返回时 drop 触发回滚。
追问
begin失败属于哪类错误?答:获取连接或执行BEGIN阶段错误,通常归类为连接/IO 或数据库错误,按sqlx::Error变体判断。- 事务能跨多个连接吗?答:不能,一个事务绑定一条物理连接,跨库一致性需要分布式事务方案。
04.4.8.1-064 commit、rollback 与 drop 时的回滚语义是什么?
一句话结论
commit(self) 提交事务并消耗句柄,rollback(self) 显式回滚;事务仍在进行中就被 drop(未 commit 也未 rollback),析构时自动回滚,避免半成品事务残留。
概念解释
事务句柄持有「未结束事务」的状态。commit/rollback 按值消费句柄;中途 panic 或提前返回导致句柄 drop,析构兜底执行回滚。自动回滚是安全网,但显式 rollback 能拿到回滚错误并记录日志。注意 drop 回滚是异步语义的析构钩子,具体行为以当前版本文档为准。
原理流程
- 事务开启后持有句柄。
- 业务成功:调用
commit,服务端提交。 - 业务失败:调用
rollback或返回错误触发 drop。 - drop 路径检测事务未结束,执行回滚兜底。
代码或图示
let mut tx = pool.begin().await?;
match do_work(&mut tx).await {
Ok(_) => tx.commit().await?,
Err(e) => { tx.rollback().await?; return Err(e); }
}
常见误区
- 依赖 drop 自动回滚却不记录原因,线上只看到事务被撤销。
commit之后继续使用原句柄:句柄已被消耗,类型上不允许。
追问
- 自动回滚失败怎么办?答:兜底回滚出错只能记录告警,连接可能被池丢弃重建;关键路径显式 rollback 便于观测。
- commit 是异步的吗?答:是,
commit().await等待服务端确认提交。
04.4.8.1-065 为什么事务句柄要以 &mut tx 传递给业务函数?
一句话结论
事务绑定一条可变借用的连接,多个查询共享同一事务必须独占借用该句柄;传 &mut Transaction 让各函数在同一事务连接上执行,避免并发借用破坏事务一致性。
概念解释
Transaction 实现 Executor 的可变借用形式:查询执行需要 &mut 访问内部连接。业务函数签名接收 &mut Transaction<'_, DB>,调用链逐层传递。不能把事务句柄克隆成多个并行分支,否则两条语句会争用同一连接。函数返回后借用结束,句柄仍归上层控制 commit/rollback。
原理流程
- 上层
begin得到事务句柄。 - 把
&mut tx传入 service 函数。 - 函数内查询借用句柄执行。
- 返回后上层决定 commit 或 rollback。
代码或图示
async fn transfer(
tx: &mut sqlx::Transaction<'_, sqlx::Postgres>,
from: i64, to: i64, amount: i64,
) -> Result<(), sqlx::Error> {
sqlx::query("UPDATE accounts SET balance = balance - $1 WHERE id = $2")
.bind(amount).bind(from)
.execute(&mut **tx)
.await?;
Ok(())
}
let mut tx = pool.begin().await?;
transfer(&mut tx, from, to, amount).await?;
tx.commit().await?;
常见误区
- 把
tx按值传给子函数又在上层 commit:所有权转移后上层无法再提交。 - 在事务函数里借池连接做附加查询:脱离事务。
追问
&mut **tx与&mut tx都能传吗?答:按Executor实现要求选择可变借用形式;编译期 trait bound 会指出正确写法。- 事务句柄能存进全局状态吗?答:不建议,事务生命周期应局限在单次业务用例内。
04.4.8.1-066 嵌套事务与 savepoint 是怎么支持的?
一句话结论
在活动事务上再次 begin() 会建立 savepoint:内层事务提交对应 release savepoint,回滚对应 rollback 到 savepoint;外层事务的提交/回滚决定整体最终结果。
概念解释
数据库不支持真正嵌套的顶层事务,SQLx 用 savepoint 模拟嵌套作用域。内层 Transaction 拥有自己的深度计数,其 commit/rollback 映射到 savepoint 操作。这样工具函数可以在不破坏外层事务的前提下划分可回滚区间。后端对 savepoint 的支持程度不同,MySQL/PG 支持,SQLite 行为以文档为准。
原理流程
- 外层
pool.begin()开启事务。 - 内层
tx.begin().await?建立 savepoint。 - 内层语句在 savepoint 之后执行。
- 内层 commit 释放 savepoint;内层 rollback 恢复到 savepoint。
- 外层最终 commit/rollback 决定整体。
代码或图示
let mut tx = pool.begin().await?;
{
let mut inner = tx.begin().await?;
// inner 内的操作
inner.commit().await?;
}
tx.commit().await?;
常见误区
- 以为内层 commit 会把外层一起提交:内层只释放 savepoint。
- 内层回滚后继续使用内层句柄:已被消耗,需重新开始区间。
追问
- savepoint 名称由谁生成?答:由 SQLx 内部按深度/计数生成;自定义语句入口以当前版本 API 为准。
- 嵌套层级很深有什么风险?答:savepoint 链增加开销与排错复杂度,合理划分业务边界即可。
04.4.8.1-067 Connection::transaction 闭包式 API 有什么优缺点?
一句话结论
闭包式 transaction(|tx| async { ... }) 自动按返回结果提交或回滚:闭包返回 Ok 提交,返回 Err 回滚;优点是不易漏 commit,缺点是错误类型要满足 From<Error> 约束,复杂控制流不如手动句柄直观。
概念解释
该 API 把事务生命周期收进闭包:进入时 begin,闭包成功返回 commit,失败返回 rollback。业务错误类型需要能从 sqlx::Error 转换(E: From<sqlx::Error>)。闭包是 FnOnce 异步块,捕获变量要满足 Send。手动 begin/commit 则保留显式控制,适合需要中间观察、分步回滚决策的场景。
原理流程
- 调用
conn.transaction,传入异步闭包。 - 闭包内拿到
&mut Transaction执行业务。 - 返回
Ok(R):框架 commit。 - 返回
Err(E):框架 rollback,错误向上传播。
代码或图示
conn.transaction(|tx| async move {
sqlx::query("UPDATE ...").execute(&mut *tx).await?;
sqlx::query("UPDATE ...").execute(&mut *tx).await?;
Ok::<(), sqlx::Error>(())
}).await?;
常见误区
- 闭包错误类型无法从
sqlx::Error转换,编译报 trait bound。 - 在闭包外持有事务句柄引用,生命周期超出闭包。
追问
- 闭包内想根据业务错误类型决定是否回滚怎么办?答:任何
Err都触发回滚;需要部分提交就拆分手动事务或用 savepoint。 - 闭包返回值类型如何标注?答:用
Ok::<R, E>(...)帮助编译器推断返回类型。
04.4.8.1-068 事务如何与 axum handler 集成?
一句话结论
全局共享 Pool 放进应用状态;handler 内按需 pool.begin() 开事务,把 &mut tx 传给 service 层,提交或回滚后返回响应;事务生命周期不跨请求,连接随句柄结束归还池。
概念解释
axum 应用状态里存的是可克隆的 Pool,不是单连接。每个请求在需要原子性的用例内开启事务。handler 错误类型要能包装 sqlx::Error;service 函数接收事务句柄而非池,保证多条语句在同一事务。事务不要存在扩展状态里跨请求复用。
原理流程
- 启动时构建
Pool,注入 axumState。 - handler 从状态取
Pool。 - 用例需要原子性时
pool.begin()。 - service 层借
&mut tx执行,handler 决定 commit/rollback。 - 响应返回后句柄结束,连接归还池。
代码或图示
async fn create_order(
State(pool): State<sqlx::PgPool>,
Json(req): Json<CreateOrder>,
) -> Result<Json<Order>, AppError> {
let mut tx = pool.begin().await?;
let order = Order::create(&mut tx, req).await?;
tx.commit().await?;
Ok(Json(order))
}
常见误区
- 把事务句柄塞进
Extension跨 handler 传递:生命周期与连接占用失控。 - service 方法内部自己
pool.begin(),外层事务被绕过。
追问
- 多步业务在一个 handler 里,事务放哪一层?答:放在用例/服务方法边界,handler 只负责调用与错误转换。
- 事务内调用外部 HTTP 接口合适吗?答:长事务持有连接等待外部响应,应尽量把外部调用移到事务外。
04.4.8.1-069 事务里跨 .await 持有连接会不会阻塞池?
一句话结论
会:事务未结束期间对应连接一直被占用,其它请求只能等待空闲连接;事务内每个 .await 只要还持有 tx,连接就不归还池,长等待会快速耗尽池。
概念解释
事务句柄活着即连接在借状态。事务内等待外部 API、锁、消息或慢查询,连接都不释放。池大小有限,并发事务积压时后续 acquire 超时返回错误。实践原则:事务内只做数据库操作,把非数据库 IO 移到事务前后;保持事务短而紧凑。
原理流程
begin后连接进入在借状态。- 事务内每个 await 期间连接仍被占用。
- 外部等待越长,占用越久。
- 并发上升后空闲连接耗尽,新请求 acquire 等待。
- commit/rollback 后连接归还。
代码或图示
反模式:
begin → 调用外部 HTTP(等待数百毫秒)→ DB 写入 → commit
改进:
先调外部接口拿到结果 → begin → DB 写入 → commit
常见误区
- 以为异步等待时连接会自动让出给别的请求:连接占用是所有权问题,与任务调度无关。
- 事务内做批量慢操作,占用连接时间被放大。
追问
- 如何观测事务占用时长?答:结合连接在借状态、慢查询日志与链路跨度,测量 begin 到 commit 的时间。
- 必须在事务内调用外部服务怎么办?答:缩小事务范围、提高失败重试设计,必要时考虑最终一致与补偿方案。
04.4.8.1-070 事务超时与长事务有什么风险?
一句话结论
长事务持有连接与锁,阻塞其它写入、推高回滚段与 Vacuum 压力,还可能让池耗尽;应设置合理的事务边界与语句超时,避免把多个用例塞进同一事务。
概念解释
数据库层面长事务影响锁持有、MVCC 版本可见性与清理;应用层表现为连接长时间不归还。风险包括:其它会话等待锁超时、备份/清理受阻、连接池被少数长事务占满。控制手段:事务内不做无关 IO、拆分大事务、设置语句/事务超时、监控事务持续时间。
原理流程
- 划分用例的原子性边界,只把必须同生共死的操作放进事务。
- 事务内语句尽量短。
- 配置语句超时与 acquire 超时兜底。
- 监控长事务与锁等待,定位异常用例。
代码或图示
长事务信号:
- 单事务内多次外部等待
- 批量大更新包在一个事务
- 事务跨越人工确认环节
常见误区
- 为了「保险」把整个请求流程都包进事务。
- 长事务出错后依赖回滚恢复,忽略期间已占用的资源。
追问
- 批量处理怎么避免单个超长事务?答:按批次提交,每批独立事务,记录进度支持断点续跑。
- 数据库侧怎么看长事务?答:查对应后端的活动会话/事务视图,找运行时间长、未提交的会话。
04.4.8.1-071 事务回滚后这条连接还能复用吗?
一句话结论
回滚结束后连接回到池可被复用;若回滚过程中连接已损坏(网络中断、协议异常),池会判定不可用并丢弃重建,不会把坏连接再借出。
概念解释
事务回滚清理的是数据库状态,连接本身在协议层通常仍可用。池在连接归还与再借出时按配置做可用性检查(如 test_before_acquire)。回滚错误、中途断连会让连接进入不可用路径。复用连接时上一个事务状态不会残留,下一次 begin 是全新事务。
原理流程
- 事务回滚完成,句柄 drop。
- 连接归还空闲队列。
- 再借出时按配置做存活检测。
- 检测通过则复用;失败则关闭并补建新连接。
代码或图示
rollback → 句柄结束 → 连接归还池 → 借出前检测 → 复用 / 丢弃重建
常见误区
- 以为回滚过的连接被标记脏、必须关闭:正常回滚后连接可复用。
- 回滚失败后仍继续在该连接上发查询:应丢弃连接并记录错误。
追问
- 如何配置借出前检测?答:
PoolOptions::test_before_acquire,具体探针行为以后端实现为准。 - 连接复用会带上会话级设置吗?答:之前在连接上执行的会话参数可能残留,必要时用
after_connect统一初始化。
04.4.8.1-072 多步写入「要么全成要么全败」的边界怎么设计?
一句话结论
先列出必须原子成功的写入步骤,把它们放进同一事务;事务外的查询、外部通知、补偿动作单独划分;明确失败时的补偿与重试边界,不要把不可回滚的外部动作塞进事务。
概念解释
事务只能保证数据库内多语句原子性,管不了外部接口、消息发送、缓存写入。设计时区分:强一致部分(库内多表写入)进事务;最终一致部分(发消息、调外部)走事务后或补偿机制。跨服务场景用本地消息表、outbox 等模式衔接。边界不清会导致事务内调外部接口拉长占用,或事务外写库留下半成品。
原理流程
- 梳理用例涉及的所有写操作与副作用。
- 标注可随事务回滚的库内操作。
- 不可回滚的外部动作移出事务,设计补偿。
- 事务内执行库内写入并提交。
- 事务后触发外部动作,失败走重试/补偿。
代码或图示
事务内:扣减库存、创建订单、写余额(库内多表)
事务后:发送消息、推送通知、调用外部服务(失败可重试/补偿)
常见误区
- 把发 MQ、调支付接口放进数据库事务等待回调。
- 多个独立用例共用一个大事务,失败互相牵连。
追问
- 事务提交后发消息失败怎么办?答:用 outbox/本地消息表,事务内落消息记录,后台任务投递并重试。
- 跨库操作如何保证?答:单库事务不覆盖,需分布式事务协议或最终一致补偿方案。
04.4.8.1-073 死锁在事务里如何暴露,重试边界在哪里?
一句话结论
死锁由数据库检测并中止其中一个事务,错误表现为数据库错误(含死锁特征码/种类);应用层可对有限次数的死锁做幂等重试,业务冲突导致的唯一键/更新冲突不应盲目重试。
概念解释
事务交叉持有锁时,数据库回滚牺牲一方,应用收到错误。重试前要区分错误类型:死锁、锁等待超时属于可重试并发冲突;唯一键冲突、数据不存在是业务状态问题,重试不解决。重试必须保证操作幂等,次数有限并记录告警。获取锁顺序一致、缩小事务范围也能减少死锁。
原理流程
- 事务内多条写语句按固定顺序访问表/行。
- 发生死锁时服务端中止当前事务。
- 错误分类:识别死锁/锁等待超时。
- 可重试且操作幂等:有限次数退避重试。
- 业务冲突错误:直接返回业务错误。
代码或图示
// 伪代码:识别可重试错误后有限重试
for attempt in 0..3 {
match run_tx(&pool).await {
Ok(v) => return Ok(v),
Err(e) if is_deadlock(&e) && attempt < 2 => continue,
Err(e) => return Err(e),
}
}
常见误区
- 对所有数据库错误无差别重试,放大唯一键冲突。
- 重试非幂等操作,重复扣款/重复下单。
追问
- 怎么判断错误是死锁?答:读取
DatabaseError的错误码/种类字段,匹配后端死锁标识;具体枚举以当前版本ErrorKind为准。 - 降低死锁概率还有哪些手段?答:统一加锁顺序、缩短事务、降低并发交叉访问、合理索引减少锁范围。
04.4.8.1-074 SQLx 连接池内部是怎么组织连接的?
一句话结论
池内部维护空闲连接队列与在借计数,按需创建连接;借出时从空闲队列取或新建,归还时放回队列;连接异常或超期则被清理,整体受 PoolOptions 配置约束。
概念解释
Pool<DB> 是线程/任务安全的共享结构,自身 Clone 只是增加一个池句柄,不复制连接。借连接是异步动作:无空闲且未达上限时新建,达到上限则等待空闲。池内部还跟踪连接生命周期(空闲时长、最大存活、健康检测)。理解内部结构有助于排查「连接为什么借不到」。
原理流程
- 构建池,按最小连接数预热。
- 请求
acquire:空闲有连接则取出;无则判断是否达上限。 - 未达上限新建连接;达上限进入等待队列。
- 连接 drop 归还空闲队列,唤醒等待者。
- 后台清理超期/损坏连接。
代码或图示
Pool
├── 空闲连接队列(可借出)
├── 在借连接集合(被任务持有)
├── 等待借出的任务队列
└── 配置:上限/预热/超时/生命周期/检测
常见误区
- 克隆
Pool以为复制了一套连接:多个句柄共享同一池。 - 以为借出后连接由调用者销毁:drop 包装器即归还。
追问
- 池关闭后等待中的请求会怎样?答:返回池已关闭类错误;具体变体以当前版本为准。
- 如何查看池状态?答:池提供状态信息接口(在借/空闲计数等),具体方法名以 docs.rs 为准。
04.4.8.1-075 PoolOptions 有哪些核心配置项?
一句话结论
核心项包括 max_connections、min_connections、acquire_timeout、idle_timeout、max_lifetime、test_before_acquire、connect_timeout、after_connect;按数据库承载能力与并发模型取值。
概念解释
max_connections 是池上限,min_connections 是预热空闲数。acquire_timeout 等待借连接的最长时间,connect_timeout 新建连接握手超时。idle_timeout 空闲多久后回收,max_lifetime 连接最长存活时间,防止长期老化连接。test_before_acquire 借出前探测可用性。after_connect 钩子做连接初始化。各方法签名以后端当前文档为准。
原理流程
- 按数据库最大连接数与实例数推算池上限。
- 设置预热与等待超时。
- 配置空闲/最大存活回收策略。
- 开启借出检测或定义初始化钩子。
- 构建池并压测校准。
代码或图示
let pool = sqlx::postgres::PgPoolOptions::new()
.max_connections(10)
.min_connections(2)
.acquire_timeout(std::time::Duration::from_secs(3))
.idle_timeout(std::time::Duration::from_secs(600))
.max_lifetime(std::time::Duration::from_secs(1800))
.test_before_acquire(true)
.connect(&url)
.await?;
常见误区
- 池上限设得超过数据库
max_connections可承受范围。 - 不配
acquire_timeout,故障时请求无限等待。
追问
min_connections越大越好吗?答:预热减少冷启动,但常驻占用数据库连接,按实例规模权衡。max_lifetime为什么要短于数据库侧连接超时?答:避免使用已被服务端单方面关闭的老化连接,具体阈值结合后端配置。
04.4.8.1-076 min_connections 预热与冷启动要权衡什么?
一句话结论
min_connections 让池启动时先建立若干空闲连接,消除首批请求的建连延迟;代价是常驻占用数据库连接,实例数多时要与数据库最大连接数一起核算。
概念解释
服务冷启动时按需建连包含握手、认证、会话初始化成本,首批请求延迟明显。预热把这部分成本前移到启动阶段。预热数量不是越大越好:每个实例都常驻最小连接,实例乘以预热数不能超过数据库连接预算。弹性伸缩频繁的场景,预热数应偏保守,避免空闲连接浪费。
原理流程
- 启动构建池,按
min_connections建立初始连接。 - 首批请求直接取空闲连接。
- 并发上升到超过预热数后按需新建到上限。
- 低峰期按空闲回收策略回落。
代码或图示
let pool = PgPoolOptions::new()
.min_connections(2)
.max_connections(10)
.connect(&url)
.await?;
常见误区
- 预热数设得与上限相同,所有实例常驻满连接。
- 忽略多实例总和:单池 10 连接 × 20 实例可能超过数据库上限。
追问
- 预热失败会怎样?答:按构建池时的错误处理;预热连接建立失败的行为以当前版本实现为准。
- 无预热可以吗?答:可以,靠按需建连,代价是冷启动请求变慢。
04.4.8.1-077 acquire_timeout 什么时候触发,报什么错?
一句话结论
池中无空闲连接、已达上限且等待超时仍借不到连接时触发 acquire_timeout,返回池超时类错误;它是并发过高、连接被长期占用或池上限过小的信号。
概念解释
acquire_timeout 限制任务等待空闲连接的时长。触发场景:慢查询占用连接、事务未及时释放、池上限偏小、数据库拒绝新连接。错误属于池获取阶段,不是 SQL 执行错误。排查时先看在借连接是否被长事务/慢查询占住,再评估调大上限或优化查询。
原理流程
- 任务请求借连接。
- 空闲队列空且达上限,进入等待。
- 等待期间有连接归还则被唤醒取走。
- 超时仍无连接:返回 acquire 超时错误。
- 上层按容量问题或故障处理。
代码或图示
acquire → 空闲? 有 → 取出
无 → 达上限? 否 → 新建
是 → 等待空闲 → 超时 → PoolTimedOut 类错误
常见误区
- 把 acquire 超时当成 SQL 报错去优化语句。
- 不设超时,请求在连接积压时永久挂起。
追问
- 超时后连接会被新建吗?答:等待超时直接返回错误,不会强行突破上限建连。
- 如何区分池超时与建连超时?答:
connect_timeout管握手阶段,acquire_timeout管从池等待阶段,错误变体不同。
04.4.8.1-078 test_before_acquire 与断连探测是怎么做的?
一句话结论
开启后每次借出连接前先做存活探测,确认连接未被服务端断开;探测通过才交给任务,避免拿到半开连接导致首条语句报错。
概念解释
空闲连接可能被数据库、防火墙或负载均衡单方面关闭,应用侧并不知情。借出前探测发一条轻量探针(具体探针 SQL 以后端实现为准),失败则丢弃该连接并补建。代价是每次借出多一次探测开销;网络稳定、连接生命周期配置合理时可权衡关闭。after_connect 与借出检测是两个不同时机。
原理流程
- 任务借出连接。
- 若开启检测,对空闲连接执行探针。
- 探针成功:交给任务。
- 探针失败:关闭坏连接,按需要新建后再交付。
代码或图示
let pool = PgPoolOptions::new()
.test_before_acquire(true)
.connect(&url)
.await?;
常见误区
- 以为池能自动知道服务端断连:没有探测时,断连要等到下一次使用才暴露。
- 把探测配置成重查询,反而拖慢借出。
追问
- 探针具体执行什么语句?答:以后端驱动实现为准,通常是轻量存活查询;不确定时查当前版本文档。
- 关闭检测有什么风险?答:半开连接被借出,首条业务语句报 IO/协议错误。
04.4.8.1-079 idle_timeout 与 max_lifetime 分别解决什么问题?
一句话结论
idle_timeout 回收长期空闲的连接以释放数据库侧资源;max_lifetime 限制连接总存活时间,避免老化连接遇到服务端超时、配置变更或内存累积问题。
概念解释
空闲连接在低峰期没有存在必要,idle_timeout 让闲置超期的连接被关闭。max_lifetime 面向连接整体寿命:即使一直活跃,达到寿命也会被替换,防止长期连接积累状态问题或撞上数据库/中间件的连接超时。两者配合:空闲回收应对波谷,寿命轮换应对长期老化。
原理流程
- 连接归还后记录空闲起始时间。
- 空闲超过
idle_timeout:后台回收。 - 连接存活超过
max_lifetime:下次归还后替换。 - 新建连接补足池规模。
代码或图示
.idle_timeout(Duration::from_secs(600))
.max_lifetime(Duration::from_secs(1800))
常见误区
- 只设空闲超时不设最大寿命:老化连接长期复用。
max_lifetime设得比数据库侧连接超时还长:先被服务端断开。
追问
- 连接达到寿命时正在被借用怎么办?答:等其归还后再替换,不会强行切断在借连接;具体行为以实现为准。
- 短寿命连接有什么代价?答:轮换频繁,建连开销上升,需在稳定性与开销间平衡。
04.4.8.1-080 连接池耗尽的排查路径是什么?
一句话结论
按「在借连接是否被占住 → 占住的是哪些任务/事务 → 慢查询或外部等待 → 池上限与数据库承载」逐层排查,先定位连接持有者,再决定优化语句、缩短事务还是调参。
概念解释
池耗尽表现为 acquire 超时、请求排队。排查顺序:看池状态在借/空闲计数;追踪在借连接对应的请求与事务;检查慢查询日志与事务持续时间;确认是否有连接未归还(泄漏);最后核对池上限与数据库最大连接数。不要一上来就调大上限,可能把压力转嫁给数据库。
原理流程
- 采集池状态:在借数、等待队列、错误计数。
- 关联链路日志,找出持有连接的请求。
- 检查这些请求是否卡在慢 SQL、外部调用或未结束事务。
- 确认连接是否被遗忘未 drop。
- 针对性优化后再评估池参数。
代码或图示
池耗尽
├── 在借数打满 → 慢查询 / 长事务 / 外部等待
├── 连接泄漏 → 句柄被长期持有或存进全局状态
├── 上限过小 → 并发需求超过配置
└── 数据库侧拒绝 → 服务端连接数/资源限制
常见误区
- 直接调大
max_connections缓解表象,根因未除。 - 只看应用错误,不查数据库侧会话与锁等待。
追问
- 怎么确认是泄漏而非慢?答:泄漏连接长期不归还且对应请求已结束;慢连接对应仍在运行的查询。结合链路时间线判断。
- 池状态怎么暴露给监控?答:读取池状态计数接入 metrics,按在借数与等待超时告警。
04.4.8.1-081 连接泄漏如何识别与避免?
一句话结论
连接泄漏指连接包装器未被 drop、连接长期在借且无对应活跃任务;识别靠在借计数只增不减、请求结束后连接不归还;避免方式是事务/连接句柄严格限定在作用域内,不存入长生命周期结构。
概念解释
PoolConnection/Transaction 包装器 drop 时归还连接。若句柄被存进全局状态、缓存、静态变量,或跨任务移动后不再被丢弃,连接就一直占用。常见写法错误:把事务句柄放进 Extension、把连接存进复用结构体。识别信号:空闲连接逐步归零、在借数单调上升、acquire 超时增多。
原理流程
- 句柄在函数作用域内借出。
- 函数结束时正常 drop 归还。
- 若句柄被移出作用域保存,归还时机丢失。
- 监控发现在借数持续增长。
- 代码审查找出长期持有句柄的位置。
代码或图示
// 正确:句柄随作用域结束归还
async fn handler(pool: &PgPool) -> Result<(), sqlx::Error> {
let mut tx = pool.begin().await?;
do_work(&mut tx).await?;
tx.commit().await?;
Ok(())
}
常见误区
- 在结构体内保存
PoolConnection字段供多次调用复用。 - spawn 的任务里持有句柄却不结束,连接被挂起任务长期占用。
追问
- 语言层面怎么防止泄漏?答:
PoolConnection不Clone,所有权与作用域受限;审查句柄传递路径即可。 - 泄漏后重启能恢复吗?答:重启释放连接,但根因仍在,会再次积累。
04.4.8.1-082 池大小如何与 CPU、数据库最大连接数协调?
一句话结论
池上限主要受数据库最大连接数与实例数约束,不是越大越好;公式上各实例池上限之和应小于数据库 max_connections,预留管理连接;CPU 核数影响并发任务数,不直接决定连接数。
概念解释
数据库连接是稀缺资源,每个连接占用服务端内存与工作区。多实例部署时:单实例池上限 × 实例数 + 预留连接 < 数据库最大连接数。异步应用单实例可在较少连接上支撑较多并发任务,但连接数仍要匹配数据库处理能力。压测时观察等待队列、查询延迟与数据库负载来校准,而非照搬教程数值。
原理流程
- 查数据库最大连接配置。
- 按实例数与预留管理连接推算总可用连接。
- 单实例池上限 = 可用连接 / 实例数,留余量。
- 压测观察 acquire 等待与查询耗时。
- 按需微调上限与超时。
代码或图示
数据库 max_connections = 100
预留管理/故障切换 = 20
应用实例 = 8
单实例池上限 ≈ (100 - 20) / 8 = 10
常见误区
- 单实例池设 50,十个实例直接打满数据库。
- 按 CPU 核数等比放大连接数:IO 型负载与连接数无直接换算。
追问
- 异步服务连接数可以比同步服务少吗?答:异步在单连接上交替服务任务,但仍受单连接查询串行约束;按压测结果定。
- 连接数过小会怎样?答:请求在池等待,吞吐被连接数卡住。
04.4.8.1-083 sqlx-cli 如何安装,对环境有什么要求?
一句话结论
通过 cargo install sqlx-cli 安装命令行工具;迁移与 prepare 命令需要 DATABASE_URL 指向可访问数据库,CLI 按启用的后端编译对应驱动。
概念解释
sqlx-cli 提供数据库创建、迁移管理与离线 prepare 能力。安装时可按目标后端裁剪 feature(如只装 postgres)。运行命令时从环境变量、.env 或 --database-url 读取连接串。CLI 是开发/运维工具,不影响运行时依赖;生产镜像通常不需要打包 CLI。
原理流程
cargo install sqlx-cli(按需选后端 feature)。- 配置
DATABASE_URL。 - CLI 连接数据库执行对应子命令。
- 迁移脚本存放在工程
migrations/目录。
代码或图示
cargo install sqlx-cli
# 可选:仅安装 postgres 后端,具体 feature 名以 crate 文档为准
# cargo install sqlx-cli --no-default-features --features postgres
sqlx database create
常见误区
- 把 CLI 作为运行时依赖写进
[dependencies]。 - 未设
DATABASE_URL就跑迁移命令,连接失败。
追问
sqlx与cargo sqlx两个入口有何区别?答:cargo sqlx是 cargo 子命令包装,sqlx是独立可执行文件;prepare 需走cargo sqlx。- CLI 版本要与库版本对齐吗?答:建议版本配套,避免元数据/迁移格式不兼容。
04.4.8.1-084 migrate add、run、revert、info 各自做什么?
一句话结论
add 生成新迁移脚本,run 应用所有未执行迁移,revert 回滚最近迁移,info 查看迁移与数据库的应用状态;--source 可指定迁移目录。
概念解释
迁移按版本顺序管理:add 在 migrations/ 下生成带版本号的脚本文件;run 对比版本表与目录,应用pending 脚本;revert 执行回滚脚本(可逆迁移);info 列出各迁移在本地与库中的状态。CLI 与运行时 migrate! 使用同一目录约定。子命令细节以后端当前版本文档为准。
原理流程
sqlx migrate add <name>生成版本脚本。- 编辑 up 逻辑(与 down 脚本,若可逆)。
sqlx migrate run应用 pending 迁移并记录版本。sqlx migrate info核对状态;revert回滚最近一条。
代码或图示
sqlx migrate add create_users
sqlx migrate run
sqlx migrate info
sqlx migrate revert
常见误区
- 已应用的迁移脚本再手动修改内容:版本表记录与脚本不一致。
- 把 revert 当常规发布流程:生产环境通常不回滚已上线迁移。
追问
- 迁移目录不在默认位置怎么办?答:用
--source指定目录,或在配置中约定。 info显示某迁移未应用但库里已有表是什么原因?答:历史表未纳入版本管理,需要核对初始化方式。
04.4.8.1-085 -r 可逆迁移的 up/down 成对文件是怎么组织的?
一句话结论
migrate add -r <name> 同时生成 <version>_<name>.up.sql 与 <version>_<name>.down.sql:up 应用变更,down 回滚变更;简单迁移与可逆迁移不能混用。
概念解释
可逆迁移要求每个变更都有对应回滚脚本,revert 才能执行 down。不加 -r 生成单文件 up 脚本,无法回滚。CLI 会拒绝简单迁移与可逆迁移混合使用。编写 down 时要保证「up 后立刻 redo」让结构回到原状;数据迁移的回滚往往无法完全还原,需在脚本里说明限制。
原理流程
sqlx migrate add -r <name>生成成对文件。- up.sql 写正向 DDL/DML。
- down.sql 写逆向逻辑。
run执行 up,revert执行 down。
代码或图示
migrations/
├── 20261119120000_create_users.up.sql
└── 20261119120000_create_users.down.sql
常见误区
- up 改了列类型,down 直接转回旧类型但不处理数据转换。
- 混用单文件与成对文件,CLI 报错拒绝。
追问
- 不可逆的数据变更怎么做回滚?答:down 尽量恢复结构,数据层面依赖备份与前镜像;不要承诺完全还原业务数据。
- 生产可以执行 revert 吗?答:谨慎,优先用新增正向迁移修正结构;回滚仅限预发/本地排错。
04.4.8.1-086 迁移版本表里记录了什么?
一句话结论
SQLx 在数据库内维护迁移历史表(默认名 _sqlx_migrations),记录已应用迁移的版本号、描述、执行时间与脚本校验和,用于判断哪些迁移 pending。
概念解释
版本表是迁移机制的真相来源:run 读取表中已应用版本,与目录脚本对比得出待执行集合。校验和用于发现脚本被改动。表结构与列名以当前版本实现为准。新环境建库后首次 run 会创建该表并依次应用脚本。手动改版本表会破坏迁移判断,应避免。
原理流程
- 首次运行迁移时创建历史表。
- 每应用一条迁移,写入版本、描述、校验和与时间。
- 后续
run对比目录版本与表记录。 - 脚本校验和与记录不符时给出警告或错误。
代码或图示
_sqlx_migrations
├── version(迁移版本号)
├── description(描述)
├── installed_on(执行时间)
└── checksum(脚本校验和)
常见误区
- 直接在表里删记录想「重置迁移状态」:应走正规 revert 或重置库。
- 改了已应用脚本内容却不处理校验和:后续环境报错。
追问
- 校验和不匹配会怎样?答:CLI/运行时按策略警告或拒绝继续;具体行为以当前版本为准。
- 多环境并行部署如何避免迁移冲突?答:迁移版本只增不改,变更通过新增迁移完成。
04.4.8.1-087 migrate! 宏在启动时如何内嵌并执行迁移?
一句话结论
migrate! 宏在编译期把 migrations/ 目录脚本嵌入二进制,运行时连接数据库后按版本顺序应用 pending 迁移;便于单二进制部署,无需在生产环境外挂迁移目录与 CLI。
概念解释
启用 migrate feature 后,sqlx::migrate!("./migrations") 在构建期读取脚本目录生成迁移集合。程序启动时调用运行方法,对比库内版本表执行未应用脚本。嵌入方式让部署产物自包含,但脚本更新需要重新编译。是否在应用启动时自动跑迁移,还是由独立发布步骤执行,按团队发布策略决定。
原理流程
- 编译期
migrate!读取目录脚本并嵌入。 - 程序启动建立连接。
- 迁移器读取版本表,对比嵌入脚本集合。
- 按版本顺序执行 pending 迁移并记录。
代码或图示
let pool = sqlx::PgPool::connect(&url).await?;
sqlx::migrate!("./migrations")
.run(&pool)
.await?;
常见误区
- 认为嵌入迁移后脚本目录就不用维护:源码目录仍是真相来源。
- 多实例同时启动自动跑迁移:需确认迁移并发执行策略,避免并发应用冲突。
追问
- 嵌入的是脚本文本还是编译后产物?答:嵌入 SQL 脚本内容,运行时在数据库执行;具体嵌入形式以实现为准。
- 不想启动自动迁移怎么做?答:去掉启动时调用,用 CLI 在发布流程中单独执行迁移。
04.4.8.1-088 可重复迁移(repeatable migration)是什么,文件命名有何约定?
一句话结论
可重复迁移用于视图、存储过程等「脚本内容变了就重新执行」的对象,不依赖递增版本;具体文件命名与识别规则以 sqlx 当前版本文档为准(待确认),不要凭记忆写死前缀。
概念解释
普通迁移按版本号只执行一次;可重复迁移在校验和变化时重新运行,适合定义可被脚本重建的数据库对象。SQLx 的 MigrationType 区分普通与可重复类型。由于命名约定在版本间可能调整,落地前应查 docs.rs/sqlx 迁移章节确认文件命名格式与 migrate add 是否有对应标志。
原理流程
- 查当前文档确认可重复迁移的文件命名/生成方式。
- 编写可重建对象的脚本。
- 迁移器按校验和判断是否需要重新执行。
- 变更脚本内容后下次启动自动重跑。
代码或图示
待确认:可重复迁移文件命名前缀与版本号取值规则;
验证方式:docs.rs/sqlx 当前版本 migrate 模块文档,或 `sqlx migrate add --help`。
常见误区
- 把普通 DDL 迁移写成可重复类型:重复执行可能破坏已有数据。
- 凭旧版本记忆命名,导致迁移器识别错误。
追问
- 视图变更适合哪种迁移?答:视图定义可由脚本完整重建,通常适合可重复迁移;最终以工具支持为准。
- 可重复迁移也有 down 脚本吗?答:其回滚语义与普通可逆迁移不同,按文档约定处理。
04.4.8.1-089 编写迁移脚本有哪些规范?
一句话结论
迁移只增不改、按顺序可追溯;脚本自身尽量明确、可重复部署;数据变更与结构变更分开考虑;禁止手工修改已在其它环境应用过的脚本。
概念解释
迁移是团队协作的历史记录:已应用到任一环境的脚本应冻结,新需求用新增迁移解决。脚本要考虑失败回滚与并发部署。大表 DDL 要评估锁与复制延迟。纯结构迁移与数据回填分开,避免长事务锁表。脚本内容应代码评审,与应用代码同批发布。
原理流程
- 新增迁移脚本,版本号递增。
- 评审 DDL/DML 对锁、数据、回滚的影响。
- 本地与测试库执行验证。
- 提交后不再修改该脚本。
- 问题修正用后续迁移承接。
代码或图示
规范要点:
- 不改历史脚本
- 结构变更与数据回填分离
- 大表变更评估锁与耗时
- down 脚本尽量可逆
- 迁移纳入版本管理与评审
常见误区
- 直接编辑已上线脚本「同步结构」,导致各环境校验和不一致。
- 一条迁移里混大表加列与全量数据更新。
追问
- 迁移在 CI 测试库怎么跑?答:测试前从空库执行全部迁移,验证脚本顺序与幂等行为。
- 上线时迁移与应用代码谁先谁后?答:遵循向后兼容:先发布兼容旧代码的迁移,再部署应用;破坏性变更分阶段进行。
04.4.8.1-090 sqlx::Error 主要分哪几类?
一句话结论
sqlx::Error 大致分为数据库返回错误、连接/IO/TLS 错误、池错误、解码/编码错误、配置与协议错误、行不存在等;按变体分类后再决定业务映射与重试。
概念解释
错误顶层类型是 sqlx::Error,各变体对应失败阶段。Database 变体包裹后端 DatabaseError,携带错误码、约束名等细节;Io/Tls 是传输层问题;PoolTimedOut/PoolClosed 是池阶段;Decode/Encode 是类型转换;RowNotFound 是基数问题。完整变体列表以 docs.rs 当前版本为准,答题时按阶段归类即可。
原理流程
- 操作返回
Result<_, sqlx::Error>。 - 按阶段匹配变体:池 → 连接 → 数据库 → 解码。
Database错误再读取内部细节。- 映射为应用层错误类型或决定重试。
代码或图示
sqlx::Error
├── Database(Box<dyn DatabaseError>) 服务端约束/语法/事务错误
├── Io / Tls / Protocol 传输与协议层
├── PoolTimedOut / PoolClosed 连接池阶段
├── Decode / Encode 类型编解码
├── RowNotFound 期望单行但无结果
└── Configuration / ... 配置与其它
常见误区
- 把所有错误都包装成「数据库错误」,丢失阶段信息。
- 不匹配变体直接
unwrap,把可处理错误变成 panic。
追问
- 怎么拿到后端原始错误码?答:
Error::Database里的DatabaseError提供code()/constraint()等访问器,具体方法名以当前版本为准。 - 错误能跨
.await传递吗?答:sqlx::Error通常满足Send,异步链路可返回;具体约束按类型定义确认。
04.4.8.1-091 DatabaseError 能提供哪些细节?
一句话结论
数据库错误可读取错误消息、后端错误码、约束名、表/列信息等,用于区分唯一键冲突、外键冲突、检查约束等具体原因;细节可用随后端不同。
概念解释
DatabaseError trait 暴露规范化访问器:message() 服务端消息,code() 后端错误码,constraint() 触发的约束名,部分后端提供表/列名。上层据此把数据库错误翻译成业务错误,而不是展示原始消息。错误码语义随后端方言,映射表要按所连数据库维护。
原理流程
- 匹配
Error::Database(db_err)。 - 读
code()或constraint()判断冲突类型。 - 结合约束名定位具体业务规则。
- 转换为应用错误枚举返回给接口层。
代码或图示
match sqlx::query("...").execute(&pool).await {
Ok(r) => Ok(r.rows_affected()),
Err(sqlx::Error::Database(e)) => {
if let Some(constraint) = e.constraint() {
Err(AppError::Conflict(constraint.to_string()))
} else {
Err(AppError::Db(e.to_string()))
}
}
Err(e) => Err(AppError::Db(e.to_string())),
}
常见误区
- 直接把数据库原始消息抛给前端:泄露表结构与内部信息。
- 只看消息文本判断冲突类型:消息文案随版本/语言变化,应匹配错误码或约束名。
追问
- 约束名在迁移里怎么定?答:给唯一/外键约束显式命名,便于应用层按名识别;匿名约束名难定位。
- 后端错误码格式一致吗?答:不一致,Postgres/MySQL/SQLite 各自编码体系,映射层要分别处理。
04.4.8.1-092 唯一键冲突如何识别并转成业务错误?
一句话结论
执行写语句后匹配 Error::Database,按错误码种类或约束名判断唯一键冲突,再映射为「资源已存在」类业务错误;不要靠匹配错误消息文本。
概念解释
唯一索引/主键重复写入时服务端拒绝,应用需要返回友好的 409/业务码。识别路径:先按数据库错误种类(如唯一违例)分类,再按约束名区分是哪条业务规则。映射后日志保留原始错误详情,对外只暴露业务语义。新增唯一约束时要同步更新应用层识别与提示。
原理流程
- 执行插入或 upsert 语句。
- 捕获
Error::Database。 - 判断错误种类为唯一违例(或匹配约束名)。
- 转换为
AppError::Duplicate(...),记录原始错误。 - 接口层映射为对应状态码与提示。
代码或图示
let err = match insert_result {
Ok(v) => return Ok(v),
Err(sqlx::Error::Database(e)) if is_unique_violation(&e) => {
AppError::Duplicate(e.constraint().unwrap_or("").to_string())
}
Err(e) => AppError::Db(e.to_string()),
};
常见误区
- 用错误消息里的中文/英文关键字判断冲突,换语言或版本即失效。
- 所有冲突都报「用户名已存在」,约束名丢失导致定位不准。
追问
is_unique_violation怎么实现?答:读DatabaseError::kind()返回的错误种类枚举,匹配唯一违例;枚举名以当前版本为准。- upsert 场景还需要处理唯一冲突吗?答:
ON CONFLICT已在库内消化冲突;未走 upsert 的插入才需要应用层识别。
04.4.8.1-093 外键冲突与检查约束冲突怎么识别?
一句话结论
外键冲突分为「插入引用不存在父行」与「父行被引用仍删除」两类,检查约束冲突由 CHECK 规则触发;同样按错误种类与约束名识别,映射为对应的业务校验错误。
概念解释
外键违例错误码与唯一违例不同,约束名指向关联关系;CHECK 约束违例对应业务规则限制(如金额为正)。应用层识别后分别提示:引用关系不存在、有关联数据不能删除、字段值不满足规则。约束命名清晰是可识别的前提。删除父行前也可先做应用层存在性检查,但数据库约束仍是最后防线。
原理流程
- 写操作触发约束违例。
- 读取错误种类区分外键/CHECK。
- 按约束名定位业务规则。
- 映射为对应业务错误与提示。
代码或图示
外键违例:子行引用缺失父行 / 删除仍被子行引用
CHECK 违例:字段值不满足规则表达式
识别依据:错误种类 + 约束名,不看消息文本
常见误区
- 把外键冲突都当成「数据不存在」返回 404,语义错误。
- 依赖应用层先查一遍就不加数据库约束:并发下仍可能突破。
追问
- 删除被引用记录怎么给前端提示?答:映射为「存在关联数据,无法删除」,必要时列出关联类型。
- 约束名无法取到时怎么办?答:按错误大类兜底提示,并在日志记录原始错误;后续补命名约束。
04.4.8.1-094 RowNotFound 与 fetch_optional 怎么选?
一句话结论
业务上记录必然存在(按内部 ID 查询且已校验)用 fetch_one,缺失属于异常;可能不存在的资源用 fetch_optional,零行返回 None 再映射为 404;不要用 fetch_one 处理正常的空结果。
概念解释
fetch_one 在零行时返回 RowNotFound 错误;fetch_optional 把零行转为 Ok(None)。选择取决于空结果是异常还是预期分支。接口查询资源大概率用 fetch_optional,再把 None 映射为未找到错误;内部流程保证存在时用 fetch_one,空结果作为错误暴露。
原理流程
- 判断空结果是否为业务合法分支。
- 合法:
fetch_optional,None→ 404/默认值。 - 异常:
fetch_one,RowNotFound进入错误日志。 - 多结果场景另选 fetch 方法并加
LIMIT。
代码或图示
let user = sqlx::query_as::<_, User>("SELECT * FROM users WHERE id = $1", )
.bind(id)
.fetch_optional(&pool)
.await?
.ok_or(AppError::NotFound)?;
常见误区
- 用
fetch_one查可选资源,把正常 404 变成 500 错误链路。 - 用
fetch_optional查必须存在的内部记录,把缺陷掩盖成空值。
追问
RowNotFound属于哪类错误?答:SQLx 顶层Error的一个变体,表示期望单行而结果为空。- 查询可能返回多行时用哪个?答:
fetch_all或流式fetch,必要时LIMIT 1收窄基数。
04.4.8.1-095 如何用 thiserror 分层包装 sqlx::Error?
一句话结论
定义应用错误枚举,用 thiserror 派生变体包装 sqlx::Error 或映射后的业务错误;数据访问层返回应用错误,接口层只认识应用错误类型,底层驱动类型不泄露到边界。
概念解释
分层约定:底层把 sqlx::Error 翻译成领域错误(NotFound、Conflict、Db),保留原始错误作为来源;thiserror 负责 Display/From 实现,anyhow 用于应用层临时聚合。驱动细节(连接池、解码)收敛在数据访问模块。错误枚举区分可对外暴露的业务语义与内部故障。
原理流程
- 定义
AppError枚举,含 NotFound/Conflict/Db 等变体。 - 实现从
sqlx::Error到AppError的转换或在仓库方法内匹配。 - 数据访问方法返回
Result<_, AppError>。 - 接口层把
AppError映射为响应;内部错误保留 source 链。
代码或图示
#[derive(Debug, thiserror::Error)]
pub enum AppError {
#[error("未找到资源")]
NotFound,
#[error("资源冲突: {0}")]
Conflict(String),
#[error("数据库错误")]
Db(#[from] sqlx::Error),
}
常见误区
- 直接把
sqlx::Error作为 handler 返回类型:驱动类型泄露到 API 边界。 - 用
anyhow::Error贯穿所有层,丢失可匹配的错误语义。
追问
#[from] sqlx::Error会不会把业务冲突也归为 Db?答:会;需要先匹配冲突变体转换为 Conflict,剩余再走 From 兜底。- 错误链怎么保留?答:
thiserror变体带source字段包装原始错误,日志层沿 source 输出详情。
04.4.8.1-096 流式查询 fetch 与 Stream 的内存行为是什么?
一句话结论
fetch 返回异步流,结果行按需从网络读取并逐行解码,不一次性把全部结果落内存;消费时要逐行处理并在出错时正确结束流,连接随流结束归还。
概念解释
列表结果集很大时 fetch_all 会把所有行解码进 Vec,内存峰值随行数增长。fetch 配合 StreamExt::next 逐行拉取,解码一行处理一行。流未耗尽时连接被占用;处理中途返回错误要丢弃流以释放连接。背压由异步流消费节奏控制,不会无限制从网络读入。
原理流程
- 查询通过
fetch(&pool)得到流。 - 循环
next().await取下一行。 - 每行解码后处理(写入响应、聚合、转发)。
- 流结束或丢弃,连接归还池。
- 行级错误在
next返回的Result中暴露。
代码或图示
use futures_util::TryStreamExt;
let mut rows = sqlx::query_as::<_, User>("SELECT * FROM users ORDER BY id")
.fetch(&pool);
while let Some(row) = rows.try_next().await? {
process(row);
}
常见误区
- 对大结果集用
fetch_all,内存被撑爆。 - 拿到流后不消费也不丢弃,连接长期被挂起流占用。
追问
- 流能并行处理行吗?答:单连接上行读取是串行的;并行处理需要分批取数或多连接,注意连接占用。
- 流式读取中途网络断开怎么表现?答:
next返回 IO/协议错误,停止消费并释放连接。
04.4.8.1-097 大结果集分页:offset 分页与 keyset 分页有何区别?
一句话结论
offset 分页按 LIMIT/OFFSET 跳过前导行,实现简单但深分页扫描成本高、数据变动时可能重复或丢行;keyset(游标)分页用上一页最后一个排序键作为条件继续取,深分页稳定且可走索引。
概念解释
offset 第 N 页要扫描并跳过前 N 行,页码越深成本越高;列表中途新增/删除记录会导致页边界漂移。keyset 分页要求排序键唯一稳定,查询带上 WHERE key < last_key ORDER BY key LIMIT n,每次从断点继续。游标序列化的是排序键组合,不是页码。两种方式按场景选择:后台浅分页可用 offset,面向用户的长列表用 keyset。
原理流程
- 确定稳定唯一的排序键(通常加主键兜底)。
- offset:计算
(page-1)*size,拼LIMIT/OFFSET。 - keyset:保存上一页末尾键,下一页按键条件过滤。
- 比较各页结果,核对无重复无遗漏。
代码或图示
-- offset
SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 40;
-- keyset
SELECT * FROM users WHERE id > $1 ORDER BY id LIMIT 20;
常见误区
- 排序键不唯一就做 keyset:翻页出现重复/遗漏。
- 深分页仍用大 offset,数据库扫描大量前导行。
追问
- 游标里要存哪些字段?答:排序涉及的全部键(如
created_at, id),缺一不可保证稳定顺序。 - 总条数还要不要返回?答:keyset 场景总数可单独 count 或不展示精确总数。
04.4.8.1-098 #[sqlx::test] 属性宏怎么用,隔离性如何保证?
一句话结论
#[sqlx::test] 标记的测试在独立数据库/架构上运行迁移并隔离数据,避免测试间相互污染;它需要测试环境可连接数据库或按离线方式配置,具体临时库机制以当前版本文档为准(待确认)。
概念解释
普通集成测试共享开发库会相互影响数据。sqlx::test 宏为每个测试准备隔离环境:常见做法是创建临时数据库或临时 schema,跑完清理。测试内拿到连接/池执行断言。该宏与标准 #[tokio::test] 的关系、是否自动跑迁移,需要对照当前版本文档确认;不确定点标注待确认。
原理流程
- 测试函数加
#[sqlx::test],签名接收连接参数。 - 宏在运行前准备隔离数据库环境。
- 执行迁移(按宏配置)与测试逻辑。
- 断言后清理临时环境。
代码或图示
#[sqlx::test]
async fn create_user(pool: sqlx::PgPool) -> Result<(), sqlx::Error> {
let id = sqlx::query_scalar!("INSERT INTO users (name) VALUES ($1) RETURNING id", "anna")
.fetch_one(&pool)
.await?;
assert!(id > 0);
Ok(())
}
常见误区
- 测试直接连开发库,用例顺序依赖导致偶发失败。
- 以为测试宏自动回滚所有写入:隔离/回滚机制以宏实现为准,需验证。
追问
#[sqlx::test]需要哪个 feature?答:以当前版本文档为准,通常与测试支持相关的 feature 配合;不确定时查 docs.rs。- 并行测试会不会争用同一临时库?答:隔离机制按测试分配独立环境;并行行为以文档与实际测试结果为准。
04.4.8.1-099 测试中用事务回滚包裹用例是什么模式?
一句话结论
每个测试在一个事务内写入数据,断言结束后回滚,不提交任何变更,从而在共享测试库上保持用例间数据隔离;适用于不支持临时库的场景。
概念解释
模式流程:测试开始 begin,所有仓库调用借用该事务句柄,断言后 rollback。由于不 commit,表内不留测试数据,下一用例从干净状态开始。前提是被测函数接收连接/事务句柄而非内部自取池连接;否则写入脱离事务无法回滚。注意回滚模式与真实提交路径略有差异,关键提交逻辑仍需独立集成测试覆盖。
原理流程
- 测试开启事务
tx。 - 业务方法接收
&mut tx执行写入。 - 断言查询结果(同事务内可见)。
- 测试结束回滚,数据不落库。
- 下一用例重复。
代码或图示
#[tokio::test]
async fn create_user_rollback() -> Result<(), sqlx::Error> {
let mut tx = pool.begin().await?;
create_user(&mut tx, "anna").await?;
let found = find_by_name(&mut tx, "anna").await?;
assert!(found.is_some());
tx.rollback().await?;
Ok(())
}
常见误区
- 业务方法内部从池里取连接:测试事务包不住其写入。
- 测试提交了数据又依赖手动清理,残留影响其它用例。
追问
- 这种模式能测 commit 行为吗?答:不能,提交路径需另起用例真实写入并清理。
- 并行测试共用库会互相干扰吗?答:未提交事务内数据对其它连接不可见,回滚后无残留;前提是各用例独立事务。
04.4.8.1-100 SQLx 类型在异步运行时下的 Send/Sync 边界是什么?
一句话结论
池句柄 Pool 可克隆并跨任务共享(Send + Sync),事务句柄与连接是可变借用资源,不能在多个异步任务间共享;查询执行借用连接,跨 .await 时借用关系必须满足 Send 约束。
概念解释
Web 应用把 Pool 放入全局状态跨 handler 共享,依赖其线程安全。Transaction/Connection 持有单连接,按可变借用独占使用,不实现可共享的并发访问。查询 future 需要满足 Send 才能被 tokio 多线程运行时调度;连接与绑定参数跨 await 移动时必须 Send。违反边界会在编译期报 Send 相关错误,而不是运行期数据竞争。
原理流程
Pool作为共享状态跨任务传递。- 每任务独立
acquire或begin,得到独占句柄。 - 查询 future 在 await 期间持有句柄借用。
- 编译器校验 future 与捕获类型满足
Send。 - 句柄 drop 后连接归还池。
代码或图示
// Pool 可克隆、可进 State
let pool: sqlx::PgPool = sqlx::PgPool::connect(&url).await?;
let shared = pool.clone();
// 句柄不跨任务共享:每个任务各自 begin
async fn handler(pool: &sqlx::PgPool) -> Result<(), sqlx::Error> {
let mut tx = pool.begin().await?;
// ... 查询借用 &mut tx
tx.commit().await?;
Ok(())
}
常见误区
- 把
Transaction放进Arc共享给多个任务并发使用:可变连接无法安全共享。 - 绑定参数含非
Send类型跨 await,future 不满足 Send,编译报错。
追问
- 编译报 future 不满足 Send 怎么排查?答:找出跨 await 持有的非 Send 类型(如 Rc、引用跨线程),改为跨任务安全类型。
- 连接池为什么能共享而连接不能?答:池是线程安全的句柄集合,内部用同步结构管理空闲队列;单连接一次只服务一条事务链路。