Python中str()与repr()的区别及适用场景

一、设计哲学与表现形式的核心差异

初学者常因两者在处理简单数字（如整数 123）时返回完全相同的字符表面而忽视其本质差别。然而，一旦涉及字符串、日期时间、浮点数以及复杂嵌套对象，两者的分歧便显露无遗：

• str() 的目标是“可读”：过滤掉机器视角的语法标记（如引号、转义字符），只呈现对象所表达的业务文本内容。
• repr() 的目标是“精确”：保留字面量特征，明确区分数据类型（例如区分字符串 '42' 与整数 42），并在可能的情况下让返回值满足 eval(repr(obj)) == obj 的等价表达。

import datetime

now = datetime.datetime(2026, 10, 27, 17, 15, 0)
s = "Hello\nWorld"

# str() 输出：适合给人类展示
print(str(now))  # 示例输出: 2026-10-27 17:15:00
print(str(s))    # 示例输出: 换行呈现为两行

# repr() 输出：适合代码审查与调试
print(repr(now)) # 示例输出: datetime.datetime(2026, 10, 27, 17, 15, 0)
print(repr(s))   # 示例输出: 'Hello\nWorld'（保留单引号与显式转义字符）

图 1-1：str() 与 repr() 的设计受众、转化目标与输出形态比对

二、底层调用与方法回退（Fallback）机制

当我们在代码中对一个实例调用 str(obj) 或 repr(obj) 时，Python 解释器会查找类中对应的特殊方法（即魔术方法）__str__() 与 __repr__()。这两个方法的内部查找与回退规则构成了自定义类设计的关键基石：

1. str(obj) 的回退链条：解释器首先检索该对象所属类是否定义了 __str__()。若已定义，则直接调用并返回结果；若未定义，解释器会自动回退并尝试调用该类的 __repr__() 方法。若两者均未显式定义，则继承自根类 object 的默认 object.__repr__()（输出形如 <__main__.User object at 0x...>）。
2. repr(obj) 的单向规则：解释器仅且只检索 __repr__()。若未显式实现，直接调用基类的 object.__repr__()，绝不会向 __str__() 发生回退。

图 2-1：str() 与 repr() 在解释器内部的派发路径与回退决策流

三、实战代码：自定义类中的标准实现范例

为了直观掌握双魔术方法的配合模式，我们构建一个实际业务常见的 Product（商品）类：

class Product:
    def __init__(self, name: str, price: float, sku: str):
        self.name = name
        self.price = price
        self.sku = sku

    def __str__(self) -> str:
        """提供给普通用户或报表展示的直观文字"""
        return f"{self.name} (售价: ¥{self.price:.2f})"

    def __repr__(self) -> str:
        """提供给调试器、日志或开发人员的精准构造表达式"""
        return f"Product(name={self.name!r}, price={self.price!r}, sku={self.sku!r})"

# 实例化对象
item = Product("机械键盘", 399.0, "KB-87-PRO")

# 场景 1: 面向用户界面展示
print(item)        # 示例输出: 机械键盘 (售价: ¥399.00)
print(str(item))   # 示例输出: 机械键盘 (售价: ¥399.00)

# 场景 2: 面向系统排障与调试
print(repr(item))  # 示例输出: Product(name='机械键盘', price=399.0, sku='KB-87-PRO')

特别陷阱：容器类型（List / Dict / Tuple）的打印行为

很多开发者经常困惑于这样一个现象：明明为自定义类实现了 __str__()，可一旦将对象放入列表或字典中，使用 print([item1, item2]) 打印整个列表时，终端输出的依然不是 __str__() 所定义的美化文本，而是 __repr__() 的内容！

这是 Python 的故意设计。在集合容器内部，为了防止元素间由于缺乏引号或边界标记引发歧义（例如无法分清字符串中的逗号与容器元素分隔逗号），所有标准容器在打印自身时，一律强制对其包含的子元素调用 repr() 而不是 str()。

items = [item]

# 注意：这里外层是 print()，但列表内部元素强制调用了 __repr__()！
print(items)
# 示例输出: [Product(name='机械键盘', price=399.0, sku='KB-87-PRO')]
# 而绝不是: [机械键盘 (售价: ¥399.00)]

图 3-1：不同语法场景、容器机制与格式化标记对底层方法的触发映射

四、工程实践：选型决策与关键避坑指南

在日常业务开发与架构设计中，如何快速判定何时调用或实现哪一个函数？以下对照表与决策树可作为标准化参照：

图 4-1：开发者在方法选型、类实现与日志编写时的标准化决策流与检查项

五、总结

str() 与 repr() 在 Python 中各司其职，互为补充：

• str() 关注的是“用户体验”，解决的是信息传递的舒适度与整洁度；
• repr() 关注的是“开发精度”，解决的是系统运作的透明度与无二义性。

遵循“类定义优先写好 __repr__()，对外展示补充 __str__()，调试排错优先使用 !r”的工程准则，可以从根源上规避对象打印模糊、日志边界不清以及容器显示混乱等一系列常见痛点。