Python 3.14 t-string 上手指南:用标签函数实现 SQL 参数化与日志脱敏

2026-11-16 0 363

去年秋天我在一个内部运维工具里查出过一条注入。写代码的同事用的是 f"SELECT * FROM nodes WHERE host = '{host}'",看着很正常,直到有人往 host 里填了一个带单引号的值。这类问题年年讲,但每次都能找到新的受害者,原因其实不在人粗心,而在于 f-string 从语法上就没给“我想先拿到结构再决定怎么拼”留口子——它一旦求值,剩下的只有一串字符。

Python 3.14 正式版带来的 t-string(PEP 750)正好补上这一块。它不是 f-string 的升级版,也不是另一种格式化语法糖,而是把“字符串模板”本身变成一个对象交给你,插值部分不会被提前转成 str。这篇我想用两个实际用到的场景来把它讲透:一个 SQL 构造器,一个审计日志脱敏器。

t-string 到底返回了什么

先看清楚它的形态。写法跟 f-string 几乎一样,只是前缀换成 t:

from string.templatelib import Template

host = "node-07"
tpl = t"SELECT * FROM nodes WHERE host = {host}"

print(type(tpl))        # <class 'string.templatelib.Template'>
print(tpl.strings)      # ('SELECT * FROM nodes WHERE host = ', '')
print(tpl.values)       # ('node-07',)

关键点在于,tpl 不是字符串。print 它的时候你会看到正常的 SQL 文本,那是因为 Template 实现了 __str__,默认行为跟 f-string 一致。但只要你还没调用 str(),那个 {host} 的位置就还保留着“这里曾经是一个表达式”的信息。

Template 上最重要的两个属性是 strings 和 interpolations:前者是静态片段组成的元组,长度固定为插值数加一;后者是 Interpolation 对象组成的元组。每个 Interpolation 上带着四样东西:

  • value:表达式求值后的实际对象,还没被转成字符串;
  • expression:表达式本身的源码文本,比如 "host" 或 "user.password";
  • conversion:是否有 !r、!s、!a 转换,没有就是 None;
  • format_spec:冒号后面的格式说明符字符串,没写就是空串。

另外 Template 是可迭代的,迭代时会交替产出静态字符串和 Interpolation 对象。写处理器用这个最省事,下面代码都走这条路。

案例一:能防注入的 SQL 构造器

思路是把每个插值替换成 ? 占位符,把值收集到参数列表里,最后交给驱动去执行。这样无论值里有什么字符,都不会进入 SQL 文本。

from string.templatelib import Template


class Query:
    __slots__ = ("sql", "params")

    def __init__(self, sql: str, params: tuple):
        self.sql = sql
        self.params = params

    def __repr__(self) -> str:
        return f"Query(sql={self.sql!r}, params={self.params!r})"


def sql(template: Template) -> Query:
    parts: list[str] = []
    params: list = []

    for item in template:
        if isinstance(item, str):
            parts.append(item)
            continue

        if item.conversion is not None or item.format_spec:
            raise ValueError(
                f"SQL 模板不允许对 {item.expression} 做格式化,"
                f"值应当交给占位符"
            )

        parts.append("?")
        params.append(item.value)

    return Query("".join(parts), tuple(params))

调用起来是这样:

host = "node-07' OR '1'='1"
q = sql(t"SELECT * FROM nodes WHERE host = {host}")
print(q)
# Query(sql='SELECT * FROM nodes WHERE host = ?', params=("node-07' OR '1'='1",))

即便host里全是引号和等号,它也只会作为一个字符串参数被绑定,SQL 结构纹丝不动。这一步的价值其实不在“防注入”这四个字上,而在于编译期就把这条规则固定死了。新人接手代码后就算想图省事,也拼不出一个内联字面量,因为 sql() 只认 Template,传普通字符串进来会直接报错。

让它认识“标识符”和“列表”

真实查询里总有些位置没法参数化,最典型的是表名、列名和 IN 后面的列表。前者是标识符,很多驱动不支持占位符;后者要展开成不定数量的问号。我加了两个轻量包装类型:

class Ident:
    """受信任的标识符,绕过参数化,但必须先校验"""

    __slots__ = ("name",)

    def __init__(self, name: str):
        if not name.isidentifier():
            raise ValueError(f"非法标识符: {name!r}")
        self.name = name


class Expand:
    """把序列展开成一组占位符"""

    __slots__ = ("values",)

    def __init__(self, values):
        self.values = tuple(values)
        if not self.values:
            raise ValueError("空序列不能用 Expand,调用方应当自己处理")

