1. 为什么查 Oracle 只拿到数据行字段名却丢了用 Python 连 Oracle 做数据同步或报表脚本时最常见的尴尬是fetchall()把数据取回来了但字段名没跟着走。结果组装 JSON 时只能靠column1、column2硬编码一旦 SQL 里改了别名或调整了列顺序整个下游解析全崩。这个问题的本质是游标对象本身不返回「带列名的结果集」它只给你一个元组列表。字段名藏在cursor.description里需要你主动提取并和数据行做映射。很多人第一次写cx_Oracle或oracledb时看到result是一堆元组就以为完事了其实真正的列信息一直在旁边等着被读。这篇面向的场景很具体你写的是数据同步脚本、报表导出工具或者给前端/下游服务组装 JSON 的中间层。目标只有一个——让字段名稳定、可读、可映射而不是每次靠猜。我会用oracledbcx_Oracle的继任者API 基本兼容走一遍完整流程同时把 TaoToken 统一 Key 的配置骨架嵌进来方便你在需要调用模型做字段语义映射或 SQL 生成时直接复用。适合谁看已经能连上 Oracle、能跑select但卡在「怎么把列名拿出来」这一步的 Python 开发者。不需要你懂 Oracle 内部字典表只要会写 SQL 和 Python 函数就行。2. TaoToken 前置统一 Key 与 settings.json 配置骨架在动手写字段映射之前先把「Key 从哪来、怎么管」这件事定下来。我试过把数据库密码、模型 Key、各种 token 散落在不同脚本里后期维护非常痛苦。TaoToken 的思路是提供一个统一入口你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 了解整体能力API 端点统一走 https://taotoken.net/api。它的定位不是替代你的数据库驱动而是当你的脚本需要「用模型理解字段含义」「自动生成列别名映射」「把 SQL 结果转成自然语言描述」时提供一个稳定的 Key 和调用入口。比如你查出来的字段是CJBZGX_CPT、SY2_这种缩写想让模型帮你翻译成可读的 JSON key这时候统一 Key 就派上用场了。配置上我建议单独放一个settings.json不要写死在代码里。下面是一个可复制的骨架字段名按你项目习惯调整{ taotoken: { api_base: https://taotoken.net/api, api_key: sk-你的统一Key, default_model: claude-sonnet, timeout_seconds: 30 }, oracle: { user: BI, password: 你的密码, dsn: 10.110.11.11:1521/orcl, encoding: UTF-8 }, field_mapping: { enabled: true, cache_ttl: 3600 } }如果你更习惯 TOML等价写法如下放在config.toml里[taotoken] api_base https://taotoken.net/api api_key sk-你的统一Key default_model claude-sonnet timeout_seconds 30 [oracle] user BI password 你的密码 dsn 10.110.11.11:1521/orcl encoding UTF-8 [field_mapping] enabled true cache_ttl 3600注意api_key不要提交到 Git。用环境变量覆盖或者把settings.json加进.gitignore。TaoToken 的 Key 可以在控制台里创建和管理具体入口在 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite。读取配置的代码很短用标准库就够import json from pathlib import Path def load_settings(pathsettings.json): with Path(path).open(r, encodingutf-8) as f: return json.load(f) settings load_settings() api_key settings[taotoken][api_key] api_base settings[taotoken][api_base]到这里前置就完成了Key 有了统一出处Oracle 连接参数也集中管理。接下来进入正题——怎么把字段名从cursor.description里稳定地拿出来。3. 可复制配置cursor.description 提取字段名与别名映射cursor.description是一个元组序列每个元素描述一列。它的结构是(name, type_code, display_size, internal_size, precision, scale, null_ok)我们只关心第一个元素name它就是字段名或 SQL 里的别名。下面这段代码把「执行 SQL → 提取字段名 → 组装字典列表」串起来可以直接复制import oracledb def query_with_columns(conn, sql, paramsNone): cursor conn.cursor() cursor.execute(sql, params or {}) columns [col[0] for col in cursor.description] rows cursor.fetchall() result [dict(zip(columns, row)) for row in rows] cursor.close() return columns, result调用示例注意 SQL 里用了别名验证别名是否被正确捕获conn oracledb.connect( usersettings[oracle][user], passwordsettings[oracle][password], dsnsettings[oracle][dsn], ) sql select CJBH as record_id, CPMC as product_name, CJSJ as created_at from SY2_CJBZGX_CPT where rownum :limit columns, rows query_with_columns(conn, sql, {limit: 5}) print(字段名:, columns) print(第一行:, rows[0] if rows else None)实测下来columns会输出[RECORD_ID, PRODUCT_NAME, CREATED_AT]。注意 Oracle 默认把未加引号的别名转成大写如果你想要小写 JSON key有两个选择SQL 里用双引号包住别名as record_id或者在 Python 侧统一lower()。我一般推荐在 Python 侧做归一化因为 SQL 里加双引号会让 Oracle 区分大小写后续维护容易踩坑def normalize_columns(columns, lowerTrue): if lower: return [c.lower() for c in columns] return columns如果你需要把中文缩写字段映射成可读英文可以借助 TaoToken 的模型对话能力做一次语义转换。调用入口在 https://taotoken.net/api模型对话页在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite。下面是一个最小调用示例把字段名列表丢给模型让它返回映射建议import requests def suggest_mapping(columns, api_key, api_base): prompt ( 把以下 Oracle 字段名翻译成可读的英文 JSON key 只返回 JSON 对象不要解释\n , .join(columns) ) resp requests.post( f{api_base}/v1/chat/completions, headers{Authorization: fBearer {api_key}}, json{ model: claude-sonnet, messages: [{role: user, content: prompt}], }, timeout30, ) resp.raise_for_status() return resp.json()拿到映射后把它缓存到本地避免每次查询都调模型。field_mapping.cache_ttl就是干这个的。4. 验证请求确认字段名稳定可读的成功结果配置写完了必须验证两件事字段名是否和数据行一一对应别名是否按预期生效。下面是一段完整的验证脚本跑完你能直接看到结果import json import oracledb settings load_settings() conn oracledb.connect( usersettings[oracle][user], passwordsettings[oracle][password], dsnsettings[oracle][dsn], ) sql select CJBH as record_id, CPMC as product_name, CJSJ as created_at from SY2_CJBZGX_CPT where rownum 3 cursor conn.cursor() cursor.execute(sql) columns [col[0] for col in cursor.description] rows cursor.fetchall() print(列数:, len(columns)) print(字段名:, columns) for row in rows: record dict(zip(columns, row)) print(json.dumps(record, ensure_asciiFalse, defaultstr)) cursor.close() conn.close()预期输出类似列数: 3 字段名: [record_id, product_name, created_at] {record_id: A001, product_name: 测试产品, created_at: 2024-01-01 10:00:00}关键验证点有三个。第一len(columns)必须等于每行元组的长度否则说明description和数据错位。第二字段名里不能出现None如果出现通常是 SQL 里用了表达式但没给别名比如select count(*) from ...这时候 Oracle 会返回一个自动生成的列名建议显式加别名。第三json.dumps时用defaultstr兜住datetime类型否则会报TypeError。如果你在脚本里需要长期跑同步任务建议加一个断言把字段名校验前置expected {record_id, product_name, created_at} actual set(columns) assert expected actual, f字段名不匹配: {actual}这样一旦上游改了表结构或 SQL 别名脚本会立刻报错而不是悄悄产出错误的 JSON。5. 本篇常见错排查字段名大小写、None 与编码问题排障部分我按出现频率排序基本都是我自己踩过的坑。字段名全是大写怎么办。Oracle 默认把未加引号的标识符转大写所以select CJBH from ...拿到的description[0][0]是CJBH。如果你要小写 key在 Python 侧统一处理不要依赖 SQL 双引号。双引号会让字段名变成大小写敏感后续where条件也得跟着加引号维护成本高。description 里出现 None。常见于聚合函数或表达式没加别名比如select max(CJSJ) from ...。解决办法是显式加别名select max(CJSJ) as latest_time from ...。加完之后description里就是LATEST_TIME不会再是None。中文编码乱码。连接时指定encodingUTF-8同时确认 Oracle 服务端的字符集。如果返回的中文是问号或乱码先检查NLS_LANG环境变量再检查 Python 侧json.dumps是否用了ensure_asciiFalse。后者不加的话中文会被转成\uXXXX虽然不算乱码但可读性差。fetchall 内存爆掉。如果表很大不要一次性fetchall()。用fetchmany(size)分批取字段名只需要从description取一次cursor.execute(sql) columns [col[0] for col in cursor.description] while True: batch cursor.fetchmany(1000) if not batch: break for row in batch: yield dict(zip(columns, row))cx_Oracle 和 oracledb 混用报错。两个库的导入名不同cx_Oracle是旧版oracledb是官方推荐的新版。如果你两个都装了注意import时不要混。新项目直接用oracledbAPI 兼容且支持 thin 模式不需要装 Oracle 客户端。TaoToken 调用返回 401。检查api_key是否从控制台正确复制以及请求头是否是Authorization: Bearer sk-xxx。如果 Key 没问题检查api_base是否写成了https://taotoken.net/api不要多加斜杠或路径。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite里面有完整的请求示例。6. 语义一致 CTA按你的场景选入口字段名提取和映射验证跑通之后下一步取决于你的实际用途。如果你是在做数据同步脚本需要长期稳定地调用模型做字段语义转换建议把 Key 管理起来用 Coding Plan 统一规划调用配额和模型选择入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite。它适合需要长期编码、Agent 调用的场景不用每次手动换 Key。如果你只是想快速验证某个字段名该映射成什么或者测试模型对 Oracle 字段的理解能力直接用模型对话页最方便https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite。把字段列表贴进去让它返回 JSON 映射几秒钟就能看到结果。如果你在接入过程中遇到 401、超时、字段名对不上这类问题先去 API Keys 页面确认 Key 状态和权限https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite再对照接入文档检查请求格式。大部分排障问题都能在这两个页面找到答案。最后补一个实用技巧把cursor.description的提取封装成装饰器或工具函数所有查询统一走它。这样字段名永远不会丢JSON 组装也不会因为列顺序变化而错位。字段名稳定了下游解析就稳了。