拓冰网站定制 
1. 为什么你的查询结果总是元组字段取值全靠猜写 Python 连数据库很多人第一次跑通SELECT之后都会遇到同一个别扭fetchall()返回的是一堆元组想拿某个字段只能靠下标。比如row[3]到底是email还是created_at得翻回建表语句数一遍。表字段一改下标全乱线上报错还特别隐蔽——因为row[3]语法上永远合法只是取错了值。这个问题的根源在于 DB-API 规范。Python 的数据库驱动默认游标cursor返回的是「序列」而不是「映射」MySQL 的 PyMySQL、PostgreSQL 的 psycopg2 都是如此。序列的好处是轻量、内存占用小坏处是可读性差、维护成本高。对写业务代码的人来说row[email]比row[3]强太多字段名即文档重构时改列名能立刻暴露问题而不是悄悄取错。我试过在一个中等规模的项目里把几十处row[2]全部换成字典取值改完之后代码 review 的效率肉眼可见地提升——因为再也不用对着 schema 数下标了。这篇就聚焦一件事怎么把 Python 数据库查询的默认元组返回改成直接按列名访问的字典类型。覆盖 MySQLPyMySQL / mysqlclient和 PostgreSQLpsycopg2 / psycopg3两套主流组合给出可复制的游标配置、查询结果转字典的写法以及验证步骤。适合正在用 MySQL 或 PostgreSQL 做后端、被元组下标折磨过的开发者。核心检索词先摆出来Python 数据库查询默认返回元组通过设置字典游标DictCursor可以让查询结果直接按列名访问。下面从环境准备讲到排错每一步都能直接抄。2. 前置准备TaoToken 接入与依赖安装在动手改游标之前先把模型调用这条链路准备好。很多同学调 SQL 的时候顺手让模型帮忙生成查询、解释报错如果模型接入没配好来回切换会很烦。TaoToken 提供统一的 API 入口把模型对话、编码辅助这些能力收敛到一个 Base URL 下配置一次就能在脚本、编辑器插件、命令行工具里复用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接用它作为 Base URL 即可。你需要先在控制台创建一个 API Key路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建后复制那串sk-开头的密钥后面配置里会用到。模型对话的调试页面在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以先用它验证 Key 是否可用。如果你打算长期做编码和 Agent 类任务Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有套餐说明按需选择就行。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题优先查它。数据库这边的依赖MySQL 用 PyMySQL 最省事纯 Python 实现装起来没有编译负担pip install pymysql如果你用的是 mysqlclient基于 C 的 MySQLdb安装命令是pip install mysqlclientPostgreSQL 用 psycopg2 的话pip install psycopg2-binary新版 psycopg3 则是pip install psycopg[binary]连接池如果要用DBUtils 可以一起装上pip install dbutils环境变量建议单独放别把密码写死在代码里。建一个.env或者直接用系统环境变量export DB_HOST127.0.0.1 export DB_PORT3306 export DB_USERroot export DB_PASSyour_password export DB_NAMEuser export TAOTOKEN_API_KEYsk-你的密钥这样脚本里用os.environ读取换环境不用改代码。前置准备做完下面进入正题游标配置。3. 可复制配置DictCursor 与字典游标完整写法这一节是全文的核心直接给可复制的配置片段。先说 MySQL 的 PyMySQL关键参数就是cursorclasspymysql.cursors.DictCursor。注意它是在建立游标时指定不是在connect()时指定虽然connect()也支持cursorclass默认值但显式写在cursor()上更清晰。import os import pymysql conn pymysql.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, ) # 关键建立游标时传入 DictCursor cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user WHERE id %s, (1,)) row cursor.fetchone() print(row) # {id: 1, name: alice, email: aexample.com} print(row[email]) # 直接按列名取值 cursor.close() conn.close()fetchall()返回的就是一个列表每个元素是字典cursor.execute(SELECT id, name FROM user LIMIT 3) rows cursor.fetchall() for r in rows: print(r[id], r[name])如果你用 mysqlclientMySQLdb写法几乎一样只是模块名不同import MySQLdb import MySQLdb.cursors conn MySQLdb.connect( hostos.environ[DB_HOST], useros.environ[DB_USER], passwdos.environ[DB_PASS], dbos.environ[DB_NAME], charsetutf8mb4, ) cursor conn.cursor(MySQLdb.cursors.DictCursor) cursor.execute(SELECT id, name FROM user) print(cursor.fetchall())PostgreSQL 的 psycopg2 用的是cursor_factory不是cursorclass这点容易搞混import os import psycopg2 import psycopg2.extras conn psycopg2.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 5432)), useros.environ[DB_USER], passwordos.environ[DB_PASS], dbnameos.environ[DB_NAME], ) cursor conn.cursor(cursor_factorypsycopg2.extras.RealDictCursor) cursor.execute(SELECT id, name, email FROM users WHERE id %s, (1,)) print(cursor.fetchone()) # {id: 1, name: alice, email: aexample.com}psycopg3 的写法又变了用row_factoryimport psycopg from psycopg.rows import dict_row with psycopg.connect( hostos.environ[DB_HOST], useros.environ[DB_USER], passwordos.environ[DB_PASS], dbnameos.environ[DB_NAME], ) as conn: with conn.cursor(row_factorydict_row) as cur: cur.execute(SELECT id, name FROM users) print(cur.fetchall())连接池场景下DBUtils 的PooledDB也能指定游标类。下面这段是 MySQL 连接池 字典游标的完整配置import pymysql from dbutils.pooled_db import PooledDB POOL PooledDB( creatorpymysql, maxconnections5, hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, cursorclasspymysql.cursors.DictCursor, # 池级别默认字典游标 ) conn POOL.connection() cursor conn.cursor() cursor.execute(SELECT id, name FROM user) print(cursor.fetchall()) cursor.close() conn.close()注意PooledDB里cursorclass是传给creator的默认参数这样每次从池里拿到的游标都是字典游标不用每次手动指定。如果你只想某次查询用字典、其他查询用元组就在conn.cursor()时单独传覆盖池的默认值。各驱动的参数对照表驱动参数名取值返回类型PyMySQLcursorclasspymysql.cursors.DictCursordictmysqlclientcursorMySQLdb.cursors.DictCursordictpsycopg2cursor_factorypsycopg2.extras.RealDictCursordictRealDictpsycopg3row_factorypsycopg.rows.dict_rowdict注意psycopg2 的RealDictCursor返回的是RealDictRow它是 dict 的子类用法和普通字典一致但json.dumps时可能需要先dict(row)转换。psycopg3 的dict_row返回的是标准 dict。配置给完了下一节验证请求确认真的按列名取到了值。4. 验证请求查询结果转字典与字段名取值实测配置写完必须验证不然你不知道游标到底生效没有。先写一个最小可跑的脚本把连接、查询、取值、打印串起来。下面这段用 PyMySQL你可以直接复制运行把环境变量换成自己的。import os import pymysql def get_conn(): return pymysql.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, ) def main(): conn get_conn() cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user LIMIT 3) rows cursor.fetchall() # 验证 1类型检查 print(rows type:, type(rows)) print(row type:, type(rows[0]) if rows else empty) # 验证 2按列名取值 for r in rows: print(fid{r[id]}, name{r[name]}, email{r[email]}) # 验证 3转成标准 dict 再序列化 import json print(json.dumps([dict(r) for r in rows], ensure_asciiFalse)) cursor.close() conn.close() if __name__ __main__: main()预期输出类似rows type: class list row type: class dict id1, namealice, emailaexample.com id2, namebob, emailbexample.com id3, namecarol, emailcexample.com [{id: 1, name: alice, email: aexample.com}, ...]看到row type: class dict就说明字典游标生效了。如果打印出来是class tuple说明游标参数没传对回到上一节检查。再验证一个容易忽略的点字段名大小写。MySQL 在 Linux 下默认表名区分大小写但列名返回的 key 通常和SELECT里写的一致。如果你写SELECT ID, NAME字典的 key 就是ID、NAME。PostgreSQL 更严格不加引号的标识符会被折叠成小写所以SELECT ID返回的 key 是id。这点在跨库迁移时特别容易踩。# PostgreSQL 验证注意 key 是小写 cursor.execute(SELECT ID, NAME FROM users) row cursor.fetchone() print(row.keys()) # dict_keys([id, name])如果你想让查询结果直接变成对象属性访问row.email而不是row[email]可以在字典基础上包一层class Row(dict): def __getattr__(self, key): try: return self[key] except KeyError: raise AttributeError(key) cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user LIMIT 1) raw cursor.fetchone() row Row(raw) print(row.email) # 属性访问这个Row类很轻适合在业务层做一层薄封装。但别过度设计大多数场景row[email]已经够用。验证通过之后把这段逻辑接进你的模型调用链路。比如让模型帮你生成 SQL、解释执行计划用 TaoToken 的模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先试跑确认 Key 和模型都正常再写进脚本。API Key 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理接入细节查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5. 常见报错排查401、local proxy failed 与游标失效配置过程中最容易撞上的几类报错逐个拆。第一类是模型侧的鉴权问题第二类是数据库游标本身的问题分开看。401 Unauthorized。这个通常出现在调用模型 API 时Key 没传、传错、或者带了多余空格。检查你的请求头import os import requests resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{ Authorization: fBearer {os.environ[TAOTOKEN_API_KEY].strip()}, Content-Type: application/json, }, json{ model: 你的模型ID, messages: [{role: user, content: 帮我解释这条SQL的执行计划}], }, timeout30, ) print(resp.status_code, resp.text)注意.strip()从网页复制 Key 时经常带上换行或空格这是 401 的高频原因。如果还是 401去控制台确认 Key 是否被禁用或过期。local proxy failed / connection refused。这类报错说明请求根本没发出去或者被本地网络配置拦了。先确认 Base URL 写的是https://taotoken.net/api不要多加/v1之外的路径也不要带 UTM 参数。然后用curl做最小验证curl -sS -o /dev/null -w %{http_code}\n \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ https://taotoken.net/api/v1/models返回 200 说明链路通。如果这里就失败检查本机 DNS、防火墙、以及是否有残留的代理环境变量HTTP_PROXY、HTTPS_PROXY。清掉它们再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxyreading choices 报错。这通常发生在解析模型响应时代码假设resp.json()[choices]一定存在但实际返回的是错误结构。稳妥的写法是先判断data resp.json() if choices not in data: print(unexpected response:, data) else: print(data[choices][0][message][content])这样报错信息会直接告诉你服务端返回了什么而不是一个干巴巴的 KeyError。OAuth / 认证相关报错。如果你用的是 Claude Code 这类命令行工具配置里需要同时写全三件套Base URL、API Key、Model ID。缺一个都会认证失败。以 Claude Code 的配置为例环境变量形式export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥 export ANTHROPIC_MODEL你的模型ID三个变量缺一不可。只配了 Base URL 没配 Key会报认证失败Key 配了但 Model ID 写错会报模型不存在。Cline 的 MCP 配置同理在settings.json里要把baseUrl、apiKey、model都填上。Codex 的auth.json也是这个逻辑{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model: 你的模型ID }游标相关的报错。数据库这边最常见的两个一是TypeError: tuple indices must be integers or slices, not str说明你还在用元组游标却按字符串取值回去加DictCursor二是KeyError: email说明字典游标生效了但SELECT里没查这个字段或者字段名拼错了。后者反而是好事——它把错误提前暴露了比元组下标取错值强得多。还有一个隐蔽的坑cursorclass传成了字符串DictCursor而不是类对象。PyMySQL 会直接报TypeError检查一下是不是漏了pymysql.cursors.前缀。提示排错时优先用最小复现脚本把连接、查询、取值三步单独跑一遍别在业务代码里大海捞针。模型侧的问题用curl验证数据库侧的问题用SELECT 1验证两条链路分开定位。6. 把字典游标固化进你的项目改到字典游标之后最该做的是把它固化下来而不是每次写查询都手动传参数。三个实用做法。第一封装一个get_cursor()函数项目里所有查询都走它def get_dict_cursor(conn): return conn.cursor(pymysql.cursors.DictCursor)第二如果用连接池把cursorclass写在池的创建参数里这样从池里拿到的游标默认就是字典类型业务代码零感知。第三写单元测试锁住行为。加一条断言确保返回类型是 dictdef test_query_returns_dict(): conn get_conn() cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT 1 AS one) row cursor.fetchone() assert isinstance(row, dict) assert row[one] 1 cursor.close() conn.close()这样以后有人不小心把游标配置改回元组测试会立刻失败而不是等到线上取错字段才发现。长期做编码和 Agent 类任务的话把模型调用和数据库查询串成工作流会省很多事。TaoToken 的 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合这种持续调用的场景API Key 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 统一管理接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各语言 SDK 的示例。Claude Code 的接入配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 里面把 Base URL、Key、Model ID 三件套讲得很清楚。最后留一个我踩过的坑字典游标的 key 顺序在 Python 3.7 是有序的和SELECT字段顺序一致但别依赖这个顺序做逻辑判断。要顺序就显式ORDER BY要字段就按名取。元组下标那种「靠位置约定」的写法正是这次改造要消灭的东西。 Python数据库查询返回元组太别扭？改到TaoToken后统一字典游标配置
1. 为什么你的查询结果总是元组字段取值全靠猜写 Python 连数据库很多人第一次跑通SELECT之后都会遇到同一个别扭fetchall()返回的是一堆元组想拿某个字段只能靠下标。比如row[3]到底是email还是created_at得翻回建表语句数一遍。表字段一改下标全乱线上报错还特别隐蔽——因为row[3]语法上永远合法只是取错了值。这个问题的根源在于 DB-API 规范。Python 的数据库驱动默认游标cursor返回的是「序列」而不是「映射」MySQL 的 PyMySQL、PostgreSQL 的 psycopg2 都是如此。序列的好处是轻量、内存占用小坏处是可读性差、维护成本高。对写业务代码的人来说row[email]比row[3]强太多字段名即文档重构时改列名能立刻暴露问题而不是悄悄取错。我试过在一个中等规模的项目里把几十处row[2]全部换成字典取值改完之后代码 review 的效率肉眼可见地提升——因为再也不用对着 schema 数下标了。这篇就聚焦一件事怎么把 Python 数据库查询的默认元组返回改成直接按列名访问的字典类型。覆盖 MySQLPyMySQL / mysqlclient和 PostgreSQLpsycopg2 / psycopg3两套主流组合给出可复制的游标配置、查询结果转字典的写法以及验证步骤。适合正在用 MySQL 或 PostgreSQL 做后端、被元组下标折磨过的开发者。核心检索词先摆出来Python 数据库查询默认返回元组通过设置字典游标DictCursor可以让查询结果直接按列名访问。下面从环境准备讲到排错每一步都能直接抄。2. 前置准备TaoToken 接入与依赖安装在动手改游标之前先把模型调用这条链路准备好。很多同学调 SQL 的时候顺手让模型帮忙生成查询、解释报错如果模型接入没配好来回切换会很烦。TaoToken 提供统一的 API 入口把模型对话、编码辅助这些能力收敛到一个 Base URL 下配置一次就能在脚本、编辑器插件、命令行工具里复用。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。注意 API 地址不带 UTM 参数直接用它作为 Base URL 即可。你需要先在控制台创建一个 API Key路径是 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建后复制那串sk-开头的密钥后面配置里会用到。模型对话的调试页面在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 可以先用它验证 Key 是否可用。如果你打算长期做编码和 Agent 类任务Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有套餐说明按需选择就行。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数问题优先查它。数据库这边的依赖MySQL 用 PyMySQL 最省事纯 Python 实现装起来没有编译负担pip install pymysql如果你用的是 mysqlclient基于 C 的 MySQLdb安装命令是pip install mysqlclientPostgreSQL 用 psycopg2 的话pip install psycopg2-binary新版 psycopg3 则是pip install psycopg[binary]连接池如果要用DBUtils 可以一起装上pip install dbutils环境变量建议单独放别把密码写死在代码里。建一个.env或者直接用系统环境变量export DB_HOST127.0.0.1 export DB_PORT3306 export DB_USERroot export DB_PASSyour_password export DB_NAMEuser export TAOTOKEN_API_KEYsk-你的密钥这样脚本里用os.environ读取换环境不用改代码。前置准备做完下面进入正题游标配置。3. 可复制配置DictCursor 与字典游标完整写法这一节是全文的核心直接给可复制的配置片段。先说 MySQL 的 PyMySQL关键参数就是cursorclasspymysql.cursors.DictCursor。注意它是在建立游标时指定不是在connect()时指定虽然connect()也支持cursorclass默认值但显式写在cursor()上更清晰。import os import pymysql conn pymysql.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, ) # 关键建立游标时传入 DictCursor cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user WHERE id %s, (1,)) row cursor.fetchone() print(row) # {id: 1, name: alice, email: aexample.com} print(row[email]) # 直接按列名取值 cursor.close() conn.close()fetchall()返回的就是一个列表每个元素是字典cursor.execute(SELECT id, name FROM user LIMIT 3) rows cursor.fetchall() for r in rows: print(r[id], r[name])如果你用 mysqlclientMySQLdb写法几乎一样只是模块名不同import MySQLdb import MySQLdb.cursors conn MySQLdb.connect( hostos.environ[DB_HOST], useros.environ[DB_USER], passwdos.environ[DB_PASS], dbos.environ[DB_NAME], charsetutf8mb4, ) cursor conn.cursor(MySQLdb.cursors.DictCursor) cursor.execute(SELECT id, name FROM user) print(cursor.fetchall())PostgreSQL 的 psycopg2 用的是cursor_factory不是cursorclass这点容易搞混import os import psycopg2 import psycopg2.extras conn psycopg2.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 5432)), useros.environ[DB_USER], passwordos.environ[DB_PASS], dbnameos.environ[DB_NAME], ) cursor conn.cursor(cursor_factorypsycopg2.extras.RealDictCursor) cursor.execute(SELECT id, name, email FROM users WHERE id %s, (1,)) print(cursor.fetchone()) # {id: 1, name: alice, email: aexample.com}psycopg3 的写法又变了用row_factoryimport psycopg from psycopg.rows import dict_row with psycopg.connect( hostos.environ[DB_HOST], useros.environ[DB_USER], passwordos.environ[DB_PASS], dbnameos.environ[DB_NAME], ) as conn: with conn.cursor(row_factorydict_row) as cur: cur.execute(SELECT id, name FROM users) print(cur.fetchall())连接池场景下DBUtils 的PooledDB也能指定游标类。下面这段是 MySQL 连接池 字典游标的完整配置import pymysql from dbutils.pooled_db import PooledDB POOL PooledDB( creatorpymysql, maxconnections5, hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, cursorclasspymysql.cursors.DictCursor, # 池级别默认字典游标 ) conn POOL.connection() cursor conn.cursor() cursor.execute(SELECT id, name FROM user) print(cursor.fetchall()) cursor.close() conn.close()注意PooledDB里cursorclass是传给creator的默认参数这样每次从池里拿到的游标都是字典游标不用每次手动指定。如果你只想某次查询用字典、其他查询用元组就在conn.cursor()时单独传覆盖池的默认值。各驱动的参数对照表驱动参数名取值返回类型PyMySQLcursorclasspymysql.cursors.DictCursordictmysqlclientcursorMySQLdb.cursors.DictCursordictpsycopg2cursor_factorypsycopg2.extras.RealDictCursordictRealDictpsycopg3row_factorypsycopg.rows.dict_rowdict注意psycopg2 的RealDictCursor返回的是RealDictRow它是 dict 的子类用法和普通字典一致但json.dumps时可能需要先dict(row)转换。psycopg3 的dict_row返回的是标准 dict。配置给完了下一节验证请求确认真的按列名取到了值。4. 验证请求查询结果转字典与字段名取值实测配置写完必须验证不然你不知道游标到底生效没有。先写一个最小可跑的脚本把连接、查询、取值、打印串起来。下面这段用 PyMySQL你可以直接复制运行把环境变量换成自己的。import os import pymysql def get_conn(): return pymysql.connect( hostos.environ[DB_HOST], portint(os.environ.get(DB_PORT, 3306)), useros.environ[DB_USER], passwordos.environ[DB_PASS], databaseos.environ[DB_NAME], charsetutf8mb4, ) def main(): conn get_conn() cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user LIMIT 3) rows cursor.fetchall() # 验证 1类型检查 print(rows type:, type(rows)) print(row type:, type(rows[0]) if rows else empty) # 验证 2按列名取值 for r in rows: print(fid{r[id]}, name{r[name]}, email{r[email]}) # 验证 3转成标准 dict 再序列化 import json print(json.dumps([dict(r) for r in rows], ensure_asciiFalse)) cursor.close() conn.close() if __name__ __main__: main()预期输出类似rows type: class list row type: class dict id1, namealice, emailaexample.com id2, namebob, emailbexample.com id3, namecarol, emailcexample.com [{id: 1, name: alice, email: aexample.com}, ...]看到row type: class dict就说明字典游标生效了。如果打印出来是class tuple说明游标参数没传对回到上一节检查。再验证一个容易忽略的点字段名大小写。MySQL 在 Linux 下默认表名区分大小写但列名返回的 key 通常和SELECT里写的一致。如果你写SELECT ID, NAME字典的 key 就是ID、NAME。PostgreSQL 更严格不加引号的标识符会被折叠成小写所以SELECT ID返回的 key 是id。这点在跨库迁移时特别容易踩。# PostgreSQL 验证注意 key 是小写 cursor.execute(SELECT ID, NAME FROM users) row cursor.fetchone() print(row.keys()) # dict_keys([id, name])如果你想让查询结果直接变成对象属性访问row.email而不是row[email]可以在字典基础上包一层class Row(dict): def __getattr__(self, key): try: return self[key] except KeyError: raise AttributeError(key) cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT id, name, email FROM user LIMIT 1) raw cursor.fetchone() row Row(raw) print(row.email) # 属性访问这个Row类很轻适合在业务层做一层薄封装。但别过度设计大多数场景row[email]已经够用。验证通过之后把这段逻辑接进你的模型调用链路。比如让模型帮你生成 SQL、解释执行计划用 TaoToken 的模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先试跑确认 Key 和模型都正常再写进脚本。API Key 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理接入细节查 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。5. 常见报错排查401、local proxy failed 与游标失效配置过程中最容易撞上的几类报错逐个拆。第一类是模型侧的鉴权问题第二类是数据库游标本身的问题分开看。401 Unauthorized。这个通常出现在调用模型 API 时Key 没传、传错、或者带了多余空格。检查你的请求头import os import requests resp requests.post( https://taotoken.net/api/v1/chat/completions, headers{ Authorization: fBearer {os.environ[TAOTOKEN_API_KEY].strip()}, Content-Type: application/json, }, json{ model: 你的模型ID, messages: [{role: user, content: 帮我解释这条SQL的执行计划}], }, timeout30, ) print(resp.status_code, resp.text)注意.strip()从网页复制 Key 时经常带上换行或空格这是 401 的高频原因。如果还是 401去控制台确认 Key 是否被禁用或过期。local proxy failed / connection refused。这类报错说明请求根本没发出去或者被本地网络配置拦了。先确认 Base URL 写的是https://taotoken.net/api不要多加/v1之外的路径也不要带 UTM 参数。然后用curl做最小验证curl -sS -o /dev/null -w %{http_code}\n \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ https://taotoken.net/api/v1/models返回 200 说明链路通。如果这里就失败检查本机 DNS、防火墙、以及是否有残留的代理环境变量HTTP_PROXY、HTTPS_PROXY。清掉它们再试unset HTTP_PROXY HTTPS_PROXY http_proxy https_proxyreading choices 报错。这通常发生在解析模型响应时代码假设resp.json()[choices]一定存在但实际返回的是错误结构。稳妥的写法是先判断data resp.json() if choices not in data: print(unexpected response:, data) else: print(data[choices][0][message][content])这样报错信息会直接告诉你服务端返回了什么而不是一个干巴巴的 KeyError。OAuth / 认证相关报错。如果你用的是 Claude Code 这类命令行工具配置里需要同时写全三件套Base URL、API Key、Model ID。缺一个都会认证失败。以 Claude Code 的配置为例环境变量形式export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥 export ANTHROPIC_MODEL你的模型ID三个变量缺一不可。只配了 Base URL 没配 Key会报认证失败Key 配了但 Model ID 写错会报模型不存在。Cline 的 MCP 配置同理在settings.json里要把baseUrl、apiKey、model都填上。Codex 的auth.json也是这个逻辑{ base_url: https://taotoken.net/api, api_key: sk-你的密钥, model: 你的模型ID }游标相关的报错。数据库这边最常见的两个一是TypeError: tuple indices must be integers or slices, not str说明你还在用元组游标却按字符串取值回去加DictCursor二是KeyError: email说明字典游标生效了但SELECT里没查这个字段或者字段名拼错了。后者反而是好事——它把错误提前暴露了比元组下标取错值强得多。还有一个隐蔽的坑cursorclass传成了字符串DictCursor而不是类对象。PyMySQL 会直接报TypeError检查一下是不是漏了pymysql.cursors.前缀。提示排错时优先用最小复现脚本把连接、查询、取值三步单独跑一遍别在业务代码里大海捞针。模型侧的问题用curl验证数据库侧的问题用SELECT 1验证两条链路分开定位。6. 把字典游标固化进你的项目改到字典游标之后最该做的是把它固化下来而不是每次写查询都手动传参数。三个实用做法。第一封装一个get_cursor()函数项目里所有查询都走它def get_dict_cursor(conn): return conn.cursor(pymysql.cursors.DictCursor)第二如果用连接池把cursorclass写在池的创建参数里这样从池里拿到的游标默认就是字典类型业务代码零感知。第三写单元测试锁住行为。加一条断言确保返回类型是 dictdef test_query_returns_dict(): conn get_conn() cursor conn.cursor(pymysql.cursors.DictCursor) cursor.execute(SELECT 1 AS one) row cursor.fetchone() assert isinstance(row, dict) assert row[one] 1 cursor.close() conn.close()这样以后有人不小心把游标配置改回元组测试会立刻失败而不是等到线上取错字段才发现。长期做编码和 Agent 类任务的话把模型调用和数据库查询串成工作流会省很多事。TaoToken 的 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 适合这种持续调用的场景API Key 在 https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 统一管理接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有各语言 SDK 的示例。Claude Code 的接入配置参考 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite 里面把 Base URL、Key、Model ID 三件套讲得很清楚。最后留一个我踩过的坑字典游标的 key 顺序在 Python 3.7 是有序的和SELECT字段顺序一致但别依赖这个顺序做逻辑判断。要顺序就显式ORDER BY要字段就按名取。元组下标那种「靠位置约定」的写法正是这次改造要消灭的东西。