做 Python 这几年最让我觉得“这个类像个正经类”的时刻就是给它写好__repr__的那一刻。你可能觉得这不就一个返回字符串的方法嘛有什么好讲的。但真到排查线上问题时你打出来的每个对象长什么样直接决定了你能不能在一堆日志里三秒定位问题。我最近在整理 Python 3.12 MagicMethods 系列本来想一篇把几个常用魔术方法混着讲完写着写着发现__repr__值得单独拿出来说因为它的细节、坑、以及 3.12 里 f-string 增强带来的新写法单靠随手写两行根本说不透。这篇就顺着实际使用场景聊清楚__repr__到底怎么用、怎么写、怎么避坑。先说个实际体验。之前我带了个项目团队里一位同学给订单类只写了__str__没写__repr__。平时直接print(order)没问题可一到排查问题打日志、看调试器变量列表、把对象塞进 list 里观察时看到的全是__main__.Order object at 0x0000021D5D...然后一屋子人盯着内存地址发呆。后来我把__repr__补上日志瞬间可读问题也马上找到了。从那天起我对__repr__的重视程度直接拉满。这是 Python 3.12 MagicMethods 系列里真正能改变日常开发体验的一个方法下面从原理到实操逐个层次拆开。1. 为什么单独拆__repr__来讲它解决了什么问题1.1 调试时的“第一现场”决定你看到什么很多人分不清__repr__和__str__代码里随便挑一个写。但这两个方法在 Python 里的分工完全不同。__repr__是给解释器、调试器、日志、以及开发者看的目标是“看到它就知道这个对象是什么”而__str__是给最终用户看的目标是“读起来舒服”。当你在交互式终端里输入obj按回车或者把一个对象放到列表、字典、集合里打印时Python 调用的是repr()也就是__repr__而不是__str__。这是最容易被忽略的点。举个例子我们定义一个最简单的商品类class Product: def __init__(self, sku, name, price): self.sku sku self.name name self.price price def __str__(self): return f{self.name}¥{self.price}如果只定义__str__那么p Product(SKU-1001, 无线机械键盘, 399) print(p) # 输出无线机械键盘¥399 [p] # 输出[__main__.Product object at 0x000001D2...]看到区别了吗列表里显示的是完全无用的一串内存地址。你在写业务代码时经常要print(orders)、logger.debug(cart.items)这时如果__repr__缺失你看到的全是地址相当于调试时被人蒙上了一层纱。而只要补上__repr__容器打印时就会自动用它。1.2__repr__和__str__的边界别踩默认回退的坑这里有一个默认行为容易混淆如果类里只定义__repr__没定义__str__那么当你调用str(obj)或print(obj)时Python 会退回去调用__repr__但如果只定义__str__而没有__repr__repr(obj)不会反过来调用__str__它会老老实实使用object.__repr__也就是给你返回“内存地址字符串”。这个不对称让很多人踩坑。定义了str(obj)输出repr(obj)输出都未定义object 默认地址object 默认地址只定义__str__调用__str__object 默认地址只定义__repr__调用__repr__调用__repr__两者都定义调用__str__调用__repr__所以我的建议是优先写__repr__它比__str__更“底层”、更通用。等你需要面向用户的友好文案时再单独写__str__。Python 官方文档也明确建议__repr__尽量做到“无歧义”最好能返回一个eval(repr(obj))可以重建对象本身的字符串而__str__只是“可读性强”。这个原则直接影响我们后面怎么实现它。2. 实现__repr__的正确姿势从需求到现成方案2.1 黄金法则尽量返回能“重建对象”的字符串Python 官方对__repr__的原始建议是repr(obj)的返回值应该尽可能像一条“合法的 Python 表达式”使得eval(repr(obj))可以重新创建出一个等值的对象。比如设计一个坐标点类class Point: def __init__(self, x, y): self.x x self.y y def __repr__(self): return fPoint(x{self.x}, y{self.y})Point(1, 2)的 repr 就是Point(x1, y2)直接eval就能回来一个同样坐标的点。这种写法在调试时非常爽因为你可以从日志里复制对象文本再贴回代码或交互环境里接着调试。当然不是所有对象都能做到这一点比如包含文件句柄、网络连接、线程锁的对象硬拼一个eval可重建的表达式并不现实。这时标准做法是返回一个清晰描述对象状态和身份的字符串例如FileHandle(path/tmp/a.log, closedFalse)至少一眼知道它是干嘛的。我没少见过有人在__repr__里直接返回self.__dict__的字符串虽然信息完整但不好看而且字典顺序在 Python 3.7 之后是插入序同一个类不同实例显示风格一致但依旧显得“不专业”。更好的做法是拼成构造调用的样子。2.2 手写实现f-string 与!r是黄金搭档最常见的写法是这样def __repr__(self): return f{self.__class__.__name__}(sku{self.sku!r}, name{self.name!r}, price{self.price!r})这里用!r非常关键它表示让子属性也调用repr()而不是str()。如果不加!r属性是字符串时会显示成没有引号的name无线机械键盘但eval出来会变成变量名完全不对加上!r后字符串会带引号数字也保持数字的字面量这样整个表达式才是合法、无歧义的。用self.__class__.__name__而不是手写类名是另一个技巧。万一你以后做了子类继承repr 会自动显示成子类名而不会傻傻地继续打“Point”或“Order”省得每次子类都要重写一遍__repr__。这个习惯我强烈建议从一开始就养成。2.3 Python 3.12 的 f-string 增强对 repr 实现的直接影响Python 3.12 引入了 PEP 701重写了 f-string 的解析器带来的一个直接好处就是f-string 的表达式部分可以复用与外层相同的引号也支持反斜杠和多行表达式。以前写某些复杂的 repr 格式化逻辑时你得小心翼翼地嵌套不同引号非常别扭。到了 3.12很多写法自然了。举个我实际用到的例子。我想写一个“自动展示所有实例属性”的通用__repr__在一个基类里定义一次所有子类都能用class BaseModel: def __repr__(self): fields , .join(f{k}{v!r} for k, v in vars(self).items()) return f{type(self).__name__}({fields})这段代码在 Python 3.11 里也能跑但 PEP 701 改了底层解析后这种紧凑表达式的容错性更好也更适合在未来继续扩展成多行条件表达式的写法。实际测试在 3.12 里下面这种以前会报语法错误的写法现在已经合法def __repr__(self): return fOrder(id{self.id}, items{self.items if self.items else []})在 3.11 里你需要在 f-string 表达式中避免和外层同类型的引号碰撞表达式里如果出现单引号且外层也用单引号就得绕来绕去。3.12 直接放宽了限制。我不建议为了炫技而刻意写复杂表达式但知道 3.12 对 f-string 更宽容后你在实现__repr__时可以更关注逻辑本身而不是去琢磨引号转义。2.4 用 dataclass 免手写但切记关注reprFalse如果你用的 Python 3.7最简单获得漂亮 repr 的方式是直接声明dataclass。它默认生成的 repr 是类似Point(x1, y2)的标准格式非常符合“可 eval 重建”的原则。但有一点必须注意dataclass 默认会把所有字段都带入 repr如果你的类里有密码、token、私密密钥这类敏感字段repr 会毫不留情地打印出来一旦混进日志或异常上报系统就是安全事故。为了避免这种问题你需要用field(reprFalse)排除敏感字段from dataclasses import dataclass, field dataclass class User: name: str email: str password: str field(reprFalse)这样User(张三, ab.com, secret)的 repr 是User(name张三, emailab.com)密码不会出现在任何 repr 输出里。我在项目里给所有敏感字段统一加了reprFalse这样一个策略就能避免一大票日志泄露隐患。另外如果 dataclass 默认的显示顺序和你想展示的顺序不一致或者你希望完全自定义显示那就得手动写__repr__并覆盖默认行为。dataclass 不会因为你自己定义了__repr__而覆盖你它的默认 repr 只在你不定义时生效。3. 实战从零实现订单类的合格__repr__3.1 先用 Python 3.12 搭建一个干净环境做任何代码实验前先把环境管好。Python 3.12 是当前新特性落地最快的稳定版本这个 MagicMethods 系列也建议在 3.12 上跑。如果你已经有 conda创建一个专门的环境很简单conda create -n magic-repr python3.12 -y conda activate magic-repr python --version跑一下python --version看到Python 3.12.x就说明环境没问题。我习惯把项目里所有代码在干净环境里验证一遍避免因为掺了旧版本包导致 f-string 的行为不稳定。你完全可以按这个命令来复现我下面的示例。3.2 需求分析这个订单类调试时到底想看到什么假设我们要做一个订单管理系统里的Order类每个订单包含订单号order_id字符串如ORD-20250301-001金额amount浮点数状态status字符串如pending/paid/shipped商品清单items一个列表每个元素是 (商品名, 数量, 单价) 这样的元组调试时我们希望一眼看到订单号和状态数量太多的话再展开看商品。所以最合适的 repr 是类似Order(ORD-20250301-001, amount399.0, statuspending, items[(机械键盘, 1, 229.0), (鼠标垫, 2, 49.9)])这样既保留了构造调用的外形又能完整重建对象。3.3 亲手实现并验证实现代码如下from typing import List, Tuple class Order: def __init__(self, order_id: str, amount: float, status: str, items: List[Tuple[str, int, float]]): self.order_id order_id self.amount amount self.status status self.items items def __repr__(self): return ( fOrder( f{self.order_id!r}, famount{self.amount!r}, fstatus{self.status!r}, fitems{self.items!r} f) )然后创建一个订单进行测试order Order( ORD-20250301-001, 328.8, pending, [(机械键盘, 1, 229.0), (鼠标垫, 2, 49.9)] ) print(repr(order)) # Order(ORD-20250301-001, amount328.8, statuspending, items[(机械键盘, 1, 229.0), (鼠标垫, 2, 49.9)]) print([order, order]) # [Order(ORD-20250301-001, amount328.8, statuspending, items[(机械键盘, 1, 229.0), (鼠标垫, 2, 49.9)]), Order(...)]列表打印不再是一堆内存地址而是完整可读的对象信息。更妙的是这个输出可以直接evalcopy_order eval(repr(order)) print(copy_order order) # 如果没实现 __eq__这里会 False但字段值完全一致这里要提醒一句eval只适合在可信任的环境中做验证。不要在生产代码里对来自日志、用户输入的字符串直接eval会有严重的安全风险。我只是用它来验证 repr 是否符合“可重建”这一黄金法则。3.4 写一个自动集齐属性的极简方案如果订单类有几十个属性手写字段拼字符串太容易漏。这时我推荐在基类里写一个通用版本所有子类自动获得“属性完整版”的 reprclass BaseModel: def __repr__(self): args , .join(f{k}{v!r} for k, v in vars(self).items()) return f{type(self).__name__}({args})这样Order类只要继承BaseModel并且不覆盖__repr__打印出来的效果和手写差不多但字段顺序完全按实例属性插入顺序不需要维护。我之前在一个后台管理项目里用过这个模式几十个数据模型类只用了一个基类方法再没出现过“某个新字段没出现在 repr 里”的疏漏。不过也要注意这种方案的输出并不一定等同于构造调用因为字段顺序可能与构造参数顺序不一致而且有些属性可能是派生出来的而非构造函数传入。如果你追求“eval可重建”最好还是显式写出构造参数的顺序。通用方法更适合内部管理系统这种“调试信息完备比可重建更重要”的场景。4. 常见问题与排查技巧实录4.1__repr__没生效多半是容器显示调用的不是__str__几乎每周都会有人问我明明写了__str__打印列表怎么还是... object at ...原因前面讲过了容器打印元素时调用的是repr()。你写__str__无法覆盖repr()的默认行为。所以如果发现列表、字典里的对象显示成内存地址先检查类里是否定义了__repr__。没有的话加上的那一刻瞬间生效。另一个相关坑是如果你在__repr__里写了return f{self!r}会因为无限调用字符串格式化而递归直接抛出RecursionError。我见过不止一次因为有人想“让 repr 和 str 一致”却写错了方式。正确做法是调用return f{self.__str__()}或直接return str(self)同时要小心str(self)内部如果用了!r也会重复递归。实际上最稳妥的方式是取具体的属性来拼字符串不要再用self的整体表示。4.2 循环引用对象repr 也会无限递归当两个对象互相引用时简单的 repr 实现会导致无限递归。比如class User: def __init__(self, name, managerNone, team()): self.name name self.manager manager self.team team def __repr__(self): return fUser(name{self.name!r}, manager{self.manager!r}, team{self.team!r})如果u1.manager u2u2.manager u1打印u1时repr 会递归渲染u2而u2又渲染u1最终爆栈。我在做组织架构树的时候踩过这个坑。解决办法有三条在 repr 中不要渲染完整的管理者对象只渲染其“标识”比如用户名或 ID。给复杂对象加一个“深度控制”或“引用标记”例如managerUser: id123不继续往下展开。使用标准库reprlib的repr()工具来截断长内容帮助解决容器太长的问题。我推荐优先采用“标识法”在这些具有引用关系的对象里__repr__只显示核心字段以及和它直接关联对象的轻量摘要。例如class User: def __repr__(self): manager_info fid{self.manager.id} if self.manager else None return fUser(name{self.name!r}, manager{manager_info})这样既保留了对引用关系的提示又不会触发递归。4.3 别把关键信息写进 repr否则日志会帮你“泄露”如前面提到的repr 会被自动用于异常消息、日志记录、调试器展示。很多框架在日志里记录异常上下文时会调用repr()来打印对象。如果你把密码、密钥、身份证号、手机号这些敏感信息放在 repr 里日志一旦被同步到分析平台或运维工具就可能泄露给不该看到的人。我建议每个团队都给 repr 制定两条铁律不打印任何隐私字段用field(reprFalse)或手写时直接跳过。不打印体积过大的字段比如一整个日志数组、图片二进制内容。如果实在需要用reprlib.recursive_repr或截断到前 N 个元素。reprlib是标准库很可能你没用过。它提供一个repr()函数可以对超长容器自动做截断处理比如reprlib.repr([1,2,3...])会输出[1, 2, 3, ...]。把它用在 repr 里控制大列表展示非常合适import reprlib class BigOrder: def __init__(self, items): self.items items def __repr__(self): return fBigOrder(items{reprlib.repr(self.items)})这种输出在调试中依旧能看出大意又不会导致日志文件被撑爆。4.4 性能与副作用repr 也讲究“轻”调试时我们经常打印对象但别初始化了在 repr 里做重活。比如有的同学在__repr__里调用第三方接口去补充信息或者跑一个大循环求值这种操作会让打印、日志、断点查看全部变慢严重时还会因为一次网络请求卡住整个调试流程。最夸张的一次我在一个查询报表的代码里发现有接口调用写进了__repr__导致日志每写一条就发一次 HTTP 请求日志系统直接被打挂。__repr__的定位是“快速反馈”你应当让它在微秒级返回只输出当前对象内部已有状态。不要在里面访问外部资源、触发 I/O、做大量计算。如果确实需要更详细的信息用显式的实例方法来输出而不是通过 repr 隐式触发。4.5 一个实用技巧用!r保证嵌套属性不被“美化”我在 2.2 提过!r这里再加强一下。如果你在 repr 里写fname{self.name}而self.name是字符串那么它显示成裸文本例如name张三如果写成fname{self.name!r}会显示成name张三。这种引号差异对调试很重要因为你能一眼区分字符串和标识符同时嵌套对象比如items元组列表也得到完整显示。养成所有拼接字段都习惯性写!r的习惯一步到位不用担心以后想扩展成eval可重建时被格式坑。如果你希望某个字段以更“人类友好”的方式显示可以使用!s比如一个枚举状态字段想显示成pending还是pending如果想一眼看出类型还是!r更安全。我一般在 repr 中主要用!r只有在明确字段是自定义类型、且有额外安全显示需求时才会用!s。5. 扩展repr 与__format__、__str__协作的加分写法5.1 让 f-string 中的默认格式走__str__!r走__repr__在 f-string 中不带修饰符的f{obj}默认调用__format__而__format__的默认实现会调用__str__带上!r则调用__repr__。这意味着你可以同时定义好__repr__和__str__让普通日志显示可读性更强的文本让调试信息显示完整无歧义的结构。例如class Order: def __repr__(self): return fOrder(id{self.order_id!r}, status{self.status!r}) def __str__(self): return f订单 {self.order_id} 当前状态{self.status}那么在print(order)或 f-string 里输出的是友好中文而在列表、日志的%r格式、调试器里输出的是结构化完整内容。这是一套非常灵活的“双模式”方案。5.2 自定义__format__微调展示如果你想支持类似f{order:short}这样的自定义格式可以实现__format__def __format__(self, format_spec): if format_spec short: return f{self.order_id}:{self.status} return str(self)但这种需求在大多数业务代码里并不常见。我更推荐把复杂展示控制放在__repr__和__str__两层解决不要过早引入__format__免得代码里到处是格式魔法。如果你在做报表、数据导出的场景__format__会很有用但普通模型类保持简单就好。5.3 别忘了__eq__和__hash__与 repr 的最佳实践在数据类中你会经常把__repr__、__eq__、__hash__放在一起考虑。__repr__的“可重建”目标是针对对象的值而__eq__则定义什么叫做“相等”。如果你实现了__repr__返回构造表达式但没实现__eq__那么eval(repr(a)) a会是比较身份返回 False这会让“可重建”验证看起来很失败。要不要实现__eq__取决于你的业务需求但为了 repr 验证过程更顺畅建议至少对纯数据模型实现__eq__或使用dataclass自动生成。如果你用dataclass(frozenTrue)repr、eq、hash 绑定在一起语义更严谨也更符合不可变对象的设计。在实现纯函数式模块或配置类时我经常这么写。个人经验补充这套__repr__的实践方法是我在不同项目里反复打磨出来的。说实话一开始我自己也偷懒觉得默认地址字符串“能跑就行”直到在排查一个内存溢出问题时logs 里满屏的内存地址让我彻底崩溃。后来花了一个下午把所有模型类的 repr 都补齐再调试问题效率直接翻倍。你如果也想快速提升代码的可调试性建议先做一件事给你的核心业务类各写一个“一眼能看懂”的__repr__并坚持用!r来渲染属性。写完跑一遍repr(obj)再跑一遍eval(repr(obj))仅限简单不可变对象和信任环境感觉完全不一样。最后再提一个小技巧如果你担心忘了写可以用dataclass帮你兜底但永远记得检查敏感字段的reprFalse。这是我在实际项目里踩过最多的坑没有之一。
