处理应用配置是每个后端开发者都避不开的活。传统的做法是定义一个config.py，里面大写的常量满天飞，或者用一个多层嵌套的字典，运行时靠字符串键去取，IDE给不了任何补全提示，键名打错了只能到线上报错才发现。后来有了dataclass和pydantic，我们可以把配置建模成结构化的类，让类型检查器提前揪出错误。但之前版本的Python在写泛型配置类时还是有些啰嗦，比如你得从typing里手动导入Generic和TypeVar，然后在类后面跟一长串[T]。
Python 3.12带来了PEP 695定义的紧凑型类型参数语法，可以用一种更自然的方式声明泛型。这篇文章就把这个新语法用在实际场景里——配合pydantic和dataclass，构建一个能从YAML/JSON里自动校验并加载配置的工具，让类型安全从模型定义一直延伸到运行时。
老语法有多难受
在开始用新语法之前，先回忆一下过去是怎么写泛型配置类的。假设我们有一个通用的分页配置，里面的page_size既可能是整数，也可能在某些环境下是字符串（比如从环境变量读取）。我们想把这个“分页配置”做成一个通用模板，允许调用方指定page_size的类型。
用Python 3.11之前的写法：
from typing import Generic, TypeVar
from pydantic import BaseModel
T = TypeVar('T')
class PaginationConfig(BaseModel, Generic[T]):
page: int = 1
page_size: T
# 使用时
int_config = PaginationConfig[int](page_size=20)
str_config = PaginationConfig[str](page_size='20')这里需要显式声明一个TypeVar，然后在类定义时同时继承BaseModel和Generic[T]，实例化时再通过方括号传入具体类型。逻辑没问题，但声明和使用的分离让代码阅读起来不太连贯，特别是当泛型参数多了以后，TypeVar的定义会和类定义离得很远。
PEP 695的新写法
Python 3.12允许直接在类名后面用[T]来声明类型参数，不再需要预先定义TypeVar。上面的例子可以改成：
from pydantic import BaseModel
class PaginationConfig[T](BaseModel):
page: int = 1
page_size: T
# 一样的用法
int_config = PaginationConfig[int](page_size=20)
str_config = PaginationConfig[str](page_size='20')干净了很多。T的作用域限定在这个类内部，不需要在文件顶部额外声明。如果有多个类型参数，直接在方括号里用逗号分隔，比如class KeyValuePair[K, V](BaseModel):。这种写法让泛型类看起来更像内置容器（如list[int]），阅读体验统一了。
函数也可以用类似的语法。写一个通用的配置读取函数，根据传入的类型自动解析：
def load_config[T](path: str, model: type[T]) -> T:
import json
with open(path) as f:
data = json.load(f)
return model(**data)这个函数的签名一眼就能看懂：我接收一个路径和一个类型，返回这个类型的实例。调用时load_config[AppConfig](...)，类型参数写在函数名后面，感觉就像在调用一个专门生成AppConfig的工厂。
设计一个多层配置结构
现在来动真格的。假设我们做一个微服务的配置中心，配置分为三层：应用基础配置、数据库连接配置、以及一组外部API的配置。数据库又分主库和只读副本，外部API则是多个同构的服务。
先定义数据库配置。主库和只读库的结构完全一样，所以适合用泛型来区分角色，但字段相同。这里我们不用泛型去区分，而是直接定义一个DatabaseConfig模型，在更高层级的配置里通过多个实例来区分：
from pydantic import BaseModel, Field, AnyUrl
class DatabaseConfig(BaseModel):
host: str = "localhost"
port: int = 3306
user: str
password: str
database: str
pool_size: int = Field(default=10, ge=1, le=100)
接下来是外部API的配置。每个API有自己的base_url和timeout，我们用泛型来承载不同API的特定参数。比如短信API需要一个sign_name，而支付API需要一个merchant_id。可以定义一个基类ApiConfig[T]，让T表示“额外参数”的类型：
class ApiConfig[T](BaseModel):
base_url: AnyUrl
timeout: int = 30
retry: int = 3
extra: T
然后定义具体的额外参数模型：
class SmsExtra(BaseModel):
sign_name: str
template_id: str
class PaymentExtra(BaseModel):
merchant_id: str
notify_url: AnyUrl
这样我们就可以写出ApiConfig[SmsExtra]和ApiConfig[PaymentExtra]，两个配置的共同部分在泛型基类里，差异部分通过extra字段承载。类型检查器会知道sms_config.extra.sign_name是合法的，而payment_config.extra.sign_name直接标红。
组合成应用根配置
最外层的根配置把所有子配置组合起来。这里用Pydantic的BaseSettings来支持从环境变量覆盖，但核心结构依然清晰：
from pydantic_settings import BaseSettings
class AppConfig(BaseSettings):
app_name: str = "my-service"
debug: bool = False
database: DatabaseConfig
read_replica: DatabaseConfig
sms_api: ApiConfig[SmsExtra]
payment_api: ApiConfig[PaymentExtra]
class Config:
env_nested_delimiter = '__'
注意sms_api和payment_api的类型声明用了具体的类型参数，这让整个配置树在IDE里拥有完整的自动补全。你输入config.sms_api.extra.之后，IDE会直接提示sign_name和template_id，不需要手动查阅文档。
从YAML文件加载并校验
假设我们有一个config.yaml文件：
app_name: order-service
debug: true
database:
host: 10.0.1.10
port: 3306
user: admin
password: secret
database: orders
pool_size: 20
read_replica:
host: 10.0.1.11
port: 3306
user: reader
password: read123
database: orders
pool_size: 5
sms_api:
base_url: https://sms.example.com/api
timeout: 10
retry: 2
extra:
sign_name: 我的应用
template_id: SMS_12345
payment_api:
base_url: https://pay.example.com/api
timeout: 15
extra:
merchant_id: M10086
notify_url: https://myservice.com/notify加载逻辑用一个函数搞定，利用前面定义的泛型load_config：
import yaml
from pathlib import Path
def load_yaml_config[T](path: Path, model: type[T]) -> T:
with open(path) as f:
data = yaml.safe_load(f)
return model(**data)
config = load_yaml_config(Path("config.yaml"), AppConfig)
print(config.app_name)
print(config.sms_api.extra.sign_name)
print(config.payment_api.extra.merchant_id)
如果YAML文件里漏写了database.password，Pydantic会在构造AppConfig时直接抛出ValidationError，明确指出哪个字段缺失、期望什么类型。这些校验在应用启动阶段就完成了，不会让残缺的配置流到业务代码里。
运行时类型安全：动态选择API配置
有时候配置本身也会根据运行环境动态变化。比如我们可以用环境变量控制启用哪些外部API，然后在代码里根据配置类型做分发。因为每个API配置的泛型参数已经固定，我们可以直接安全地访问extra里的特定字段。
def send_notification(config: AppConfig, phone: str, message: str):
# 类型检查器知道sms_api.extra是SmsExtra
print(f"使用模板{config.sms_api.extra.template_id}发送短信")
# 实际的SDK调用...
def create_payment(config: AppConfig, order_id: str, amount: float):
print(f"商户号{config.payment_api.extra.merchant_id}发起支付")
# 调用支付网关...
如果未来新增一种API类型，比如邮件推送，我们只需要定义EmailExtra，然后在AppConfig里加上email_api: ApiConfig[EmailExtra]。所有用到这个配置的地方都会获得完善的类型提示，不用担心字段名拼写错误。
Python 3.12类型参数的更多应用
除了在Pydantic模型中使用，PEP 695的紧凑语法也可以让普通的dataclass变得简洁。比如定义一个通用的响应包装类：
from dataclasses import dataclass
@dataclass
class ApiResponse[T]:
code: int
message: str
data: T
# 用户信息响应
user_resp: ApiResponse[dict] = ...
# 列表响应
list_resp: ApiResponse[list[str]] = ...
在3.11之前要实现同样的效果，你得from typing import Generic, TypeVar，然后T = TypeVar('T')，再class ApiResponse(Generic[T]):。现在直接class ApiResponse[T]:，代码量减少的同时可读性明显增加。
还有一个实用的场景是结合collections.abc定义自己的容器类型。比如一个“有名称的列表”：
class NamedList[T](list[T]):
def __init__(self, name: str, items: list[T]):
super().__init__(items)
self.name = name
现在你可以写NamedList[int]("ids", [1,2,3])，而且迭代出来的元素类型检查器能推断为int。这在处理复杂的数据结构时能省掉大量的# type: ignore注释。
注意事项：版本兼容与新语法边界
PEP 695是Python 3.12引入的，如果你的运行环境还在3.11甚至更早，这些代码会直接报语法错误。不过类型参数语法在运行时并不会产生额外开销，它只是一种声明方式，class Foo[T]:等价于3.11的class Foo(Generic[T]):加上自动生成的__class_getitem__。如果你需要向后兼容，可以暂时保留from __future__ import annotations配合旧的Generic写法，然后等生产环境全面升级到3.12后再迁移。
另外，目前mypy和pyright对PEP 695的支持已经基本完善，但部分边缘情况（比如类型参数与多重继承的交互）可能还存在检查盲区。写代码时最好用最新的类型检查工具版本，并开启严格模式。
总结：从配置入手，感受新语法的利落
配置管理看起来是个小话题，但它正好能体现类型参数语法的优势：不用一堆顶层的TypeVar声明，泛型类可以像内置类型一样自然地写出来，结合Pydantic的运行时校验能力，从文件到内存的整条链路都被类型保护覆盖了。
Python的类型系统还在快速进化，PEP 695只是其中一步。接下来还有PEP 696（TypeVar默认值）、PEP 698（override装饰器）等提案正在推进。但仅就目前而言，3.12的这个新语法已经能让日常的类型标注清爽不少。如果你正在升级Python版本，不妨从配置模块开始，把那些泛型类改成新的写法，感受一下没有Generic和TypeVar的代码是什么模样。