然后 sql() 里分支处理:

        value = item.value

        if isinstance(value, Ident):
            parts.append(value.name)
            continue

        if isinstance(value, Expand):
            parts.append("(" + ", ".join(["?"] * len(value.values)) + ")")
            params.extend(value.values)
            continue

        parts.append("?")
        params.append(value)

这里有个取舍得想清楚。Ident 这种“绕过参数化”的口子,本质上就是把安全责任交回给调用方,所以我只在校验通过 isidentifier() 之后才放行。它会拦住空格、分号、括号这类明显危险的东西,但拦不住一个叫 information_schema 的合法标识符。如果列名来自用户输入,应当在更上层做白名单映射,别指望这个校验。

用法示例:

table = Ident("nodes")
ids = Expand([101, 102, 103])

q = sql(t"SELECT * FROM {table} WHERE id IN {ids} AND status = {status}")
print(q.sql)
# SELECT * FROM nodes WHERE id IN (?, ?, ?) AND status = ?
print(q.params)
# (101, 102, 103, 'online')

展开后的占位符数量跟参数数量严格对应,这点比手工拼字符串靠谱太多——手工拼接时少写一个问号,报错信息通常是“参数数量不匹配”,然后你要在几十行的 SQL 里数逗号。

案例二:按变量名自动遮蔽的审计日志

第二个场景来自同一个项目。审计日志要在记录请求上下文的同时,把密码、token、手机号这类字段遮掉。以前是用一个正则扫字符串,或者每次都记得手动 mask() 一下,漏掉一次就出事。

t-string 给了我一个 f-string 完全做不到的东西:expression。它是编译器捕获的表达式源码,也就是说,标签函数在运行时能知道这个位置写的是 user.password 而不是别的。用它来判断要不要遮,比在值上做类型嗅探可靠得多。

SENSITIVE = {"password", "token", "secret", "phone", "id_card"}


def _mask_phone(value: str) -> str:
    digits = "".join(ch for ch in value if ch.isdigit())
    if len(digits) != 11:
        return "***"
    return f"{digits[:3]}****{digits[-4:]}"


def audit(template: Template) -> str:
    out: list[str] = []

    for item in template:
        if isinstance(item, str):
            out.append(item)
            continue

        # expression 是源码文本,取最后一段属性名
        name = item.expression.rsplit(".", 1)[-1].strip()

        if name not in SENSITIVE:
            out.append(str(item.value))
        elif name == "phone":
            out.append(_mask_phone(str(item.value)))
        else:
            out.append("<redacted>")

    return "".join(out)

调用一下:

user = {
    "username": "lin",
    "password": "hunter2",
    "phone": "13812345678",
}

msg = audit(t"登录尝试 user={user['username']} pwd={user['password']}")
print(msg)
# 登录尝试 user=lin pwd=<redacted>

注意 user['password'] 这种下标访问,expression 拿到的是完整源码字符串 "user['password']",用 rsplit(".") 是切不出 password 的。所以生产代码里我把它换成了更朴素的做法:用正则从表达式里抽出所有标识符,再跟敏感词表求交集。

import re

_IDENT = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")


def _sensitive_hit(expression: str) -> bool:
    return any(tok in SENSITIVE for tok in _IDENT.findall(expression))

这样 user['password']、payload["token"]、req.headers.get("secret") 都能命中。代价是误判率会上去一点,比如一个普通字段叫 phone_book_count 也会被遮掉。这种情况下宁可误遮也不漏遮,审计日志里多几个星号不痛不痒,漏一条密码就是事故。

几个必须记住的坑

一、版本是硬门槛。 string.templatelib 是 3.14 才有的,3.13 上 import 会直接抛 ModuleNotFoundError。如果项目同时要兼容老版本,得用条件导入加降级,或者干脆把这部分功能做成可选。我在一个 3.11 的项目里试过,没有官方 backport 可用。

二、别急着 str()。 一旦对 Template 调了 str(),或者用了 f"{tpl}",你拿回来的就是普通字符串,插值结构全部丢失,再想按变量名判断已经不可能了。标签函数必须直接接收 Template,中间不能有转手。

三、conversion 的取值。 !r 对应 'r',!s 对应 's',!a 对应 'a',没写就是 None,不是空字符串。我在 SQL 构造器里判断 item.conversion is not None,如果写成 if item.conversion,None 也是假值,行为碰巧正确,但可读性差,换个人接手容易看错。

四、format_spec 默认是空串。 不是 None。所以 if item.format_spec: 这种真假判断是安全的,但如果你写 if item.format_spec is not None,那无论写没写冒号都会成立,判断永远为真,后面所有值都会被拒绝。这个错误我调试了十几分钟才发现。

