Python 裝飾器：@property

在 Python 的對象模型中，屬性訪問與方法調用共享統一的命名空間，但表達的語義卻不同：屬性描述對象的狀態，方法表達對象的行為。隨著類設計的演進，原本以屬性公布的值可能需要延遲計算、加入校驗邏輯、動態生成或與其他屬性保持同步。

如果直接將屬性改寫為方法，不僅破壞既有的 API，還會使調用方式從：

obj.area

變為：

obj.area()

這種變化違背“接口穩定性”原則，不利于代碼維護。

@property 應運而生，它可以將無參方法以屬性形式呈現，使訪問簡單直觀，但背后仍由方法控制邏輯，同時兼顧封裝性、可擴展性和接口穩定性。

一、什么是 @property

@property 是 Python 內置的裝飾器，用于將實例方法轉換為描述符對象，使其在訪問時觸發自定義邏輯。其核心目標包括：

（1）提供優雅的屬性訪問語法

將方法邏輯以屬性形式暴露，例如 obj.area 而不是 obj.area()。

（2）支持基于方法的動態計算或延遲求值

允許在屬性訪問時執行邏輯，而無需改變 API 約定。

（3）提升封裝性

通過 getter、setter、deleter 控制屬性的讀取、賦值和刪除行為。

（4）保持 API 的向后兼容

當原本的公開屬性需要擴展邏輯時，可用 property 保持調用方式不變。

從 Pythonic 風格看，@property 是“顯式優于隱晦”的體現：它讓用戶以簡單的語法訪問有邏輯支持的屬性。

二、@property 工作原理

@property 的底層基于。

在 Python 中，任何實現以下方法之一的對象都被視為描述符：

__get__(self, instance, owner)

__set__(self, instance, value)

__delete__(self, instance)

描述符對象可以控制某個屬性在 讀取、寫入、刪除 時的行為。

property 本質是內置類：

    def __delete__(self, instance): ...

當我們定義：

        return ...

解釋器會將 x 替換為一個 property 實例，其內部維護三個方法：

? fget：取值邏輯（getter）

? fset：賦值邏輯（setter）

? fdel：刪除邏輯（deleter）

當執行：

obj.x

實際等價于：

A.x.__get__(obj, A)

即調用 fget(obj)。

類似地：

? 賦值 obj.x = value 等價于 A.x.__set__(obj, value)

? 刪除 del obj.x 等價于 A.x.__delete__(obj)

因此，property 與簡單屬性不同，它是具有行為的托管屬性。

三、核心方法：getter/setter/deleter

property 的三個核心組件共同構成完整的托管屬性機制。

（1）getter：屬性讀取邏輯

最基本的 @property 用法是定義只讀屬性。

        return 3.14159 * self.r ** 2

使用：

print(c.area)     # 訪問 area 屬性時會自動調用其 getter（觸發 fget 方法）

（2）setter：屬性賦值邏輯

setter必須使用與 getter 同名的裝飾器：

p.age = 20      # 訪問 age 屬性時會自動調用其 setter（觸發 fset 方法）

說明：@age.setter 并不是隨意命名，而是綁定到同一個 property 對象上，因此名稱必須與 getter 相同。

（3）deleter：屬性刪除行為

用于資源釋放或狀態清理。

del res.conn   # 訪問 conn 屬性時會自動調用其 deleter（觸發 fdel 方法）

說明：@conn.deleter 綁定的是同名 property 對象的刪除邏輯方法，確保刪除行為受控。

getter、setter 和 deleter 都必須保持與原 property 對象同名，確保訪問行為受控。

四、典型應用場景

（1）將計算邏輯轉換為自然的屬性語法

當某個值由其他屬性推導而來時，使用 property 會讓 API 更自然。

        return self.w * self.h

用戶角度：

rect.area   # 比 rect.area() 更直觀

這是最常見的用法：用戶訪問屬性時實際觸發方法邏輯。

（2）為屬性添加校驗邏輯

避免直接暴露內部成員。

        self._c = value

（3）保持 API 向后兼容

當屬性從簡單值變成計算值時，不破壞調用方式。

初始版本中：

obj.speed = 12  # 簡單屬性

后來想加入單位轉換或校驗：

        self._speed = value

外部代碼無需調整。

（4）隱藏內部實現，保護成員命名自由

有了 property 之后，可以隨意修改內部成員名（如從 value → _value → _internal_value），讓類具有更好的可維護性與擴展性。

五、常見誤區

誤區 1：在 getter 內訪問自身屬性導致無限遞歸

錯誤示例：

    return self.x   # 再次訪問 property → 無限遞歸

正確寫法：

    return self._x

誤區 2：誤認為 property 會自動緩存

每次訪問都會重新計算。

如果需要緩存，應使用：

from functools import cached_property

誤區 3：getter、setter 名稱不一致

在使用 property 時，setter 方法必須綁定到同一個 property 對象上，因此名稱必須與 getter 相同，否則不會生效：

    ...

誤區 4：將 property 當作帶參數的方法使用

property 只能表現為無參屬性：

obj.value(3) # 錯誤

小結

@property 基于描述符協議實現，是 Python 中用于創建托管屬性的核心機制。它讓開發者以屬性語法訪問方法邏輯，在保持接口簡潔的同時獲得計算、校驗與封裝能力。通過 getter、setter 與 deleter，可以設計穩定且易維護的類接口。使用 property 時應避免遞歸訪問、濫用復雜邏輯或錯誤綁定 setter，以保持類結構清晰、設計合理。

“點贊有美意，贊賞是鼓勵”