Python sqlite3怎么防止SQL注入？参数化查询的正确写法

在 Python 中使用内置的 sqlite3 模块时，防止 SQL 注入最直接、有效且唯一受到官方推荐的核心手段是参数化查询（Parameterized Queries）。参数化查询的本质是将“SQL 语法逻辑”与“用户传入的数据”从底层解析阶段进行严格剥离，无论用户输入中包含何种破坏性的 SQL 关键字或引号，数据库引擎都仅将其视作纯粹的字面值变量，而绝不重新编译或执行其中的逻辑。

一、SQL 注入的根源与参数化原理对比

许多初学者习惯使用 Python 的字符串拼接或格式化方法来组装查询，例如使用 + 拼接、% 操作符、str.format() 或 f-string（格式化字符串字面值）。这种做法之所以危险，是因为数据库在接收到整串 SQL 时，词法分析器和语法分析器无法区分哪些字符属于开发者的业务指令，哪些字符属于外部输入的文本。一旦外部输入包含了类似 ' OR '1'='1 的字符串，SQL 解析树就会发生语法结构形变，原本的条件约束直接被改写。

而参数化查询要求我们在编写 SQL 模板时，在需要填充数据的地方放置占位符。执行时，驱动程序先将固定的 SQL 结构交付 SQLite 引擎完成词法分析与预编译，确定执行计划；随后驱动程序将参数作为独立的值绑定至预留槽位中。即使参数内容是复杂的 SQL 语句，也只会被作为普通字符串进行值比较，从物理上杜绝了语法被篡改的可能。

图 1：字符串拼接与参数化查询底层解析机制对比

二、sqlite3 参数化查询的标准写法

在 Python 的 DB-API 规范（PEP 249）及 sqlite3 驱动实现中，支持两种主要的占位符风格：问号占位符（qmark）与命名占位符（named）。在任何情况下，占位符两侧都绝对不要加单引号或双引号，SQLite 引擎会自动识别参数的数据类型并做规范绑定。

1. 问号占位符（qmark 风格）

问号占位符使用英文字符 ? 代表待填入的数据值，传给 cursor.execute() 的第二个参数必须是一个包含所有参数的序列（Sequence），通常使用元组（tuple）或列表（list）。

import sqlite3

# 建立连接与游标
conn = sqlite3.connect(":memory:")
cursor = conn.cursor()

# 创建示例表
cursor.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username TEXT, balance REAL)")

# 正确写法：插入数据（使用问号占位符，参数通过元组传递）
cursor.execute("INSERT INTO users (username, balance) VALUES (?, ?)", ("alice", 100.5))

# 正确写法：查询单条数据（特别注意：单元素元组必须包含尾随逗号）
target_user = "alice"
cursor.execute("SELECT id, username, balance FROM users WHERE username = ?", (target_user,))
user = cursor.fetchone()
print("查询结果:", user)

conn.commit()
conn.close()

2. 命名占位符（named 风格）

当字段较多或查询条件复杂时，按位置对应的 ? 容易混淆顺序。此时推荐使用命名占位符，其格式为 :参数名，第二个参数传递 Python 字典（dict）。

import sqlite3

conn = sqlite3.connect(":memory:")
cursor = conn.cursor()

cursor.execute("CREATE TABLE products (id INTEGER PRIMARY KEY, name TEXT, price REAL, stock INTEGER)")

# 使用命名占位符插入
product_data = {
    "item_name": "Mechanical Keyboard",
    "item_price": 499.0,
    "item_stock": 50
}
cursor.execute(
    "INSERT INTO products (name, price, stock) VALUES (:item_name, :item_price, :item_stock)",
    product_data
)

# 使用命名占位符做多条件筛选
query_conditions = {
    "min_price": 200.0,
    "min_stock": 10
}
cursor.execute(
    "SELECT name, price FROM products WHERE price >= :min_price AND stock >= :min_stock",
    query_conditions
)
print("筛选结果:", cursor.fetchall())

conn.close()

3. 批量操作防注入：executemany

需要批量插入或更新多条记录时，严禁使用循环拼接 SQL，而应使用 executemany()。该方法同样享受参数化绑定的安全隔离，并具备显著的执行性能优势。

# 批量插入记录，参数为一个包含多个元组的列表
batch_records = [
    ("bob", 200.0),
    ("charlie", 350.0),
    ("david", 50.0)
]
cursor.executemany("INSERT INTO users (username, balance) VALUES (?, ?)", batch_records)

图 2：sqlite3 参数化操作标准化执行生命周期

三、常见的“假参数化”误区与防御边界

