怎么在Python三引号中编写SQL或HTML长文本

阿澈

发布时间：2026-10-20 | 4人浏览过

原创

在 Python 中编写大段的 SQL 查询或 HTML 模板时，三引号字符串（''' 或 """）是最常用的原生工具。要写出既容易阅读、排版规整，又不会在运行时引入额外空行与多余空格缩进的代码，核心在于掌握首行换行控制、配合 textwrap.dedent() 清洗多余缩进，并区分处理 SQL 的参数绑定与 HTML 的字符转义要求。本文将具体讲解操作要点、常见缺陷与排查处理方法。

一、三引号的缩进陷阱与处理机制

Python 的三引号会原汁原味地记录字符串内的每一个换行符与空格。当我们在一个函数或类方法内部编写长文本时，往往会自然地给 SQL 或 HTML 加上代码缩进，以便与外层 Python 代码保持整齐结构。然而，这就导致缩进空格也被硬编码进了字符串内部，不仅增大了内存占用，在打印日志或解析文本时也容易造成干扰。

此外，三引号开头的换行也会产生一个首行空换行符 \n。例如下面的写法：

def get_user_query():
    # 错误示范：会导致字符串开头有 \n，且每行带有 8 个空格缩进
    sql = """
        SELECT id, username, email
        FROM users
        WHERE status = 'active'
    """
    return sql

为了既保持源码在编辑器中优雅对齐，又获得纯净没有多余缩进的长文本，标准做法是使用内置模块 textwrap.dedent()，配合首尾去空的 strip() 方法。

图1：Python 三引号字符串缩进陷阱与 textwrap.dedent 处理机制对比

二、标准操作流程：编写长文本的四个关键步骤

在实际开发中，无论是构建一段多行 SQL 查询，还是拼装一段用于邮件、报告的 HTML 片段，遵循统一的处理流程能够最大限度避免格式混乱和安全隐患。完整操作流程包含以下四个步骤：

选用合适引号并控制首行换行：推荐使用三个双引号 """，这样内部直接书写 HTML 属性（如 class="item"）或 SQL 单引号字面量（如 'active'）时无需反复反斜杠转义。在三引号之后立即放置反斜杠 \ 可以直接吞掉首个换行符。
保留自然的排版层级：按照 SQL 关键字分行或 HTML DOM 标签层级缩进书写，便于同行审阅。
消除公共缩进：通过 inspect.cleandoc() 或 textwrap.dedent().strip() 将有效内容左对齐。
严格处理参数与特殊字符：SQL 文本只留占位符（如 %s 或 ?），不进行字符串拼接；HTML 中涉及 CSS/JS 样式或字面量大括号时做双重转义。

图2：Python 三引号编写长文本的标准四步处理流程

三、编写 SQL 长文本的具体实践与注入防护

在 Python 中编写复杂 SQL 时，三引号能显著提升子查询、多表 JOIN 和 CASE WHEN 语句的阅读体验。但最常见也是危害最大的误区，就是在三引号前面直接加上 f 标识符，用 f"""... WHERE name = '{user_input}' """ 拼接字符串。

这种拼接不仅会导致严重的 SQL 注入安全漏洞，还会导致数据库引擎无法有效重用执行计划。正确的做法是将 SQL 语句本身作为静态的三引号长文本，在动态参数处保留占位符，执行时交由数据库驱动进行底层转义与类型校验。

import textwrap
import sqlite3

def find_active_orders(conn, min_amount, user_status):
    # 使用三引号组织清晰的多行 SQL
    # 首行使用反斜杠避免开头的多余换行，内部保持参数占位符（SQLite使用 ?，MySQL常用 %s）
    query = textwrap.dedent("""\
        SELECT 
            o.id AS order_id,
            o.amount,
            u.username,
            u.email
        FROM orders o
        INNER JOIN users u ON o.user_id = u.id
        WHERE o.amount >= ?
          AND u.status = ?
        ORDER BY o.created_at DESC
        LIMIT 50;
    """).strip()

    cursor = conn.cursor()
    # 动态参数通过元组安全传参，严禁使用 f-string 拼接
    cursor.execute(query, (min_amount, user_status))
    return cursor.fetchall()

图3：SQL 长文本编写方式对比：f-string 直接拼接 vs 参数化预编译查询

注意占位符方言：不同的数据库驱动使用的占位符并不相同。SQLite 使用 ?，MySQL (PyMySQL / mysqlclient) 使用 %s，PostgreSQL (psycopg2) 使用 %s，psycopg3 和 sqlite3 也支持命名占位符如 :user_id。无论哪种方言，占位符都不是 Python 的字符串格式化，切勿调用 % 操作符。

四、编写 HTML 长文本的特殊规则与转义处理

在 Python 代码中通过三引号编写 HTML 时，最常遇到的问题是大括号冲突。在现代 Python 开发中，我们经常使用 f-string 注入动态生成的变量，但 HTML 内部常包含 CSS 样式表（例如 <style>body { margin: 0; }</style>）或 JavaScript 脚本块。在 f-string 中，单个大括号会被解析为 Python 表达式，从而引发 SyntaxError 或 KeyError。

1. 大括号双重转义规则

如果必须在 f-string 三引号中嵌入 CSS 或 JS 代码，所有的字面量大括号必须写成双大括号 {{ 和 }}，Python 才会将其还原为单个大括号而不进行表达式求值：

import html
import textwrap

def generate_report_card(title, user_name, score):
    # 对外部不可信输入先做 HTML 转义，防止 XSS 攻击
    safe_title = html.escape(title)
    safe_user = html.escape(user_name)

    # 在 f-string 三引号中，CSS 规则必须使用 {{ 和 }} 双重转义
    html_content = textwrap.dedent(f"""\
        <div class="card">
            <style>
                .card {{
                    padding: 16px;
                    border: 1px solid #ddd;
                    border-radius: 8px;
                }}
                .title {{ font-size: 18px; color: #333; }}
            </style>
            <h3 class="title">{safe_title}</h3>
            <p>用户：<strong>{safe_user}</strong></p>
            <p>得分：{score}</p>
        </div>
    """).strip()
    return html_content

2. 避免 XSS 与模板分离建议

三引号拼接 HTML 仅适合用于脚本小工具、测试用例或轻量的通知邮件片段。如果 HTML 片段超过数十行，或者涉及复杂的循环逻辑与条件判断，硬编码在三引号中容易造成大括号转义混乱，且缺乏 HTML 模板自动转义机制。此时应引入专业模板引擎（如 Jinja2），将 HTML 分离为独立的 .html 模板文件。

五、场景选型与注意事项速查

为了帮助读者在不同开发场景下快速决策，下表总结了在 Python 三引号中处理 SQL 与 HTML 长文本的核心规则与排查要点。

图4：Python 三引号编写长文本 (SQL vs HTML) 核心规则矩阵

六、总结

掌握在 Python 三引号中编写 SQL 和 HTML 长文本的关键，在于认清字符串存储与代码视觉排版的差别。通过使用三双引号、善用反斜杠 \ 控制首行换行、借助 textwrap.dedent() 抹平缩进差异，可以有效保持 Python 代码的整洁性。而在动态内容处理上，始终对 SQL 采用驱动级的参数化查询、对 HTML 采用必要的双大括号转义与 html.escape()，就能确保长文本在满足可读性的同时具备高可靠性与安全性。