python@property属性函数怎么定义

顾言
顾言
发布时间:2026-11-21| 16人浏览过
原创

详细讲解Python中@property属性函数的定义方法、工作原理与应用技巧。从只读属性的创建,到使用setter进行数据安全校验,再到deleter删除管理与常见递归避坑,配合图解与完整代码实例助你快速掌握。

Python 核心特性 面向对象设计与属性封装 阅读时长约 8 分钟
python@property属性函数怎么定义
图 0:Python @property 装饰器与属性函数概览
核心答复:在 Python 中,定义一个属性函数只需在类内部定义一个同名方法,并在该方法上方添加内置装饰器 @property。这样既保留了普通字段 obj.name 的简洁访问方式,又能够在底层以函数调用的形式执行动态计算、类型检查或逻辑拦截。当需要支持修改或删除该属性时,再通过 @属性名.setter 和 @属性名.deleter 进行成对扩展定义。

一、为什么需要 @property 属性函数

在面向对象编程中,我们经常需要在读取或修改实例属性时执行额外逻辑。例如:判断传入的年龄是否大于0、在获取面积时根据长宽动态计算、或者在更新价格时记录变更日志。

在传统方式下,通常会像 Java 那样为属性编写显式的 get_score() 和 set_score(val) 方法。这种方式虽然能实现数据验证与封装,但在 Python 代码中显得冗长且不够自然。更棘手的是,如果最初设计类时使用的是公开属性 obj.score,后来需要加入数值校验,就不得不强迫所有外部调用方把 obj.score 改成 obj.get_score(),从而破坏向下兼容性。

Python 提供的 @property 内置装饰器优雅地化解了这一矛盾:它将方法包装为描述符(Descriptor),使得外部能够像访问普通属性一样直接读写,而解释器在底层自动执行对应的方法函数。

python@property属性函数怎么定义
图 1:传统 Getter/Setter 显式方法与 @property 访问机制对比

二、@property 属性函数的基础定义步骤(只读属性)

定义一个基础的只读属性函数非常直观,整个过程主要包含两个关键动作:

  1. 使用单下划线前缀存储内部变量:在构造函数 __init__ 中,将真实数据存储在 self._属性名(例如 self._radius),避免与对外公开的属性名冲突。
  2. 添加 @property 装饰器:定义与公开属性同名的方法,加上 @property 装饰,该方法只接受 self 参数,并在函数体内返回内部变量或计算结果。

下面是一个完整的只读计算属性示例:

class Circle:
    def __init__(self, radius):
        # 将真实数据保存在内部私有变量 _radius 中
        self._radius = radius

    @property
    def radius(self):
        """读取圆的半径"""
        return self._radius

    @property
    def area(self):
        """动态计算圆的面积,无需外部加括号调用"""
        return 3.14159 * (self._radius ** 2)

使用方式及输出结果示例:

执行示例与结果输出
>>> c = Circle(5)
>>> print(c.radius) # 读取半径
5
>>> print(c.area) # 像属性一样读取动态计算结果
78.53975
>>> c.area = 100 # 尝试写入只读属性
AttributeError: property 'area' of 'Circle' object has no setter

可以看到,当外部尝试对 c.area 赋值时,Python 会抛出 AttributeError,明确提示该属性没有配置 setter。这种开箱即用的只读保护特性,能够极大降低对象状态被外部误改的风险。

python@property属性函数怎么定义
图 2:@property 属性函数定义的三个关键步骤流程图

三、定义可写属性:配置 Setter 与参数校验

如果属性需要支持被外部修改,同时又要求对赋值进行严格的安全检查,我们就需要为该属性配置 setter。

配置 setter 的语法格式为:@属性名.setter。需要特别注意的是,修饰的方法名称必须与之前 @property 修饰的方法名称完全一致,并且该方法接收两个参数:self 和外部传入的新值 value。

1. 完整代码定义范例

以下代码定义了一个表示温度的 Temperature 类。该类通过 setter 函数严格把关传入的摄氏度数值,杜绝低于绝对零度(-273.15°C)的非法数值进入对象内部:

