去年秋天我在一个内部运维工具里查出过一条注入。写代码的同事用的是 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("...") 在调用形式上几乎一样,只是多了个字母,而它带来的约束是编译器级别的。

