1. 为什么你的 pyMySQL 项目需要一个 settings.json 骨架如果你正在写 Python 项目尤其是那种要连 MySQL 做增删改查的脚本或小服务大概率写过类似这样的代码import pymysql conn pymysql.connect( host127.0.0.1, userroot, password123456, dbtest, charsetutf8mb4 )能跑但问题也很明显数据库地址、账号、密码全硬编码在业务代码里。换一台机器要改代码多人协作时密码还会跟着 Git 一起提交上去。更麻烦的是当你项目里同时有本地调试、测试库、线上库三套环境时connect()的参数会越写越乱。这篇要解决的就是这件事把 pyMySQL 的连接参数抽到一个settings.json里让代码只负责读配置、建连接、跑 SQL。同时把「统一 Key / API 通道」这一层也纳入配置管理——也就是通过 TaoToken 拿到统一的访问凭证再让 pyMySQL 走这套配置去连库。这样你的项目结构会变成配置归配置代码归代码凭证归凭证。适合谁看写过一点 Python、用过 pyMySQL 的connect / cursor / execute / commit四步流程但还没把配置抽干净的开发者。读完你能拿到一份可直接复制的settings.json骨架、一份读取配置并建连的代码以及一次能确认「配置真的生效」的连通性验证动作。先说清楚边界pyMySQL 本身是 Python 的 MySQL 客户端库它负责的是「Python 进程 ↔ MySQL 服务」这条链路。TaoToken 在这里扮演的是统一凭证与 API 通道的角色帮你把 Key 管理、调用入口收敛到一处而不是让你在每个项目里散落一堆明文密码。两者配合才是这篇要讲的完整配置姿势。2. TaoToken 前置先把统一 Key 和通道准备好在写settings.json之前得先有东西可填。这一步不做后面配置里全是占位符验证必然失败。TaoToken 的核心作用是提供统一的 API 入口和 Key 管理。你可以把它理解成一个「凭证中转站」项目里不再直接写数据库明文密码而是通过统一 Key 去访问受控的通道。官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content进去之后按下面的顺序操作别跳步第一步注册并登录进入控制台。控制台地址是https://taotoken.net/console登录后你能看到自己的项目空间和 Key 管理区域。第二步创建 API Key。路径在https://taotoken.net/api-keys点新建系统会生成一串 Key。这串 Key 只显示一次复制下来先存到安全的地方别直接贴进聊天窗口或提交到公开仓库。第三步如果你后面要用模型对话能力做辅助调试比如让模型帮你生成 SQL 或解释报错可以顺手看下模型对话入口https://taotoken.net/model-chat。如果是要长期做编码、跑 Agent 类任务那更适合看 Coding Planhttps://taotoken.net/coding-plan。第四步接入细节和字段说明统一看文档https://taotoken.net/doc。API 的基础地址是https://taotoken.net/api注意这个地址不带任何查询参数配置里填的时候别自己加尾巴。这里有个我踩过的坑很多人拿到 Key 之后直接把 Key 当成数据库密码填进pymysql.connect(password...)这是错的。Key 是访问通道的凭证数据库密码是数据库自己的密码两者不是一回事。settings.json里要分字段存放后面我会给出骨架。注意Key 属于敏感信息。settings.json如果进了 Git请务必把真实 Key 换成环境变量引用或者把该文件加进.gitignore。下面骨架里我会用占位符演示你替换成自己的值即可。3. 可复制的 settings.json 骨架与字段说明现在进入正题。在项目根目录新建一个settings.json内容如下。这份骨架把「数据库连接参数」和「TaoToken 通道参数」分成两块职责清晰后面读配置的代码也好写。{ database: { host: 127.0.0.1, port: 3306, user: your_db_user, password: your_db_password, db: your_database, charset: utf8mb4, connect_timeout: 10, autocommit: false }, taotoken: { api_base: https://taotoken.net/api, api_key: sk-your-taotoken-key, timeout: 30 }, runtime: { env: dev, log_sql: true } }逐字段说明别嫌啰嗦配置错一个字符就连不上database.host是 MySQL 服务地址本地就是127.0.0.1容器里可能是服务名。database.port默认 3306改过端口的按实际填。database.user和database.password是数据库自己的账号密码不是 TaoToken 的 Key。database.db是目标库名。database.charset建议utf8mb4能存 emoji 和生僻字utf8在老项目里常见但不够用。database.connect_timeout是连接超时秒数网络不稳时给 10 秒比较稳。database.autocommit设成false意味着你要手动commit()这也是 pyMySQL 的默认行为写清楚是为了避免有人误以为自动提交。taotoken.api_base固定填https://taotoken.net/api不要加 UTM 参数。taotoken.api_key填你在api-keys页面拿到的那串 Key。taotoken.timeout是调用通道的超时30 秒够用。runtime.env标记当前环境runtime.log_sql控制是否打印 SQL调试时开、上线时关。提示如果你不想把 Key 写死在文件里可以把api_key的值改成${TAOTOKEN_API_KEY}然后在读取配置的代码里做一次环境变量替换。这样文件可以安全提交。4. 读取配置并建立 pyMySQL 连接有了骨架接下来写读取逻辑。核心思路先读 JSON再把database块解包成pymysql.connect()的关键字参数。注意db这个键名pyMySQL 接受db也接受database我这里保持和 JSON 一致。import json import os import pymysql def load_settings(pathsettings.json): with open(path, r, encodingutf-8) as f: settings json.load(f) # 支持环境变量替换避免明文 Key 进仓库 api_key settings[taotoken][api_key] if api_key.startswith(${) and api_key.endswith(}): env_name api_key[2:-1] settings[taotoken][api_key] os.environ.get(env_name, ) return settings def get_connection(settings): db_cfg settings[database] conn pymysql.connect( hostdb_cfg[host], portdb_cfg[port], userdb_cfg[user], passworddb_cfg[password], dbdb_cfg[db], charsetdb_cfg[charset], connect_timeoutdb_cfg[connect_timeout], autocommitdb_cfg[autocommit], ) return conn这段代码里有两个细节值得说。第一load_settings里做了环境变量替换如果你的api_key写的是${TAOTOKEN_API_KEY}它会去读环境变量读不到就返回空串方便你排查。第二get_connection把autocommit显式传进去和 JSON 里的值保持一致避免默认行为带来的困惑。接下来是标准的四步操作流程和 pyMySQL 官方用法一致建连接、取游标、执行 SQL、提交并关闭。def run_query(settings): conn None cursor None try: conn get_connection(settings) cursor conn.cursor() sql SELECT VERSION() AS version if settings[runtime][log_sql]: print(f[SQL] {sql}) cursor.execute(sql) result cursor.fetchone() conn.commit() return result except Exception as err: if conn: conn.rollback() print(f[ERROR] {err}) raise finally: if cursor: cursor.close() if conn: conn.close()注意finally里的关闭顺序先关游标再关连接。反过来虽然多数情况也能跑但规范写法是游标先释放。except里做了rollback()这是 pyMySQL 默认开启事务下的必要动作失败不回滚会留下未提交的脏状态。5. 一次连通性验证确认配置真的生效配置写完最怕的是「看起来对其实没连上」。所以必须做一次明确的连通性验证。我推荐用SELECT VERSION()这条 SQL它不依赖任何业务表任何 MySQL 都能跑返回结果还能证明链路是通的。把上面的函数串起来写一个verify.pyfrom config_loader import load_settings, run_query if __name__ __main__: settings load_settings(settings.json) print(f[ENV] {settings[runtime][env]}) print(f[API_BASE] {settings[taotoken][api_base]}) row run_query(settings) print(f[OK] MySQL version {row[version]})运行python verify.py成功时你会看到类似输出[ENV] dev [API_BASE] https://taotoken.net/api [SQL] SELECT VERSION() AS version [OK] MySQL version 8.0.36看到[OK]和版本号说明三件事同时成立settings.json被正确读取、pyMySQL 成功建连、SQL 执行并拿到了结果。如果[API_BASE]打印出来是空的或者带了一堆参数说明你的taotoken块填错了回去检查api_base是否严格等于https://taotoken.net/api。再补一个更贴近业务的验证建一张临时表、插一条、查出来、删掉。这样能顺带验证事务提交是否正常。def verify_crud(settings): conn get_connection(settings) cursor conn.cursor() try: cursor.execute(CREATE TABLE IF NOT EXISTS _conn_check (id INT PRIMARY KEY, note VARCHAR(32))) cursor.execute(REPLACE INTO _conn_check (id, note) VALUES (1, ok)) conn.commit() cursor.execute(SELECT note FROM _conn_check WHERE id 1) row cursor.fetchone() print(f[CRUD] note {row[note]}) cursor.execute(DROP TABLE _conn_check) conn.commit() except Exception as err: conn.rollback() print(f[CRUD-ERROR] {err}) finally: cursor.close() conn.close()跑通这段说明你的配置不仅能连还能正常写和读。到这一步settings.json骨架就算真正落地了。6. 本篇常见错排查配置类问题报错信息往往不直观。下面这几个是我实际遇到频率最高的按现象对号入座。报错Access denied for user数据库账号或密码错了。注意区分这是 MySQL 的账号密码不是 TaoToken 的 Key。检查database.user和database.password确认该账号有目标库的权限。报错Cant connect to MySQL server on 127.0.0.1地址或端口不对或者 MySQL 没启动。先确认服务在跑再确认host和port。容器场景下127.0.0.1指的是容器自己要用服务名或宿主地址。报错Unknown databasedatabase.db填的库不存在。先去 MySQL 里SHOW DATABASES;看一眼库名大小写敏感的场景也要注意。中文乱码或 emoji 存不进去charset没设成utf8mb4或者表本身的字符集不是utf8mb4。连接层和表层要一致。api_base相关异常最常见的是把带 UTM 的官网地址填进了api_base。记住 API 地址是https://taotoken.net/api不带任何查询参数。Key 无效或过期时去https://taotoken.net/api-keys重新生成。事务没生效、数据查不到autocommit为false时忘了commit()。pyMySQL 默认不开自动提交写完必须提交否则连接关闭时改动会丢。Key 泄露风险settings.json提交到了公开仓库。立刻去控制台吊销旧 Key、生成新的并把文件加入.gitignore改用环境变量引用。注意排查时优先看完整报错栈别只看最后一行。pyMySQL 的异常信息里通常包含 errno比如 1045 是权限、2003 是连不上对照 errno 查更快。如果你在接入过程中卡在 Key 配置或通道地址上直接看接入文档https://taotoken.net/doc最省时间需要重新生成凭证就去https://taotoken.net/api-keys想先用模型对话把 SQL 或报错解释清楚可以走https://taotoken.net/model-chat长期做编码和 Agent 任务的话https://taotoken.net/coding-plan更合适。把配置抽干净这件事做一次后面每个项目都能复用。