掌握了基础写法后，开发者常在一些复杂或动态场景下误入陷阱。有些看似使用了占位符的代码，由于写法变形，本质上依然处于完全未设防的注入状态。

1. 伪参数化：将拼接语句送入 execute

# 严重错误示范：虽然调用了 execute，但依然是字符串拼接！
user_input = "malicious_string"
cursor.execute(f"SELECT * FROM users WHERE username = '{user_input}'") # 漏洞依然存在！
cursor.execute("SELECT * FROM users WHERE username = '%s'" % user_input) # 同样危险！

只要 SQL 语句在抵达 execute() 之前已经被 Python 运行时插值合并，哪怕函数名叫 execute，也无法提供任何保护。安全的前提必须是：SQL 字符串自身保持静态模板形式，输入值单独作为第二个参数交由驱动传递。

2. 占位符不能用于表名、列名和 SQL 关键字

这是绝大多数开发者容易踩中的认知盲区：SQLite 的参数化占位符只能代表数据值（Value），不能用于数据库标识符（表名、列名、索引名）或关键字（ASC/DESC 等）。如果写出 cursor.execute("SELECT * FROM ?", (table_name,))，SQLite 会在预编译阶段直接抛出 sqlite3.OperationalError: near "?": syntax error 语法错误。

当业务确实需要动态指定查询表名、排序列或排序方向时，不能也不可能使用 ?，此时正确的防御策略是基于程序内严格的白名单校验（Whitelist Validation）：

# 动态指定表名与排序字段的安全实现
ALLOWED_TABLES = {"users", "admins", "guests"}
ALLOWED_COLUMNS = {"id", "created_at", "username"}

def get_sorted_records(table_name: str, sort_col: str, min_id: int):
    # 第一步：白名单严格校验标识符，杜绝非法字符与SQL注入
    if table_name not in ALLOWED_TABLES:
        raise ValueError(f"非法的表名请求: {table_name}")
    if sort_col not in ALLOWED_COLUMNS:
        raise ValueError(f"非法的排序列请求: {sort_col}")

    # 第二步：标识符通过白名单后安全拼入，而数据值仍然严格使用参数化
    sql = f"SELECT * FROM {table_name} WHERE id >= ? ORDER BY {sort_col} ASC"
    cursor.execute(sql, (min_id,))
    return cursor.fetchall()

3. LIKE 模糊查询的通配符陷阱

在进行模糊查询时，许多人试图写出 WHERE title LIKE '%?%'。在 SQL 语法中，处于单引号内部的 ? 只会被视作普通的问号文字符号，而不再具有占位符功能。正确的处理方法是保持 SQL 模板为 WHERE title LIKE ?，并将 % 通配符在 Python 中拼接到参数内容上：

keyword = "python"
# 正确写法：占位符不加引号，通配符由参数值自身携带
cursor.execute("SELECT * FROM articles WHERE title LIKE ?", (f"%{keyword}%",))

4. IN 语句多值查询的动态占位符构建

若需要查询满足列表内任意 ID 的记录，写成 WHERE id IN (?) 并传入 (id_list,) 是错误的，SQLite 会将整个列表视作一个不可比对的复合对象或仅匹配第一个值。安全的做法是根据待查序列的长度，安全地在 SQL 中生成对应数量的 ?：

target_ids = [101, 102, 105, 108]
if not target_ids:
    records = []
else:
    # 动态安全生成 "?, ?, ?, ?"
    placeholders = ",".join("?" for _ in target_ids)
    sql = f"SELECT id, name FROM items WHERE id IN ({placeholders})"
    cursor.execute(sql, target_ids)
    records = cursor.fetchall()

图 3：动态 SQL 输入处理与防御边界决策树

四、安全防护体系与最佳实践总结

在工程实践中，为了从代码审查、架构设计与单元测试层面彻底阻断注入风险，可以建立如下标准化防线：

• 零容忍代码审查规则：在静态代码扫描（如 Bandit、SonarQube）或日常 PR 评审中，一旦发现 cursor.execute(f"...") 或 cursor.execute("..." % ...)，立即拦截并驳回。无论输入来源看似多么“安全”，都不应破坏参数化隔离原则。
• 明确数据与结构的分工：数据值 100% 走参数化绑定；结构标识符 100% 走白名单匹配。
• 妥善管理连接生命周期：尽量结合 Python 的上下文管理器（with conn:）或 try...finally 块，确保事务在异常发生时能回滚，且连接被正确关闭。

图 4：Python sqlite3 防注入安全规范体系总览

五、常见问题解答（FAQ）