Python函数封装与参数校验最佳实践

1. 函数封装与参数校验的必要性

在大语言模型应用开发中，函数封装和参数校验是构建稳健系统的基石。想象一下，如果你每次调用API都要重复编写相同的请求代码，或者因为参数错误导致整个程序崩溃，那将是多么低效和危险。这正是我们需要系统化处理这些问题的重要原因。

函数封装的核心价值在于：

• 代码复用：避免重复造轮子，相同功能只需编写一次
• 逻辑隔离：将复杂系统分解为可管理的模块
• 错误隔离：单个函数出错不会影响整个系统
• 团队协作：明确定义的接口让多人协作更顺畅

参数校验则像是给函数加了一道安全门：

• 防御性编程：防止无效或恶意输入导致系统异常
• 自文档化：通过类型提示和校验规则明确函数预期
• 早期错误检测：在调用前就发现问题，而非运行时崩溃

2. 函数封装的最佳实践

2.1 设计高内聚的函数

一个好的函数应该像瑞士军刀中的单个工具 - 专注做好一件事。以调用大语言模型API为例：

python复制def call_llm_api(prompt: str, model: str, api_key: str) -> dict:
    """调用大语言模型API获取响应
    
    Args:
        prompt: 用户输入的提示词
        model: 要使用的模型名称
        api_key: API访问密钥
        
    Returns:
        API的JSON响应或None(失败时)
    """
    # 实现细节...

关键设计原则：

1. 单一职责：一个函数只做一件事
2. 明确接口：输入输出类型清晰
3. 适当粒度：不过大也不过小
4. 无副作用：尽量避免修改外部状态

2.2 参数设计的艺术

参数设计直接影响函数易用性：

python复制# 不好的设计 - 参数过多且无序
def process_data(name, age, address, phone, email, is_vip, ...):

# 好的设计 - 相关参数分组
class UserInfo:
    name: str
    age: int
    contact: ContactInfo

def process_data(user: UserInfo, is_vip: bool):

经验法则：

• 超过5个参数考虑使用对象封装
• 布尔参数尽量不超过2个
• 相关参数组合成数据结构

3. 使用Pydantic进行专业级参数校验

3.1 Pydantic基础用法

Pydantic通过Python类型注解提供运行时数据验证：

python复制from pydantic import BaseModel, Field

class LLMRequest(BaseModel):
    prompt: str = Field(..., min_length=1, max_length=1000)
    model: str = Field("gpt-3.5-turbo", regex=r"^gpt-\d\.\d-turbo$")
    temperature: float = Field(0.7, ge=0, le=1)
    max_tokens: int = Field(100, gt=0)

字段类型说明：

• ... 表示必填字段
• min_length/max_length 限制字符串长度
• ge/le 数值范围限制(ge=大于等于, le=小于等于)
• regex 正则表达式验证

3.2 高级验证技巧

自定义验证器提供更灵活的控制：

python复制from pydantic import validator

class UserInput(BaseModel):
    username: str
    password: str
    
    @validator('password')
    def password_complexity(cls, v):
        if len(v) < 8:
            raise ValueError("密码至少8位")
        if not any(c.isupper() for c in v):
            raise ValueError("密码需包含大写字母")
        return v

验证器可以：

• 访问其他字段值
• 进行跨字段验证
• 修改返回值(如自动trim字符串)

3.3 性能优化技巧

Pydantic默认会在每次实例化时进行完整验证，对于高频调用场景可以：

python复制from pydantic import validate_arguments

@validate_arguments
def frequent_call(text: str, count: int):
    # 自动缓存验证结果
    pass

注意：验证缓存基于参数哈希，确保相同输入跳过重复验证

4. 异常处理的工程实践

4.1 异常分类与处理策略

大语言模型应用中的常见异常：