cursor.execute(sql1, args) 多参数占位符统一用 %s 的写法与验证

1. 从一次 TypeError 说起：为什么 args 里全是 %s 才不报错

cursor.execute(sql1, args)这个调用形式，在 Python 的 DB-API 里几乎天天见。它看起来很简单：一条 SQL，一个参数序列，交给驱动去执行。但真正踩过坑的人都知道，参数占位符的写法一旦不统一，报错信息往往和 SQL 本身毫无关系，而是直接抛在 Python 层，比如TypeError: must be real number, not str。

这个报错的迷惑性在于：你明明写的是%f对应浮点数、%s对应字符串，看起来类型对得上，为什么还报“需要实数，却给了字符串”？原因不在你的数据，而在驱动内部对参数的处理路径。以 MySQLdb / mysqlclient 这类驱动为例，cursor.execute(sql, args)在底层会先做一次参数转义，把args里的值按占位符类型格式化进 SQL。如果 SQL 里混用了%f、%d、%s，驱动会尝试按每个占位符去匹配参数类型；一旦某个位置期望的是数字格式，而参数序列里对应位置的值在转义阶段被当成字符串处理，就会在query % self._escape_args(args, conn)这一行炸掉。

更关键的是，很多驱动对args的默认处理是“全部按字符串转义”，然后再交给 SQL 层。也就是说，%s是唯一被广泛保证能正确工作的占位符。你写%f，驱动可能仍然按字符串去转义，最后格式化时类型不匹配，于是报must be real number, not str。这不是你的数据错了，而是占位符和驱动预期不一致。

所以结论很直接：只要用cursor.execute(sql1, args)这种“参数序列 + 占位符”的形式，args 里所有占位符统一写成%s。数字、字符串、日期、None，全部用%s，驱动会自己处理类型转换。混用%(name)s或?会触发不同的报错：%(name)s需要 args 是字典，传列表会报TypeError: format requires a mapping；?是 sqlite3 的风格，在 MySQL 驱动里会直接当成普通字符，导致 SQL 语法错误或参数数量不匹配。

这个场景适合所有用 Python 连数据库的人，尤其是从 sqlite3 切到 MySQL、或者从 ORM 切回原生 SQL 的开发者。下面我把可复制的配置、验证步骤和排错过程完整写一遍，你可以直接跟着做。

2. 前置准备：TaoToken 接入与本地数据库环境

在写参数化 SQL 之前，先把两件事准备好：一个是模型/API 侧的接入配置，方便你在写 SQL 时随时让模型帮你检查占位符；另一个是本地数据库环境，用来真实验证%s的行为。

TaoToken 的接入地址是https://taotoken.net/api，API Key 在控制台创建。如果你只是想让模型帮你审查 SQL 占位符，用模型对话就够了；如果你在写一个长期跑的 Agent 或编码助手，可以考虑 Coding Plan。下面给出一份可复制的配置片段，路径和字段名保持原样，你按自己的环境替换 Key 即可。

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "claude-sonnet-4-20250514", "timeout": 60 }

如果你用的是 Claude Code 这类工具，配置通常落在settings.json或对应的环境变量里。核心三件套是 Base URL、API Key、Model ID，缺一不可。Base URL 填https://taotoken.net/api，Key 填控制台生成的，Model ID 按你实际要用的模型填。写 SQL 检查提示词时，可以直接把cursor.execute(sql1, args)和 args 列表贴给模型，让它指出占位符是否统一。

本地数据库这边，我建议同时准备 sqlite3 和 MySQL 两个环境，因为它们的占位符风格不同，正好用来对比验证。sqlite3 是 Python 内置的，直接import sqlite3就能用，它的占位符是?或:name。MySQL 需要装驱动，常见的是mysqlclient或PyMySQL。用pip install mysqlclient或pip install pymysql即可。

建一张测试表，字段覆盖数字和字符串：

CREATE TABLE car_now ( id INT PRIMARY KEY, blood_min FLOAT, blood_max FLOAT, body FLOAT, heart FLOAT, alcohol VARCHAR(64) );

插入一行初始数据，方便后面 UPDATE 验证：

INSERT INTO car_now (id, blood_min, blood_max, body, heart, alcohol) VALUES (1, 0, 0, 0, 0, 'none');

到这里，环境就齐了。接下来进入核心部分：把cursor.execute(sql1, args)的占位符统一成%s，并写出可复制的配置片段。

3. 可复制配置：cursor.execute 多参数统一 %s 的写法

