Python re.Pattern.fullmatch 怎样判断整串文本是否匹配

我在做表单字段校验时，最容易误判的一点不是正则怎么写，而是“匹配成功”到底代表什么：match() 只要求从字符串开头开始，search() 允许在任意位置找到片段，而 fullmatch() 才要求整串文本都符合模式。需要完整校验用户名、版本号或固定格式编号时，优先使用编译后的 Pattern.fullmatch()。

官方文档：https://docs.python.org/3/library/re.html

判断“整串是否合规”时，先调用 pattern.fullmatch(text)，再判断返回值是否为 None。不要用 search() 的成功代替完整校验。

先看清三个 API 检查的是哪一段

假设规则是连续的 ASCII 字母和数字，输入是 "ab-123"。同一个模式交给三个 API，结果可能完全不同：

import re

# 规则只允许 ASCII 字母和数字，示例故意放入中间连字符。
pattern = re.compile(r"[A-Za-z0-9]+")
text = "ab-123"

# fullmatch 要求从开头到结尾全部匹配，因此这里返回 None。
whole = pattern.fullmatch(text)
# match 只检查开头，能拿到 "ab" 这一段。
prefix = pattern.match(text)
# search 会在任意位置寻找，仍然能找到 "ab"。
part = pattern.search(text)

print(whole is not None)  # 这里是 False：整串不符合规则。
print(prefix.group() if prefix else None)  # 这里是 ab：只匹配了开头。
print(part.group() if part else None)  # 这里也是 ab：找到了局部片段。

这也是“看起来校验成功，实际上仍放过非法字符”的常见原因。若业务要求整串通过，返回一个局部 Match 并不能说明输入合规。

用 Pattern.fullmatch 完成整串校验

re.compile() 会得到一个 Pattern 对象。把规则编译一次后，使用 fullmatch(string) 判断每个输入即可。成功时返回匹配对象，失败时返回 None。

import re

# 编译一次，后续可以复用同一条规则处理多个输入。
code_pattern = re.compile(r"[A-Z]{2}-[0-9]{4}")

def is_valid_code(value: str) -> bool:
    # fullmatch 覆盖整个 value，前后不能残留其它字符。
    return code_pattern.fullmatch(value) is not None

samples = ["AB-2026", " AB-2026", "AB-2026 ", "AB-26"]
for sample in samples:
    # repr 让首尾空格在排查日志中可见，便于解释失败原因。
    print(repr(sample), is_valid_code(sample))

这里不需要手动在模式前后加 ^ 和 $ 才能表达“整串”。fullmatch() 已经把匹配范围定义为整个字符串；代码读起来也更直接。需要注意的是，模式本身仍然决定允许哪些字符，fullmatch 不会替你放宽字符集。

返回 None 时要把它当成正常分支

匹配失败不是异常，通常只意味着输入不符合规则。业务代码应该显式判断结果，再读取 group()、groupdict() 等属性。直接对 None 调用这些方法，会把普通输入错误升级为 AttributeError。

import re

identifier = re.compile(r"(?P[a-z]+)-(?P[0-9]+)")

def parse_identifier(value: str) -> dict[str, str] | None:
    # 先完整匹配，再读取命名分组，避免对 None 调用 groupdict。
    matched = identifier.fullmatch(value)
    if matched is None:
        return None
    # groupdict 返回模式中声明的字段，适合交给后续业务处理。
    return matched.groupdict()

parsed = parse_identifier("order-2048")
if parsed is None:
    print("输入格式不正确")  # 这是可预期的校验结果。
else:
    print(parsed["prefix"], parsed["number"])

如果输入来自用户或外部接口，建议把失败当作可解释的校验结果，返回字段错误信息；如果模式本身是开发配置，才需要另外关注模式编译阶段的 re.error。

换行和边界选项会改变你的预期

fullmatch() 约束的是整个字符串，但“点号能否匹配换行”“字符类是否包含换行”等行为仍由正则模式和 flags 决定。例如 . 默认不匹配换行，开启 re.DOTALL 后才会把换行纳入点号的匹配范围：

import re

text = "alpha\nbeta"

# 点号默认不能跨过换行，所以整个文本无法被一个点号覆盖。
plain = re.compile(r".+")
# DOTALL 让点号也能匹配换行，但 fullmatch 仍然负责覆盖整串。
multiline = re.compile(r".+", re.DOTALL)

print(plain.fullmatch(text) is not None)  # False
print(multiline.fullmatch(text) is not None)  # True

排查这类问题时，先确认输入是否真的含有换行、回车或首尾空格，再确认 flags 是否符合业务规则。不要为了“让匹配成功”盲目加 DOTALL，否则可能把本来应拒绝的多行输入放进单行字段。

实际项目怎么选：一张小表就够了

我自己的取舍是：字段验证默认先想 fullmatch()，只有需求明确是“从开头读一个前缀”或“在长文本中寻找片段”时，才改用 match() 或 search()。这样可以减少 API 名字相近带来的误用。

常见问题

fullmatch() 失败会抛异常吗？

正常的“不匹配”返回 None，不是异常。只有模式本身非法、类型不符合要求等情况才需要按异常处理。

已经使用 ^ 和 $，还需要 fullmatch 吗？

如果业务语义就是完整字符串校验，fullmatch() 更直观。使用锚点时还要留意多行模式、换行和美元符号的边界语义，不要只凭视觉判断。

为什么 match() 返回成功，但 fullmatch() 返回 None？

通常是输入只有前缀符合规则，后面还残留了空格、换行或其它字符。打印 repr(value) 可以快速观察不可见字符。

总结

Pattern.fullmatch() 的关键价值是把“匹配范围覆盖整串”表达成了明确的 API 语义。编译模式后先调用 fullmatch()，再判断结果是否为 None；同时检查 flags、换行和首尾空格，基本就能避开大多数整串校验误判。