当数据库密码包含 @、/、: 或 % 等 url 保留字符时，直接拼接连接字符串会导致 sqlalchemy 解析失败，引发 getaddrinfo failed 等连接异常；正确做法是使用 urllib.parse.quote_plus() 对敏感凭证进行 url 编码。
在使用 SQLAlchemy 连接 MySQL 数据库时，连接字符串遵循 URL 格式：
mysql+pymysql://
其中 @ 是分隔用户名与主机地址的关键符号。若密码中本身含有 @（例如 'Gspann@123'），SQLAlchemy 会错误地将该符号识别为 URL 结构分界符，导致解析出错——主机名被截断为 Gspann，端口或路径混乱，最终触发 OperationalError: Can't connect to MySQL server on 'Gspann' 或 getaddrinfo failed（错误码 Errno 11003）。
需要创建、读取、编辑或处理 Word 文档（.docx / .dotx）时使用。触发词：'Word'、'word 文档'、'.docx'、'生成报告'、'制作合同/简历/方案/说明书'、'提取 word 内容'、'在文档里查找替换'、'给文档加页眉页脚/目录/表格'。也用于把任意内容排版成一份正式的 Word 文件。不要用它处理 PDF、Excel 或无关编程任务。中文创作场景尤其适合：小说大纲稿、投稿文档、合同、简历、工作总结。
✅ 正确解决方案：对用户名和密码进行 URL 编码
Python 标准库 urllib.parse 提供了安全编码工具，推荐使用 quote_plus()（兼容空格转 +，适合表单风格）或更严格的 quote()（空格转 %20）。对于数据库凭证，二者均可，但 quote_plus 更常用：
from urllib.parse import quote_plus
from sqlalchemy import create_engine
import pandas as pd
# 安全编码密码（关键步骤！）
password = "Gspann@123"
encoded_password = quote_plus(password)
# 构建标准化连接字符串
db_connection_str = f"mysql+pymysql://beat_dq_readonly:{encoded_password}@35.187.158.251/beat_results_dev"
# 创建引擎（建议添加 pool_pre_ping=True 提高健壮性）
db_connection = create_engine(
db_connection_str,
pool_pre_ping=True, # 自动验证连接有效性，避免 stale connection
echo=False # 生产环境建议设为 False，避免打印 SQL 日志
)
# 执行查询
df = pd.read_sql("SELECT * FROM vw_dv_count_rpt", con=db_connection)
print(df.head())⚠️ 注意事项：
- 不止 @ 需要编码：若密码含 /（如 pass/123）、:（如 abc:def）或 %（如 p%20ss），同样必须编码，否则 URL 解析必然失败；
- 避免硬编码敏感信息：生产环境中应使用环境变量（如 os.getenv("DB_PASSWORD")）或密钥管理服务，而非明文写入脚本；
- 检查网络与权限：URL 编码解决的是解析问题，若仍报错，请确认：① 目标 MySQL 服务器已开放 3306 端口且允许该 IP 访问；② 用户 beat_dq_readonly 在 beat_results_dev 库中具有 SELECT 权限；③ 防火墙或云平台安全组未拦截连接。
总结：URL 编码不是“可选项”，而是构建可靠数据库连接的必要实践。只要凭证含特殊字符，就必须通过 quote_plus() 处理——这是 SQLAlchemy 官方文档明确推荐的标准流程，也是避免低级但致命连接故障的核心防线。