先看错误写法，也就是 excerpt 里那段：

args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol] sql1 = "UPDATE car_now SET blood_min = %f, blood_max = %f, body = %f, heart = %f, alcohol = %s WHERE id = 1;" cursor.execute(sql1, args)

这段代码在 MySQLdb 下会报TypeError: must be real number, not str。原因是%f期望的是数字格式，但驱动在_escape_args阶段可能已经把参数按字符串处理，格式化时类型对不上。正确写法是把所有占位符统一成%s：

args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol] sql1 = "UPDATE car_now SET blood_min = %s, blood_max = %s, body = %s, heart = %s, alcohol = %s WHERE id = 1;" cursor.execute(sql1, args)

注意id = 1这里我写死了，如果你也想参数化，就再加一个%s，并把 1 放进 args：

args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol, 1] sql1 = "UPDATE car_now SET blood_min = %s, blood_max = %s, body = %s, heart = %s, alcohol = %s WHERE id = %s;" cursor.execute(sql1, args)

这里有一个容易忽略的点：args必须是序列（list 或 tuple），不能是字典。如果你写成%(name)s，args 就必须是 dict，否则报TypeError: format requires a mapping。而?是 sqlite3 的风格，在 MySQL 驱动里不会被识别为占位符，SQL 会原样发给数据库，导致语法错误或参数数量不匹配。

为了让你一次写对，我把三种占位符的对应关系整理成表：

如果你用 sqlite3，写法是：

import sqlite3 conn = sqlite3.connect("test.db") cursor = conn.cursor() args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol] sql1 = "UPDATE car_now SET blood_min = ?, blood_max = ?, body = ?, heart = ?, alcohol = ? WHERE id = 1;" cursor.execute(sql1, args) conn.commit()

注意 sqlite3 用?，不要用%s，否则 sqlite3 会把%s当成普通字符串，导致 SQL 里出现字面量%s，更新失败但不报错，这种静默错误更危险。

如果你用 PyMySQL，写法是：

import pymysql conn = pymysql.connect(host="127.0.0.1", user="root", password="yourpass", database="test") cursor = conn.cursor() args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol] sql1 = "UPDATE car_now SET blood_min = %s, blood_max = %s, body = %s, heart = %s, alcohol = %s WHERE id = 1;" cursor.execute(sql1, args) conn.commit()

PyMySQL 和 MySQLdb 都认%s，所以这份写法可以直接复用。关键就是：args 是序列，占位符全用%s，不要混%f、%d、%(name)s、?。

4. 验证请求与成功结果：本地跑一遍看输出

配置写好后，必须真跑一遍，看cursor.execute是否成功、数据是否更新。下面给出完整的验证脚本，你可以直接复制到本地运行。

先验证 MySQL 场景：

import pymysql conn = pymysql.connect( host="127.0.0.1", user="root", password="yourpass", database="test", charset="utf8mb4" ) cursor = conn.cursor() result_blood_min = 1.2 result_blood_max = 5.6 result_tem = 36.5 result_heart = 72.0 date_alcohol = "2025-01-01" args = [result_blood_min, result_blood_max, result_tem, result_heart, date_alcohol] sql1 = "UPDATE car_now SET blood_min = %s, blood_max = %s, body = %s, heart = %s, alcohol = %s WHERE id = 1;" try: cursor.execute(sql1, args) conn.commit() print("execute ok, rowcount =", cursor.rowcount) except Exception as e: print("execute failed:", repr(e)) conn.rollback() cursor.execute("SELECT blood_min, blood_max, body, heart, alcohol FROM car_now WHERE id = 1;") print("after update:", cursor.fetchone()) cursor.close() conn.close()

预期输出：

execute ok, rowcount = 1 after update: (1.2, 5.6, 36.5, 72.0, '2025-01-01')

如果你把%s改回%f，同样的脚本会输出：

execute failed: TypeError('must be real number, not str')

这就复现了 excerpt 里的报错。注意rowcount = 1表示影响了一行，说明 UPDATE 生效。如果rowcount = 0，说明 WHERE 条件没匹配到，检查 id 是否为 1。

再验证 sqlite3 场景：

import sqlite3 conn = sqlite3.connect("test.db") cursor = conn.cursor() args = [1.2, 5.6, 36.5, 72.0, "2025-01-01"] sql1 = "UPDATE car_now SET blood_min = ?, blood_max = ?, body = ?, heart = ?, alcohol = ? WHERE id = 1;" cursor.execute(sql1, args) conn.commit() print("sqlite rowcount =", cursor.rowcount) cursor.execute("SELECT blood_min, blood_max, body, heart, alcohol FROM car_now WHERE id = 1;") print("sqlite after update:", cursor.fetchone()) cursor.close() conn.close()

