访问已移除API元素时抛出异常的最佳设计模式探讨

场景说明 #

我之前在库中用DeprecationWarning提示用户某个方法已废弃，比如A.foo会提醒改用A.bar。现在要彻底移除A.foo，但还是想保留清晰的错误提示，帮用户顺利重构代码。目前的方案是保留foo方法，里面抛出NameError带提示，但不确定这是不是最优解，想找更合适的设计模式。

推荐方案 #

1. 自定义专属异常类 #

Python标准库没有专门针对“已移除API”的异常类型，所以自定义一个异常类是最清晰的做法。这样用户不仅能看到明确的错误信息，还可以针对性地捕获这类异常：

class RemovedAPIAccessError(Exception):
    """访问已移除的API元素时抛出的异常"""
    pass

class A:
    def foo(self):
        raise RemovedAPIAccessError(f"`A.foo` 已被移除，请使用 `A.bar` 替代。")
    
    def bar(self):
        # 业务逻辑实现
        pass

这种方式的优势在于错误语义精准，不会和NameError（通常用于名称未定义）、AttributeError（属性不存在）这类标准异常混淆，用户一看异常类型就知道是API被移除导致的问题。

2. 用__getattr__捕获不存在的属性访问 #

如果不想在类中保留冗余的foo方法，可以利用Python的__getattr__魔法方法。当用户访问类实例上不存在的属性时，这个方法会被触发，我们可以在这里针对已移除的API给出定制提示：

class RemovedAPIAccessError(Exception):
    """访问已移除的API元素时抛出的异常"""
    pass

class A:
    def bar(self):
        # 业务逻辑实现
        pass
    
    def __getattr__(self, name):
        if name == 'foo':
            raise RemovedAPIAccessError(f"`A.foo` 已被移除，请使用 `A.bar` 替代。")
        # 其他不存在的属性按正常逻辑抛出AttributeError
        raise AttributeError(f"'A' 对象没有属性 '{name}'")

这种方案更符合“彻底移除”的语义，类结构更干净，同时又能给用户提供迁移指引。需要注意的是，__getattr__只会在访问不存在的属性时触发，不会影响现有属性的正常访问。

不推荐使用NameError的原因 #

NameError的语义是“名称未找到”，比如引用了未定义的变量。如果保留foo方法却抛出NameError，语义上并不准确——因为A.foo这个名称是存在的，只是功能被移除了。如果用__getattr__的话，默认会抛出AttributeError，但自定义异常能传递更明确的错误信息，帮助用户更快定位问题。

总结 #

• 优先自定义专属异常类，让错误类型更清晰，方便用户识别和处理；
• 若想保留方法入口，直接在方法内抛自定义异常；若想彻底清理类结构，用__getattr__捕获访问并提示；
• 避免滥用标准异常，确保错误语义和实际场景匹配。

内容的提问来源于stack exchange，提问作者obviouslyalive