Python接口参数规范与可维护性指南

Python接口参数设计应遵循命名清晰、关键字参数优先、类型标注+默认值+文档字符串协同、复杂参数封装为dataclass或Pydantic模型四大原则，以提升可读性、健壮性与可维护性。

Python接口参数设计直接影响代码可读性、协作效率和长期维护成本。规范的参数结构能让调用方快速理解意图，减少错误，也便于后续扩展和类型检查。

参数命名清晰，避免缩写和歧义

使用完整、语义明确的英文单词命名参数，如user_id优于uid，is_active优于active_flag。避免拼音、中文拼音首字母或无上下文的单字母（如a、x）。

• ✅ 推荐：def send_notification(to_email: str, template_name: str, context: dict)
• ❌ 避免：def send_noti(e: str, t: str, c: dict)

优先使用关键字参数（keyword-only），限制位置参数数量

将非必需参数设为关键字参数（用*分隔），强制调用时显式传参名，提升可读性和健壮性。位置参数建议不超过3个，核心必填项可保留位置传入。

• ✅ 推荐：def create_order(user_id, product_id, *, quantity=1, is_urgent=False, timeout_s=30)
• ❌ 避免：def create_order(user_id, product_id, quantity, is_urgent, timeout_s)（易错序、难维护）

类型标注+默认值+文档字符串三者协同

所有参数必须标注类型（PEP 484），可选参数提供合理默认值，并在docstring中说明业务含义、取值范围及边界行为。类型标注不仅支持IDE提示，也为mypy等工具校验提供依据。

• ✅ 示例：
  def fetch_user_profile(user_id: int, include_private: bool = False) -> dict:
    """获取用户公开资料；若include_private=True，需校验权限。
    :param user_id: 用户唯一整数ID，必须大于0
    :param include_private: 是否返回隐私字段，默认False
    :raises ValueError: 当user_id ≤ 0时抛出"""

复杂参数封装为数据类（dataclass）或Pydantic模型

当接口接收多个逻辑相关的参数（如分页、过滤、排序配置），应聚合为专用结构体，而非平铺5–6个独立参数。dataclass适合内部服务，Pydantic适合API入口（自动校验+序列化）。

• ✅ 示例（Pydantic）：
  class ListQuery(BaseModel):
    page: int = 1
    size: int = 20
    status_in: list[str] | None = None
    sort_by: Literal["created_at", "name"] = "created_at"
  def list_items(query: ListQuery) -> list[Item]
• ❌ 避免：def list_items(page=1, size=20, status_in=None, sort_by="created_at")