class Temperature:
    def __init__(self, celsius=0.0):
        # 在构造函数中直接通过属性赋值,从而复用 setter 的校验逻辑
        self.celsius = celsius

    # 1. 定义读取方法 (Getter)
    @property
    def celsius(self):
        return self._celsius

    # 2. 定义赋值方法 (Setter),方法名必须与属性名相同
    @celsius.setter
    def celsius(self, value):
        # 第一道防线:类型校验
        if not isinstance(value, (int, float)):
            raise TypeError("温度数值必须是整型或浮点型")
        
        # 第二道防线:物理范围校验
        if value < -273.15:
            raise ValueError("温度不能低于绝对零度 (-273.15°C)")
        
        # 校验通过,安全写入底层私有变量
        self._celsius = float(value)

    # 3. 动态转换属性(只读华氏度)
    @property
    def fahrenheit(self):
        return (self._celsius * 9 / 5) + 32

使用方式及校验效果:

执行示例与结果输出
>>> t = Temperature(25)
>>> print(t.celsius) # 正常读取
25.0
>>> print(t.fahrenheit) # 自动同步计算华氏度
77.0
>>> t.celsius = 30 # 正常更新温度
>>> print(t.fahrenheit)
86.0
>>> t.celsius = "hot" # 传入错误类型触发拦截
TypeError: 温度数值必须是整型或浮点型
>>> t.celsius = -300 # 传入低于下限数值触发拦截
ValueError: 温度不能低于绝对零度 (-273.15°C)
python@property属性函数怎么定义
图 3:@property.setter 属性赋值与参数安全校验执行流程

四、定义删除属性:配置 Deleter

除了读(Getter)和写(Setter),Python 还支持监听对象的删除操作。当执行 del obj.attr 语句时,如果定义了 @属性名.deleter,Python 就会触发该方法。

Deleter 常用于在属性被删除时执行清理资源、重置默认值或阻止属性被意外删除的操作:

class UserSession:
    def __init__(self, token):
        self._token = token

    @property
    def token(self):
        if self._token is None:
            raise AttributeError("Token 已被注销,无法访问")
        return self._token

    @token.deleter
    def token(self):
        # 在删除属性时进行安全清理
        print("正在注销用户 Token 并清理会话资源...")
        self._token = None
执行示例与结果输出
>>> session = UserSession("abc_token_123")
>>> print(session.token)
abc_token_123
>>> del session.token
正在注销用户 Token 并清理会话资源...
>>> print(session.token)
AttributeError: Token 已被注销,无法访问

五、常见避坑指南与注意事项

在初学和使用 @property 时,有几个容易忽视但后果严重的细节需要特别留意:

高频陷阱 1:在 setter 内部误用属性名导致无限递归

在 setter 函数内部,必须将值赋给带有单下划线的私有变量 self._name = value,而绝对不能写成 self.name = value。

这是因为 self.name = value 本身就会再次调用 setter 函数,从而引发无限递归循环,最终抛出 RecursionError: maximum recursion depth exceeded 错误崩溃。

高频陷阱 2:Getter 与 Setter 的方法名不一致

无论是 @property、@name.setter 还是 @name.deleter,它们修饰的函数名称必须与属性名 name 完全一致。若写成不同的名字(如 def set_name(self, value):),setter 将无法绑定到原属性上,赋值操作将无法生效。

最佳实践 3:避免在 @property 中执行耗时或有副作用的操作

使用点号访问属性(如 obj.data)给读者的直观预期是轻量、低延迟且无明显副作用的。如果该属性需要发起数据库全表扫描、远程网络请求或复杂的密集计算,建议将其定义为普通的动词方法(例如 fetch_remote_data()),明确告知调用方该操作具有时间成本。

六、核心要点总结与适用场景对照

为了方便在实际开发中快速查阅和决策,下表整理了 @property 的核心组成要素及其作用:

组成部分 装饰器语法 参数要求 触发时机 典型用途
Getter @property (self) x = obj.attr 读取数据、只读属性控制、动态计算派生数据
Setter @attr.setter (self, value) obj.attr = val 属性赋值、类型检查、数值合法性校验
Deleter @attr.deleter (self) del obj.attr 属性删除时执行数据清理、重置或防删拦截

总结来说,当你需要保护对象内部数据一致性、拦截非法赋值、实现基于现有属性的实时计算,或者在不更改调用接口的前提下重构类属性时,@property 都是 Python 中最标准、最符合语言习惯的利器。

python@property属性函数怎么定义
图 4:python @property 属性函数知识体系与开发避坑全景总结
相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。