1. 为什么查 MySQL 总拿到元组，而不是键值对
用 Python 连 MySQL 查数据，很多人第一次跑出来的结果长这样：(1, 'alice', 'alice@example.com')。字段顺序全靠脑记，一旦表结构改了列顺序，row[2]取到的可能就不是邮箱而是手机号，排查起来非常费劲。你真正想要的是{'id': 1, 'username': 'alice', 'email': 'alice@example.com'}这种键值对形式，用字段名取值，代码可读性和抗变更能力都强一个档次。
这篇就围绕「Python 查询 MySQL 以键值对方式返回」这件事展开：先讲清楚游标类型怎么决定返回结构，再给出一份可复制的连接参数与结果转换代码，最后把 TaoToken 统一 Key 的settings.json配置骨架接进来，演示一次真实查询验证动作。适合刚接触 Python + MySQL、想把查询结果直接当字典用的同学，也适合已经在用 ORM、但偶尔要写原生 SQL 的开发者。
核心结论先放这里：键值对返回不是靠fetchall()本身，而是靠游标类型。MySQLdb 用DictCursor，PyMySQL 用pymysql.cursors.DictCursor，mysql-connector 用dictionary=True。选对游标，fetchone()和fetchall()出来的就是字典或字典列表。
2. TaoToken 统一 Key 与 settings.json 配置骨架
在写数据库代码之前，先把外部 API 通道的配置理顺。TaoToken 提供统一 Key 和统一 API 入口，把模型调用、编码辅助这类请求收敛到一个地址和一个密钥上，配置文件里不用散落一堆不同厂商的 key。官网地址是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api 。
我习惯把这类配置集中放在项目根目录的settings.json里，数据库连接和 API 通道分开两个块，互不干扰。下面这份骨架你可以直接抄，把占位值换成自己的即可：
{ "database": { "host": "127.0.0.1", "port": 3306, "user": "app_user", "password": "your_db_password", "database": "demo", "charset": "utf8mb4" }, "taotoken": { "base_url": "https://taotoken.net/api", "api_key": "sk-你的统一Key", "default_model": "claude-sonnet-4-5", "timeout": 60 } }这里有几个点值得说明。charset一定写utf8mb4，不然中文和 emoji 容易变问号。taotoken.base_url只写到/api，具体路径由 SDK 或请求拼接，不要自己乱加后缀。api_key建议从环境变量注入，别硬编码进仓库，后面第 3 节会给读取方式。
统一 Key 的申请入口在控制台的 API Keys 页面：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。拿到 key 后填进settings.json的api_key字段即可。如果你后续要做长期编码或 Agent 类任务，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。
注意：
settings.json里出现明文密钥时，务必把该文件加入.gitignore，或者改用os.environ读取，避免密钥进版本库。
3. 可复制配置：连接参数与键值对游标写法
这一节是全文重点，直接给能跑的代码。先装驱动，PyMySQL 是纯 Python 实现，安装无编译依赖，推荐新手用：
pip install pymysql然后写一个读取配置 + 建立连接 + 键值对查询的完整脚本。注意游标那行cursorclass=pymysql.cursors.DictCursor，它就是键值对的开关：
import json import os import pymysql # 读取 settings.json，密钥优先走环境变量 with open("settings.json", "r", encoding="utf-8") as f: cfg = json.load(f) db_cfg = cfg["database"] db_cfg["password"] = os.environ.get("DB_PASSWORD", db_cfg["password"]) conn = pymysql.connect( host=db_cfg["host"], port=db_cfg["port"], user=db_cfg["user"], password=db_cfg["password"], database=db_cfg["database"], charset=db_cfg["charset"], cursorclass=pymysql.cursors.DictCursor, # 关键：返回字典 ) try: with conn.cursor() as cursor: cursor.execute("SELECT id, username, email FROM users LIMIT 5") rows = cursor.fetchall() for row in rows: print(row["id"], row["username"], row["email"]) finally: conn.close()如果你用的是 MySQLdb，写法几乎一样，只是游标类换成MySQLdb.cursors.DictCursor，连接用MySQLdb.connect(...)。用 mysql-connector-python 的话，是在connect()里加dictionary=True，不用指定游标类。三种驱动对照如下：
| 驱动 | 键值对开关 | 取值方式 |
|---|---|---|
| PyMySQL | cursorclass=pymysql.cursors.DictCursor | row["字段名"] |
| MySQLdb | cursorclass=MySQLdb.cursors.DictCursor | row["字段名"] |
| mysql-connector | connect(..., dictionary=True) | row["字段名"] |
有时候你不想改游标类型，只想把已有的元组结果转成字典，可以用cursor.description拿字段名再zip：
with conn.cursor() as cursor: cursor.execute("SELECT id, username, email FROM users LIMIT 5") cols = [d[0] for d in cursor.description] rows = [dict(zip(cols, r)) for r in cursor.fetchall()] print(rows[0]["username"])这种转换方式适合临时场景，但字段多的时候不如直接用 DictCursor 干净。另外提醒一句，fetchone()在 DictCursor 下返回单个字典，查不到数据时返回None，取值前记得判空。
4. 验证请求：跑一次查询看键值对结果
配置写完，跑一次验证动作确认链路通。先准备一张测试表和几条数据：
CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50), email VARCHAR(100) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4; INSERT INTO users (username, email) VALUES ('alice', 'alice@example.com'), ('bob', 'bob@example.com');执行第 3 节的脚本，预期输出类似：
1 alice alice@example.com 2 bob bob@example.com如果打印出来是这种带字段名的结构，说明键值对返回已经生效。再补一个单条查询的验证，确认fetchone()行为：
with conn.cursor() as cursor: cursor.execute("SELECT id, username FROM users WHERE username=%s", ("alice",)) row = cursor.fetchone() print(type(row), row) # 预期：<class 'dict'> {'id': 1, 'username': 'alice'}看到type是dict，键值对查询就算跑通了。这里顺带说下参数化查询：execute的第二个参数用元组传值，别用字符串拼接，能防 SQL 注入。占位符 PyMySQL 和 MySQLdb 都用%s，不是?。
如果你还想顺手验证 TaoToken 通道是否可用，可以用统一 Key 发一次模型对话请求，确认settings.json里的base_url和api_key配置正确。模型对话入口：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_content=models&utm_campaign=rewrite 。接入细节可查文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。
5. 本篇常见错排查
报错ModuleNotFoundError: No module named 'pymysql'：驱动没装或装到了别的 Python 环境。用python -m pip install pymysql明确指定解释器，再python -c "import pymysql; print(pymysql.__version__)"确认。
结果还是元组，不是字典：八成是游标类没生效。检查connect()里cursorclass是否拼写正确，或者你是不是在conn.cursor()时又覆盖了游标类型。mysql-connector 用户检查dictionary=True有没有漏。
KeyError: 'username'：字段名对不上。DictCursor 的键是 SQL 里SELECT的列名或别名，SELECT username AS name之后就得用row["name"]。大小写敏感取决于系统，建议统一小写。
中文乱码：连接参数charset没设成utf8mb4，或者表本身不是这个字符集。两边都要对齐。
pymysql.err.OperationalError: (2003, ...)：连不上数据库。先确认 host、port 可达，再确认用户有远程访问权限，本地测试用127.0.0.1比localhost更少踩 socket 的坑。
settings.json读取报JSONDecodeError：文件里有注释或尾逗号。JSON 标准不支持注释，删掉再试，或者改用json5解析。
密钥泄露风险：api_key和数据库密码别写死在代码里，用环境变量或密钥管理服务。提交前git diff扫一眼。
6. 把配置和查询固化下来
键值对查询这件事，一旦游标类型选对，剩下的就是工程习惯问题。我的做法是把数据库连接封装成一个get_conn()函数，settings.json只放非敏感默认值，密码和统一 Key 走环境变量，脚本里统一with conn.cursor() as cursor管理资源。这样无论是写报表脚本还是接进服务，返回的都是字典，下游处理不用再关心列顺序。
TaoToken 的统一 Key 在这里的价值是：外部 API 通道和数据库配置放在同一份settings.json里管理，换环境只改一个文件，不用满项目找 key。API Keys 管理页在 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。先把第 3 节脚本跑通，再按第 4 节验证一次，键值对查询就彻底落地了。