预期输出：

sqlite rowcount = 1 sqlite after update: (1.2, 5.6, 36.5, 72.0, '2025-01-01')

如果你在 sqlite3 里误用%s，脚本不会报错，但rowcount可能是 0，或者查询结果里出现字面量%s。这种静默失败最容易被忽略，所以验证时一定要看rowcount和实际数据。

如果你想让模型帮你检查占位符，可以把 SQL 和 args 贴到模型对话里，让它逐个数占位符数量是否和 args 长度一致。TaoToken 的模型对话入口在控制台里，Base URL 用https://taotoken.net/api，Key 用你创建的。检查提示词可以这样写：“下面这段 cursor.execute 的 SQL 和 args，占位符是否统一为 %s，数量和 args 是否一致，有没有混用 %f 或 ?”。模型会直接指出问题位置。

5. 常见报错排查：401、local proxy failed、reading choices、OAuth

这一节把你在接入和验证过程中可能遇到的报错集中列出来，对照真实错误信息排查。

401 Unauthorized：API Key 不对或没带。检查请求头里的 Authorization 是否为Bearer sk-你的Key，Key 是否从 TaoToken 控制台正确复制，有没有多余空格。如果用的是 Claude Code 或 Cline MCP，检查settings.json里的api_key字段是否和 Base URL 配套。Base URL 填https://taotoken.net/api，不要漏掉/api。

local proxy failed：本地代理配置有问题。先确认你没有在环境变量里设置HTTP_PROXY、HTTPS_PROXY指向一个不可用的地址。如果你用的是公司网络，检查是否需要走内网代理。这个报错和 SQL 占位符无关，但会阻断你调用模型检查 SQL 的流程，所以先解决它。

reading choices 报错：通常出现在调用模型接口后解析响应时，提示读取choices字段失败。原因可能是返回体不是预期的 JSON 结构，比如返回了 HTML 错误页。检查 Base URL 是否写成了https://taotoken.net/api而不是其他路径，Model ID 是否拼写正确。如果返回体里没有choices，先打印原始响应内容，看是不是 401 或 404 的 HTML。

OAuth 相关报错：如果你用 Claude Code 的 OAuth 登录方式，报错通常和 token 过期或回调地址不匹配有关。检查settings.json里的 OAuth 配置，确认回调端口没有被占用。如果同时配了 API Key 和 OAuth，优先用 API Key，避免冲突。

占位符相关报错对照：

排查顺序建议：先看报错是 Python 层还是数据库层。Python 层的TypeError基本都是占位符和 args 类型不匹配；数据库层的ProgrammingError多半是 SQL 语法或表字段问题。把 SQL 和 args 分别打印出来，逐个数占位符，是最快的定位方法。

如果你在 Cline MCP 或 Codex 的auth.json里配置了模型，出现reading choices报错时，检查auth.json里的base_url是否为https://taotoken.net/api，model字段是否和实际调用的模型一致。三件套 Base URL、Key、Model ID 任何一个写错都会导致解析失败。

6. 语义一致 CTA：把占位符写对之后

占位符统一成%s这件事，本质上是在对齐驱动对参数的处理预期。你写%f的时候，以为是在告诉驱动“这是浮点数”，但驱动在转义阶段可能已经把它当字符串处理了，格式化时才炸。统一%s之后，类型转换交给驱动和数据库，你只需要保证 args 的顺序和占位符一一对应。

如果你在写一个长期跑的编码助手或 Agent，需要反复检查 SQL 占位符、生成参数化查询，可以用 Coding Plan，把模型对话和代码检查串起来。入口在https://taotoken.net/api对应的控制台里，创建 Key 后按前面的 JSON 片段配置即可。如果你只是想快速验证一段 SQL 的占位符写法，用模型对话把 SQL 和 args 贴进去，让它数占位符数量、检查是否混用，比手动数快得多。

接入文档里有完整的 Base URL、Key、Model ID 配置说明，遇到 401 或 reading choices 报错时对照排查。API Keys 页面可以创建和管理 Key，注意不要泄露。把这篇里的验证脚本在本地跑一遍，你会对cursor.execute(sql1, args)的占位符行为有更直观的认识。下次再看到must be real number, not str，直接检查是不是混用了%f和%s，改成全%s就能解决。