五、性能要心里有数。 t-string 字面量本身会构造一个 Template 对象加若干个 Interpolation,比起 f-string 多了对象创建开销。更重要的是标签函数是一次 Python 函数调用,里面的循环、正则、类型判断都在主线程上跑。我没做过严谨的 benchmark 就不报数字了,但原则很清楚:如果这段逻辑在热路径里每帧都执行,先做缓存或者干脆退回 f-string,别为了语法优雅给自己挖坑。SQL 这种一条请求只编译一次的场合就很合适。

六、大括号还是要转义。 跟 f-string 一样,想在文本里写一个字面量左大括号,得写 {{。JSON 片段塞进 t-string 里最容易忘,一旦忘了会解析成语法错误,报错位置还不一定准。

什么时候别用它

我把项目里的用法梳理了一遍,最后只留下了两个标签函数:sql() 和 audit()。其余的字符串拼接一个没动,继续用 f-string。

判断标准比较朴素:如果这段字符串最终会作为一个整体交给别的系统解释(SQL 引擎、模板引擎、日志采集器),那它值得拥有一个标签函数;如果它只是给人看的提示文本,或者只是拼个 URL 路径,f-string 快且省事,没有任何理由换。t-string 的卖点从来不是“更好的格式化”,而是“把模板从字符串里救出来”。用不上这个特性,就等于给自己加了一层不必要的间接。

最后一段完整代码

把上面的东西合起来,这是可以直接存成 safe_sql.py 跑的最小实现:

from string.templatelib import Template


class Query:
    __slots__ = ("sql", "params")

    def __init__(self, sql: str, params: tuple):
        self.sql = sql
        self.params = params

    def __repr__(self):
        return f"Query(sql={self.sql!r}, params={self.params!r})"


class Ident:
    __slots__ = ("name",)

    def __init__(self, name):
        if not name.isidentifier():
            raise ValueError(f"非法标识符: {name!r}")
        self.name = name


class Expand:
    __slots__ = ("values",)

    def __init__(self, values):
        self.values = tuple(values)
        if not self.values:
            raise ValueError("空序列不能用 Expand")


def sql(template: Template) -> Query:
    parts, params = [], []

    for item in template:
        if isinstance(item, str):
            parts.append(item)
            continue

        if item.conversion is not None or item.format_spec:
            raise ValueError(f"不允许对 {item.expression} 做格式化")

        value = item.value

        if isinstance(value, Ident):
            parts.append(value.name)
        elif isinstance(value, Expand):
            parts.append("(" + ", ".join(["?"] * len(value.values)) + ")")
            params.extend(value.values)
        else:
            parts.append("?")
            params.append(value)

    return Query("".join(parts), tuple(params))


if __name__ == "__main__":
    host = "node-07' OR '1'='1"
    status = "online"
    table = Ident("nodes")
    ids = Expand([101, 102, 103])

    q = sql(
        t"SELECT * FROM {table} "
        t"WHERE host = {host} AND id IN {ids} AND status = {status}"
    )
    print(q.sql)
    print(q.params)

输出会是:

SELECT * FROM nodes WHERE host = ? AND id IN (?, ?, ?) AND status = ?
("node-07' OR '1'='1", 101, 102, 103, 'online')

相邻两个 t-string 字面量在编译期会拼成一个 Template,这点跟普通字符串字面量的隐式拼接规则一致,所以把它们分行写完全没问题,读起来还比一根长长的 t-string 清楚。

如果你手上正好有一个正在被字符串拼接折磨的模块,可以挑最危险的那处先换成标签函数试试。改动量通常比想象中小,因为 sql(t"...") 和原来的 sql("...") 在调用形式上几乎一样,只是多了个字母,而它带来的约束是编译器级别的。

Python 3.14 t-string 上手指南:用标签函数实现 SQL 参数化与日志脱敏
收藏 (0) 打赏

感谢您的支持,我会继续努力的!

打开微信/支付宝扫一扫,即可进行扫码打赏哦,分享从这里开始,精彩与您同在
点赞 (0)

版权声明:
本站资源有的来自互联网收集整理,本站纯免费分享提供学习使用,如果侵犯了您的合法权益,请发送邮件1506151422@qq.com联系,将会及时下架删除。
本站资源仅供研究、学习交流之用,免费开源项目不代表完全可商用,若商业用途请先咨询开发企业能否商用,否则产生的一切后果将由下载用户自行承担。
原创板块未经允许不得转载,否则将追究法律责任。

淘吗网 python Python 3.14 t-string 上手指南:用标签函数实现 SQL 参数化与日志脱敏 https://www.taomawang.com/server/python/3022.html

常见问题

相关文章

猜你喜欢
发表评论
暂无评论
官方客服团队

为您解决烦忧 - 24小时在线 专业服务