Python sqlite3 怎样使用命名参数绑定查询

Python sqlite3使用命名参数时，在SQL中写:参数名，把不带冒号的同名键放进字典，再把字典作为execute的第二个参数传入。例如WHERE warehouse = :warehouse对应{"warehouse": "东仓"}。不要把值先拼进SQL，也不要给占位符加引号。

官方地址：https://www.python.org/

接口目标：让条件名字与业务含义一致

设想一个按仓库、最低库存和类别筛选商品的小工具。如果由我设计查询函数，我会把这些条件做成有名字的接口参数，让调用方看到warehouse、min_stock就能理解含义，而不必记住一个长元组的顺序。这是假设业务场景，下面示例没有连接真实库存库。

命名绑定解决的是“这个值对应哪个条件”。它不会自动检查业务范围，也不会把字典中所有键变成WHERE条件。SQL中实际出现的占位符才决定哪些值参与查询。查询函数仍应明确接受哪些条件，以及默认值代表什么。

参数设计：SQL写冒号，字典键不带冒号

# 值通过字典传给execute，SQL结构保持固定。
sql = "SELECT sku FROM inventory WHERE warehouse = :warehouse AND stock >= :min_stock"
params = {"warehouse": "东仓", "min_stock": 5}
rows = connection.execute(sql, params).fetchall()

warehouse和min_stock是参数名。SQL端有冒号，字典端没有；字典键应为字符串。不写成{":warehouse": "东仓"}，也不把SQL写成warehouse = ':warehouse'。后者是字符串字面量，数据库不会把引号内的文字识别成这里所需的参数。

同一个命名占位符在SQL中出现多次时，可以复用一个字典键。采用清楚的英文语义名比数字式名字更方便维护。Python sqlite3不支持PEP 249的数字占位符风格；形如:1的写法会被当作命名占位符，不应当作位置编号使用。

字典键顺序不需要与SQL中占位符顺序一致。若使用问号风格，则应提供与位置一一对应的序列。为了让接口错误更容易发现，同一条SQL保持一种占位符风格。

错误模型：缺键、空值和错误容器分别处理

如果多传了一个拼错的category键，而原SQL根本没有类别条件，驱动不会替你发现“少筛选了一项”。我会在查询函数入口构造一个最小字典，而不是把整份请求对象直接交给execute。

NULL要按SQL语义设计：column = :value在value为None时，不会筛出NULL行。明确查空值可用column IS NULL；可选过滤条件则可使用(:category IS NULL OR category = :category)，表示None时不按类别限制。这两种需求不同，不要用同一默认值混在一起。

调用方业务范围错误可提前抛ValueError；缺少绑定值属于ProgrammingError；SQL拼错或表不存在可能表现为OperationalError。不要把所有sqlite3.Error都转换为“查无记录”，否则故障会被隐藏。

兼容策略：参数只代表值，不能替换查询结构

命名参数适用于字符串、整数等值，不适用于表名、列名或ASC、DESC等SQL片段。ORDER BY :sort_col会把参数作为表达式值，而不是把它变成所指定的列；FROM :table_name也不能用来替换表名。排序选项应映射到开发者预先写好的固定片段，再选择对应查询。

IN (:items)也不会把Python列表自动展开成多个占位符。这里的筛选接口只接收一个仓库值和一个可选类别，避免把列表语义误塞进单个参数。需要多值筛选时，另外设计由受控占位符组成的结构，每个实际值仍单独绑定。

绑定参数能避免将数据直接拼成SQL，但不替代权限判断、字段范围检查和查询代价控制。比如LIKE条件中的%和_仍具有通配语义；是否允许通配搜索应由接口明确决定。

完整示例：用命名条件查询库存记录

以下原创示例使用内存库，写入三条演示库存，再调用带关键字参数的查询函数。仓库必填，最低库存是非负整数，category为None表示不限制类别；连接由调用方创建并关闭，查询函数不擅自提交或关闭连接。

import sqlite3

def find_inventory(connection, *, warehouse, min_stock=0, category=None):
    if not isinstance(warehouse, str) or not warehouse.strip():
        raise ValueError("warehouse必须是非空字符串")
    # 排除bool，避免将True意外当成库存数量1。
    if type(min_stock) is not int or min_stock = :min_stock
          AND (:category IS NULL OR category = :category)
        ORDER BY sku
    """
    params = {
        "warehouse": warehouse,
        "min_stock": min_stock,
        "category": category,
    }
    # 只绑定本查询使用的键，不传整个外部请求对象。
    return connection.execute(sql, params).fetchall()

connection = sqlite3.connect(":memory:")
try:
    connection.execute(
        "CREATE TABLE inventory (sku TEXT, warehouse TEXT, stock INTEGER, category TEXT)"
    )
    connection.executemany(
        "INSERT INTO inventory VALUES (:sku, :warehouse, :stock, :category)",
        [
            {"sku": "A10", "warehouse": "东仓", "stock": 8, "category": "配件"},
            {"sku": "A20", "warehouse": "东仓", "stock": 2, "category": "配件"},
            {"sku": "B10", "warehouse": "西仓", "stock": 12, "category": "耗材"},
        ],
    )
    connection.commit()  # 演示数据写入与查询接口的职责分开。
    rows = find_inventory(
        connection, warehouse="东仓", min_stock=5, category="配件"
    )
    print(rows)
finally:
    connection.close()  # 内存数据库随连接关闭释放。

按演示数据推导，结果应为[('A10', 8)]。这不是已执行的日志或性能测量。将category改为None，表示忽略类别条件；把min_stock设为0，则东仓两条记录都满足库存门槛，结果按sku排序。

executemany中的每个字典对应一条待执行的数据绑定。批量写入是否整体提交、失败如何回滚，需要按应用事务策略另行安排；命名占位符本身不改变事务边界。大型列表查询也应考虑读取规模，而不是默认无限fetchall。

字典可以多带几个键吗？

驱动会忽略额外项，但接口最好只构造所需键，减少拼错字段被静默忽略的机会。

命名参数可以绑定表名吗？

不能。表名和列名属于SQL结构，应从开发者控制的固定选项中选择。

None是不是“不传这个参数”？

不是，它是一个绑定为NULL的值。是否代表跳过过滤，要由SQL条件显式表达。

需要手动转义字符串中的单引号吗？

作为绑定值传入时不应自行拼接或替换引号。保持原始值，由驱动完成参数绑定。

官方资料：sqlite3占位符与参数绑定、Cursor.execute接口说明。