类(class)是创建对象的一种模板。它把一组相关的数据和处理这些数据的函数放在一起,形成一个更完整的模型。
例如,一本书有标题、作者这些数据,也可以有介绍自己、修改标题这些行为。用类描述后,每一本具体的书都是一个对象:
01class Book: 02 def __init__(self, title, author): 03 self.title = title 04 self.author = author 05 06 def describe(self): 07 return f"《{self.title}》的作者是{self.author}。" 08 09first_book = Book("Python 入门", "小林") 10second_book = Book("FastAPI 实战", "小周") 11 12print(first_book.describe()) 13print(second_book.describe())
Book 是类,first_book 和 second_book 是两个实例。它们使用同一套结构,但各自保存不同的标题和作者。
Book
first_book
second_book
类适合描述「有状态、有行为」的对象。如果只是临时组合几个字段,字典往往更直接;当数据和操作逐渐变多时,类可以让代码的职责更清晰。
使用 class 定义类,类名通常采用大驼峰命名,例如 Book、ChatSession。类体通过缩进表示:
class
ChatSession
1class User: 2 pass 3 4user = User() 5print(user)
pass 表示暂时没有实现任何内容。User() 会创建一个 User 实例,调用类的过程也叫实例化。
pass
User()
User
通常会在类中定义 __init__(),为实例准备初始数据:
__init__()
1class User: 2 def __init__(self, name, email): 3 self.name = name 4 self.email = email 5 6user = User("小明", "xiaoming@example.com") 7print(user.name) # 小明 8print(user.email) # xiaoming@example.com
__init__() 会在实例创建后自动调用。self 代表当前实例,self.name 和 self.email 是这个实例自己的属性。调用 User("小明", ...) 时,传入的参数会交给 __init__(),不需要手动传 self。
self
self.name
self.email
User("小明", ...)
很多教程会把 __init__() 口语化地称为「构造函数」,但从 Python 的严格机制看,它是初始化方法。真正负责创建实例的是 __new__()。调用 User(...) 时,可以把过程简化理解为:先由 __new__() 创建并返回实例,再由 __init__() 给这个实例填充初始数据。
__new__()
User(...)
01class User: 02 def __new__(cls, name): 03 print("1. __new__: 创建实例") 04 instance = super().__new__(cls) 05 return instance 06 07 def __init__(self, name): 08 print("2. __init__: 初始化实例") 09 self.name = name 10 11user = User("小明") 12print(user.name)
输出顺序是先执行 __new__(),再执行 __init__()。__new__() 接收类本身 cls,必须返回一个实例;__init__() 接收已经创建好的实例 self,不需要返回实例。
cls
如果 __new__() 没有返回当前类的实例,Python 不会继续调用对应的 __init__()。重写 __new__() 常见于继承 str、tuple 等不可变类型,或实现单例等特殊创建逻辑;普通业务类通常只需要编写 __init__()。
str
tuple
每个实例可以拥有不同的属性值,也可以在创建后增加属性:
01class Account: 02 def __init__(self, owner): 03 self.owner = owner 04 self.balance = 0 05 06account = Account("小明") 07account.balance = 100 08account.currency = "CNY" 09 10print(account.owner) 11print(account.balance) 12print(account.currency)
不过,业务需要的属性最好在 __init__() 中统一初始化。这样,其他代码只要看到类的定义,就能知道一个实例通常包含哪些数据。
写在类中的函数叫作方法。实例方法的第一个参数通常是 self,通过它读取或修改当前实例:
01class Counter: 02 def __init__(self): 03 self.value = 0 04 05 def increase(self, amount=1): 06 self.value += amount 07 08 def current(self): 09 return self.value 10 11counter = Counter() 12counter.increase() 13counter.increase(4) 14print(counter.current()) # 5
调用 counter.increase(4) 时,Python 会自动把 counter 作为 self 传给方法。可以把它近似理解为 Counter.increase(counter, 4),所以方法内部才能访问 self.value。
counter.increase(4)
counter
Counter.increase(counter, 4)
self.value
方法不仅可以读取属性,也可以返回计算结果。把和对象状态有关的操作放进方法,调用方就不需要了解内部实现:
01class Order: 02 def __init__(self, price, quantity): 03 self.price = price 04 self.quantity = quantity 05 06 def total(self): 07 return self.price * self.quantity 08 09 def summary(self): 10 return f"共 {self.quantity} 件,合计 {self.total()} 元" 11 12order = Order(30, 2) 13print(order.summary()) # 共 2 件,合计 60 元
如果希望 print(order) 时显示更有意义的内容,可以实现 __str__():
print(order)
__str__()
1class User: 2 def __init__(self, name): 3 self.name = name 4 5 def __str__(self): 6 return f"User(name={self.name})" 7 8print(User("小明")) # User(name=小明)
以双下划线包围的 __init__、__str__ 等方法叫特殊方法。它们通常由 Python 在特定时机自动调用,不需要像普通方法那样直接使用。
__init__
__str__
类中还可以定义类方法和静态方法。它们与实例方法的区别在于,自动接收的第一个参数不同:
@classmethod
@staticmethod
01class User: 02 def __init__(self, name): 03 self.name = name 04 05 def rename(self, name): 06 self.name = name 07 08 @classmethod 09 def guest(cls): 10 return cls("游客") 11 12 @staticmethod 13 def is_valid_name(name): 14 return bool(name.strip()) 15 16user = User.guest() 17user.rename("访客") 18print(user.name) # 访客 19print(User.is_valid_name("小明")) # True
guest() 是类方法,可以通过 cls 创建当前类的实例,因此常被用作「替代构造方法」。is_valid_name() 不需要读取实例或类的数据,只是一个和用户相关的检查函数,所以可以定义为静态方法。
guest()
is_valid_name()
除了 __str__(),还可以实现 __repr__() 和 __eq__()。前者主要用于调试时展示对象,后者用于定义两个实例如何比较:
__repr__()
__eq__()
01class User: 02 def __init__(self, name): 03 self.name = name 04 05 def __str__(self): 06 return self.name 07 08 def __repr__(self): 09 return f"User(name={self.name!r})" 10 11 def __eq__(self, other): 12 return isinstance(other, User) and self.name == other.name 13 14first = User("小明") 15second = User("小明") 16 17print(str(first)) # 小明 18print(repr(first)) # User(name='小明') 19print(first == second) # True
str() 更适合面向用户的内容,repr() 更适合调试。默认情况下,两个不同实例即使属性相同,使用 == 也不会被认为相等;实现 __eq__() 后,类可以定义自己的比较规则。is 判断的是不是同一个对象,不会调用 __eq__()。
str()
repr()
==
is
Python 没有像某些语言那样强制禁止访问的私有方法。下划线主要是给开发者的访问约定:
method()
_method()
__method()
__method__()
单个下划线最常见。它不会阻止访问,只是告诉调用方「这是类的内部实现,公开接口发生变化时不一定保持兼容」:
01class Account: 02 def __init__(self, owner): 03 self.owner = owner 04 self._balance = 0 05 06 def deposit(self, amount): 07 if not self._is_valid_amount(amount): 08 raise ValueError("存款金额必须大于 0") 09 10 self._balance += amount 11 12 def _is_valid_amount(self, amount): 13 return amount > 0 14 15account = Account("小明") 16account.deposit(100) 17print(account._balance) # 可以访问,但业务代码不应该依赖这个内部属性
deposit() 是对外提供的操作,_is_valid_amount() 只是它内部使用的辅助方法。外部代码技术上可以调用 _is_valid_amount(),但应该优先使用类提供的公共方法。
deposit()
_is_valid_amount()
两个连续的前置下划线会触发名称改写(name mangling)。例如,__cleanup() 会在类内部被改写为类似 _Session__cleanup,这样子类定义同名方法时,不容易意外覆盖父类的内部实现:
__cleanup()
_Session__cleanup
01class Session: 02 def __cleanup(self): 03 print("清理会话") 04 05 def close(self): 06 self.__cleanup() 07 08session = Session() 09session.close() # 清理会话 10# session.__cleanup() # AttributeError:原始名称不能直接访问
名称改写不是安全机制,也不能真正阻止访问。它主要用于减少子类和父类之间的命名冲突。最后要特别区分:__init__()、__str__() 两端都有下划线,它们是特殊方法,不是私有方法。
实例属性属于某一个对象,类属性则属于整个类。类属性可以被所有实例读取:
01class Article: 02 category = "Python" 03 04 def __init__(self, title): 05 self.title = title 06 07first = Article("变量") 08second = Article("函数") 09 10print(first.category) # Python 11print(second.category) # Python
如果实例没有自己的同名属性,Python 会继续到类上查找。因此,类属性适合保存所有实例共享的常量或默认配置:
1class Request: 2 default_timeout = 30 3 4 def __init__(self, path): 5 self.path = path 6 7request = Request("/users") 8print(request.default_timeout) 9print(Request.default_timeout)
不要把可变对象(例如列表、字典)作为类属性来保存每个实例自己的状态,否则所有实例可能会共享同一个对象:
1class BadPlaylist: 2 songs = [] 3 4first = BadPlaylist() 5second = BadPlaylist() 6first.songs.append("晴天") 7 8print(second.songs) # ['晴天'],两个实例共享同一个列表
正确做法是把可变属性放到 __init__() 中,让每个实例创建自己的列表:
01class Playlist: 02 def __init__(self): 03 self.songs = [] 04 05first = Playlist() 06second = Playlist() 07first.songs.append("晴天") 08 09print(first.songs) # ['晴天'] 10print(second.songs) # []
如果直接公开属性,外部代码可以写入任意值。@property 可以让一个方法以属性的方式被读取,并在赋值时加入校验:
@property
01class User: 02 def __init__(self, name): 03 self.name = name 04 05 @property 06 def name(self): 07 return self._name 08 09 @name.setter 10 def name(self, value): 11 value = value.strip() 12 if not value: 13 raise ValueError("用户名不能为空") 14 15 self._name = value 16 17user = User(" 小明 ") 18print(user.name) # 小明 19user.name = "小红"
调用方仍然使用 user.name,不需要写成 user.name()。只有定义 @property 而没有定义 setter 时,这个属性才是只读的。@property 适合把校验、格式转换和兼容旧接口的逻辑封装在类内部。
user.name
user.name()
类可以通过组合表达「一个对象使用另一个对象」。例如,一个聊天服务可以持有负责整理问题的格式化对象,在组装请求数据时调用它的方法:
01class MessageFormatter: 02 def __init__(self, prefix="问题:"): 03 self.prefix = prefix 04 05 def format(self, question): 06 return self.prefix + question.strip() 07 08class ChatService: 09 def __init__(self, formatter, model_name="deepseek-chat"): 10 self.formatter = formatter 11 self.model_name = model_name 12 13 def build_request(self, question): 14 return { 15 "model": self.model_name, 16 "messages": [ 17 {"role": "user", "content": self.formatter.format(question)}, 18 ], 19 } 20 21formatter = MessageFormatter() 22service = ChatService(formatter) 23request = service.build_request(" 请介绍一下 Python。 ") 24print(request)
在真实的 FastAPI 项目中,接口函数可以接收请求,再调用 ChatService 的方法;在 LangChain 项目中,服务类也可以持有模型实例、提示词和工具。这样,路由负责 HTTP,服务类负责业务,模型调用不会全部堆在接口函数里。
ChatService
如果一个类主要用于保存数据,可以使用标准库中的 dataclass。它会根据类型注解自动生成常用的 __init__()、__repr__() 和 __eq__():
dataclass
01from dataclasses import dataclass 02 03@dataclass 04class ChatRequest: 05 question: str 06 model: str = "deepseek-chat" 07 08request = ChatRequest("请介绍一下 Python。") 09print(request) 10print(request == ChatRequest("请介绍一下 Python。")) # True
dataclass 适合数据结构清晰、行为较少的对象,例如 FastAPI 的请求配置或 LangChain 的运行参数。如果一个类包含较多业务行为,仍然可以手写普通类和方法。
类之间还可以通过继承复用代码。子类会获得父类的方法和属性,也可以覆盖某个方法:
01class Message: 02 def __init__(self, content): 03 self.content = content 04 05 def render(self): 06 return self.content 07 08class SystemMessage(Message): 09 def render(self): 10 return f"[系统] {self.content}" 11 12message = SystemMessage("你是一名温和的助手。") 13print(message.render()) # [系统] 你是一名温和的助手。
子类需要复用父类的初始化逻辑时,可以调用 super():
super()
01class User: 02 def __init__(self, name): 03 self.name = name 04 05class Admin(User): 06 def __init__(self, name, level): 07 super().__init__(name) 08 self.level = level 09 10admin = Admin("小明", 2) 11print(admin.name) # 小明 12print(admin.level) # 2
继承适合表达明确的「是一种」关系,例如 Admin 是一种 User。如果两个对象只是互相协作,优先考虑组合,避免为了复用几行代码创建过深的继承层级。
Admin
可以使用 isinstance() 检查一个对象是否属于某个类,使用 issubclass() 检查两个类之间是否存在继承关系:
isinstance()
issubclass()
01class User: 02 pass 03 04class Admin(User): 05 pass 06 07admin = Admin() 08 09print(isinstance(admin, Admin)) # True 10print(isinstance(admin, User)) # True,子类实例也属于父类类型 11print(issubclass(Admin, User)) # True
type(admin) is Admin 只判断对象的直接类型,而 isinstance(admin, User) 还会考虑继承关系。业务代码需要兼容子类时,通常优先使用 isinstance()。
type(admin) is Admin
isinstance(admin, User)
本篇把前面的知识放进一个可修改的 Python 项目。main.py 只负责接收参数并调用实验函数,classes_demo.py 保存本篇的逻辑。默认接口不需要密钥,也不会调用外部模型。
main.py
classes_demo.py
001from dataclasses import asdict, dataclass 002 003class User: 004 def __init__(self, name: str): 005 self.name = name 006 007 @property 008 def name(self) -> str: 009 return self._name 010 011 @name.setter 012 def name(self, value: str) -> None: 013 value = value.strip() 014 if not value: 015 raise ValueError("用户名不能为空") 016 self._name = value 017 018 @classmethod 019 def guest(cls): 020 return cls("游客") 021 022 @staticmethod 023 def is_valid_name(name: str) -> bool: 024 return bool(name.strip()) 025 026 def __str__(self) -> str: 027 return self.name 028 029 def __repr__(self) -> str: 030 return f"User(name={self.name!r})" 031 032 def __eq__(self, other): 033 if not isinstance(other, User): 034 return NotImplemented 035 return self.name == other.name 036 037class Order: 038 def __init__(self, price: int, quantity: int): 039 self.price = price 040 self.quantity = quantity 041 042 def total(self) -> int: 043 return self.price * self.quantity 044 045 def summary(self) -> str: 046 return f"共 {self.quantity} 件,合计 {self.total()} 元" 047 048class MessageFormatter: 049 def __init__(self, prefix: str = "问题:"): 050 self.prefix = prefix 051 052 def format(self, question: str) -> str: 053 return self.prefix + question.strip() 054 055class ChatService: 056 def __init__(self, formatter: MessageFormatter, model_name: str = "example-model"): 057 self.formatter = formatter 058 self.model_name = model_name 059 060 def build_request(self, question: str) -> dict[str, object]: 061 return { 062 "model": self.model_name, 063 "messages": [{"role": "user", "content": self.formatter.format(question)}], 064 } 065 066@dataclass 067class ChatRequest: 068 question: str 069 model: str = "example-model" 070 071class Message: 072 def __init__(self, content: str): 073 self.content = content 074 075 def render(self) -> str: 076 return self.content 077 078class SystemMessage(Message): 079 def render(self) -> str: 080 return f"[系统] {self.content}" 081 082def playlist_report() -> dict[str, object]: 083 # 在每次实验里定义类,避免错误示例的共享列表跨请求累积。 084 class SharedPlaylist: 085 songs = [] 086 087 class Playlist: 088 def __init__(self): 089 self.songs = [] 090 091 shared_first, shared_second = SharedPlaylist(), SharedPlaylist() 092 shared_first.songs.append("晴天") 093 first, second = Playlist(), Playlist() 094 first.songs.append("晴天") 095 return { 096 "class_attribute": { 097 "first": shared_first.songs, 098 "second": shared_second.songs, 099 "same_object": shared_first.songs is shared_second.songs, 100 }, 101 "instance_attribute": { 102 "first": first.songs, 103 "second": second.songs, 104 "same_object": first.songs is second.songs, 105 }, 106 } 107 108def build_report(name: str, price: int, quantity: int) -> dict[str, object]: 109 user = User(name) 110 guest = User.guest() 111 order = Order(price, quantity) 112 formatter = MessageFormatter("问题:") 113 service = ChatService(formatter) 114 question = f"请向 {user.name} 介绍 Python 类。" 115 request = ChatRequest(question) 116 message = SystemMessage("你是一名温和的助手。") 117 print(order.summary()) 118 return { 119 "user": { 120 "name": user.name, 121 "guest": guest.name, 122 "valid_name": User.is_valid_name(name), 123 "str": str(user), "repr": repr(user), 124 "equal_value": user == User(name), 125 "same_instance": user is User(name), 126 }, 127 "order": {"price": price, "quantity": quantity, "total": order.total(), "summary": order.summary()}, 128 "playlists": playlist_report(), 129 "composition": { 130 "uses_injected_formatter": service.formatter is formatter, 131 "request": service.build_request(question), 132 }, 133 "dataclass": {"fields": asdict(request), "equal_value": request == ChatRequest(question)}, 134 "inheritance": { 135 "rendered": message.render(), 136 "is_message": isinstance(message, Message), 137 "is_subclass": issubclass(SystemMessage, Message), 138 }, 139 } 140
01from fastapi import FastAPI, HTTPException, Query 02 03from classes_demo import build_report 04 05app = FastAPI() 06 07@app.get("/classes") 08async def classes( 09 name: str = Query("小微", min_length=1, max_length=80), 10 price: int = Query(30, ge=0, le=1000000), 11 quantity: int = Query(2, ge=1, le=100), 12) -> dict[str, object]: 13 try: 14 return build_report(name, price, quantity) 15 except ValueError as error: 16 raise HTTPException(status_code=400, detail=str(error)) from error 17
01[project] 02name = "python-classes" 03version = "0.1.0" 04description = "Python 类" 05readme = "README.md" 06requires-python = ">=3.12" 07dependencies = [ 08 "fastapi[standard]==0.136.1; sys_platform != 'emscripten'", 09 "fastapi==0.136.1; sys_platform == 'emscripten'", 10 "pydantic==2.12.5", 11 "httpx==0.28.1", 12] 13 14[tool.uv] 15package = false 16
其余配置文件可在在线案例左侧的文件目录中查看,也会包含在下载包里。接口的输入有明确的长度、数量或数值范围,超出范围时 FastAPI 会返回 422。
422
打开在线案例,点击运行,等待环境就绪。案例预览默认使用 GET,地址是:
GET
1/classes?name=小微&price=30&quantity=2
默认参数得到订单总价 60。user.equal_value 为 true,而 user.same_instance 为 false:两个实例的数据相等,并不意味着它们是同一个对象。共享类属性中的两个播放列表都包含“晴天”,实例属性版本的第二个播放列表仍为空。
60
user.equal_value
true
user.same_instance
false
composition.uses_injected_formatter 为 true,说明 ChatService 实际使用传入的 MessageFormatter 对象。修改格式化器的前缀后重新运行,组装的消息内容也会变化;该实验只组装字典,不调用模型。
composition.uses_injected_formatter
MessageFormatter
数据类通过 asdict() 转换为字典后展示,响应不会把 Python 对象变成 JSON 中的对象引用。可以将 name 改为只含空格的值,观察 property 校验返回的 400;正常名字会被去掉两端空格。
asdict()
name
property
400
下载 ZIP 并解压,在项目目录执行:
1uv run fastapi dev main.py
然后打开 http://127.0.0.1:8000/docs,选择对应接口,填写和在线案例相同的参数发送请求。
http://127.0.0.1:8000/docs
本机使用 .python-version 指定的 Python 3.12,浏览器使用当前 Pyodide 的 Python 版本。在线案例通过 ASGITransport 执行 FastAPI,不监听本机端口,无需安装本机 Python。每次请求都会新建本次实验的状态,本篇的代码草稿、Git、日志和 Agent 对话也与其他文章分开保存。
.python-version
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 认识
类(class)是创建对象的一种模板。它把一组相关的数据和处理这些数据的函数放在一起,形成一个更完整的模型。
例如,一本书有标题、作者这些数据,也可以有介绍自己、修改标题这些行为。用类描述后,每一本具体的书都是一个对象:
Book是类,first_book和second_book是两个实例。它们使用同一套结构,但各自保存不同的标题和作者。类适合描述「有状态、有行为」的对象。如果只是临时组合几个字段,字典往往更直接;当数据和操作逐渐变多时,类可以让代码的职责更清晰。
2. 定义
使用
class定义类,类名通常采用大驼峰命名,例如Book、ChatSession。类体通过缩进表示:pass表示暂时没有实现任何内容。User()会创建一个User实例,调用类的过程也叫实例化。通常会在类中定义
__init__(),为实例准备初始数据:__init__()会在实例创建后自动调用。self代表当前实例,self.name和self.email是这个实例自己的属性。调用User("小明", ...)时,传入的参数会交给__init__(),不需要手动传self。很多教程会把
__init__()口语化地称为「构造函数」,但从 Python 的严格机制看,它是初始化方法。真正负责创建实例的是__new__()。调用User(...)时,可以把过程简化理解为:先由__new__()创建并返回实例,再由__init__()给这个实例填充初始数据。输出顺序是先执行
__new__(),再执行__init__()。__new__()接收类本身cls,必须返回一个实例;__init__()接收已经创建好的实例self,不需要返回实例。__new__()cls__init__()self如果
__new__()没有返回当前类的实例,Python 不会继续调用对应的__init__()。重写__new__()常见于继承str、tuple等不可变类型,或实现单例等特殊创建逻辑;普通业务类通常只需要编写__init__()。每个实例可以拥有不同的属性值,也可以在创建后增加属性:
不过,业务需要的属性最好在
__init__()中统一初始化。这样,其他代码只要看到类的定义,就能知道一个实例通常包含哪些数据。3. 方法
写在类中的函数叫作方法。实例方法的第一个参数通常是
self,通过它读取或修改当前实例:调用
counter.increase(4)时,Python 会自动把counter作为self传给方法。可以把它近似理解为Counter.increase(counter, 4),所以方法内部才能访问self.value。方法不仅可以读取属性,也可以返回计算结果。把和对象状态有关的操作放进方法,调用方就不需要了解内部实现:
如果希望
print(order)时显示更有意义的内容,可以实现__str__():以双下划线包围的
__init__、__str__等方法叫特殊方法。它们通常由 Python 在特定时机自动调用,不需要像普通方法那样直接使用。类中还可以定义类方法和静态方法。它们与实例方法的区别在于,自动接收的第一个参数不同:
self@classmethodcls@staticmethodguest()是类方法,可以通过cls创建当前类的实例,因此常被用作「替代构造方法」。is_valid_name()不需要读取实例或类的数据,只是一个和用户相关的检查函数,所以可以定义为静态方法。除了
__str__(),还可以实现__repr__()和__eq__()。前者主要用于调试时展示对象,后者用于定义两个实例如何比较:str()更适合面向用户的内容,repr()更适合调试。默认情况下,两个不同实例即使属性相同,使用==也不会被认为相等;实现__eq__()后,类可以定义自己的比较规则。is判断的是不是同一个对象,不会调用__eq__()。4. 私有
Python 没有像某些语言那样强制禁止访问的私有方法。下划线主要是给开发者的访问约定:
method()_method()__method()__method__()单个下划线最常见。它不会阻止访问,只是告诉调用方「这是类的内部实现,公开接口发生变化时不一定保持兼容」:
deposit()是对外提供的操作,_is_valid_amount()只是它内部使用的辅助方法。外部代码技术上可以调用_is_valid_amount(),但应该优先使用类提供的公共方法。两个连续的前置下划线会触发名称改写(name mangling)。例如,
__cleanup()会在类内部被改写为类似_Session__cleanup,这样子类定义同名方法时,不容易意外覆盖父类的内部实现:名称改写不是安全机制,也不能真正阻止访问。它主要用于减少子类和父类之间的命名冲突。最后要特别区分:
__init__()、__str__()两端都有下划线,它们是特殊方法,不是私有方法。5. 属性
实例属性属于某一个对象,类属性则属于整个类。类属性可以被所有实例读取:
如果实例没有自己的同名属性,Python 会继续到类上查找。因此,类属性适合保存所有实例共享的常量或默认配置:
不要把可变对象(例如列表、字典)作为类属性来保存每个实例自己的状态,否则所有实例可能会共享同一个对象:
正确做法是把可变属性放到
__init__()中,让每个实例创建自己的列表:如果直接公开属性,外部代码可以写入任意值。
@property可以让一个方法以属性的方式被读取,并在赋值时加入校验:调用方仍然使用
user.name,不需要写成user.name()。只有定义@property而没有定义 setter 时,这个属性才是只读的。@property适合把校验、格式转换和兼容旧接口的逻辑封装在类内部。6. 组合
类可以通过组合表达「一个对象使用另一个对象」。例如,一个聊天服务可以持有负责整理问题的格式化对象,在组装请求数据时调用它的方法:
在真实的 FastAPI 项目中,接口函数可以接收请求,再调用
ChatService的方法;在 LangChain 项目中,服务类也可以持有模型实例、提示词和工具。这样,路由负责 HTTP,服务类负责业务,模型调用不会全部堆在接口函数里。如果一个类主要用于保存数据,可以使用标准库中的
dataclass。它会根据类型注解自动生成常用的__init__()、__repr__()和__eq__():dataclass适合数据结构清晰、行为较少的对象,例如 FastAPI 的请求配置或 LangChain 的运行参数。如果一个类包含较多业务行为,仍然可以手写普通类和方法。类之间还可以通过继承复用代码。子类会获得父类的方法和属性,也可以覆盖某个方法:
子类需要复用父类的初始化逻辑时,可以调用
super():继承适合表达明确的「是一种」关系,例如
Admin是一种User。如果两个对象只是互相协作,优先考虑组合,避免为了复用几行代码创建过深的继承层级。可以使用
isinstance()检查一个对象是否属于某个类,使用issubclass()检查两个类之间是否存在继承关系:type(admin) is Admin只判断对象的直接类型,而isinstance(admin, User)还会考虑继承关系。业务代码需要兼容子类时,通常优先使用isinstance()。7. 在线类与对象实验
本篇把前面的知识放进一个可修改的 Python 项目。
main.py只负责接收参数并调用实验函数,classes_demo.py保存本篇的逻辑。默认接口不需要密钥,也不会调用外部模型。7.1 完整实验代码
7.2 接口与配置
其余配置文件可在在线案例左侧的文件目录中查看,也会包含在下载包里。接口的输入有明确的长度、数量或数值范围,超出范围时 FastAPI 会返回
422。7.3 运行和观察
打开在线案例,点击运行,等待环境就绪。案例预览默认使用
GET,地址是:默认参数得到订单总价
60。user.equal_value为true,而user.same_instance为false:两个实例的数据相等,并不意味着它们是同一个对象。共享类属性中的两个播放列表都包含“晴天”,实例属性版本的第二个播放列表仍为空。composition.uses_injected_formatter为true,说明ChatService实际使用传入的MessageFormatter对象。修改格式化器的前缀后重新运行,组装的消息内容也会变化;该实验只组装字典,不调用模型。数据类通过
asdict()转换为字典后展示,响应不会把 Python 对象变成 JSON 中的对象引用。可以将name改为只含空格的值,观察property校验返回的400;正常名字会被去掉两端空格。7.4 本机运行
下载 ZIP 并解压,在项目目录执行:
然后打开
http://127.0.0.1:8000/docs,选择对应接口,填写和在线案例相同的参数发送请求。本机使用
.python-version指定的 Python 3.12,浏览器使用当前 Pyodide 的 Python 版本。在线案例通过 ASGITransport 执行 FastAPI,不监听本机端口,无需安装本机 Python。每次请求都会新建本次实验的状态,本篇的代码草稿、Git、日志和 Agent 对话也与其他文章分开保存。