Python API 设计最佳实践：构建优雅的接口

1. 背景与动机

良好的 API 设计是软件工程的核心技能。本文总结 Python API 设计的最佳实践，帮助开发者构建易用、可维护的接口。

2. 设计原则

2.1 简洁性

# 好的设计
class FileProcessor:
    def process(self, filepath: str) -> dict:
        """处理文件并返回结果"""
        pass

# 避免过度设计
class FileProcessor:
    def __init__(self, config):
        self.config = config
    
    def validate(self, filepath):
        pass
    
    def open(self, filepath):
        pass
    
    def process(self, filepath):
        pass

2.2 一致性

# 命名一致性
class DataLoader:
    def load_from_file(self, path): pass
    def load_from_database(self, conn): pass
    def load_from_api(self, url): pass

# 参数顺序一致性
def create_user(name, email, age): pass
def update_user(user_id, name, email, age): pass

3. 类型提示

from typing import List, Dict, Optional, Union
from dataclasses import dataclass

@dataclass
class User:
    id: int
    name: str
    email: str
    age: Optional[int] = None

def get_users(
    filters: Dict[str, Union[str, int]],
    limit: int = 100
) -> List[User]:
    """获取用户列表
    
    Args:
        filters: 过滤条件
        limit: 返回数量限制
    
    Returns:
        用户对象列表
    """
    pass

4. 错误处理

class APIError(Exception):
    """API 基础异常"""
    def __init__(self, message, code=None):
        super().__init__(message)
        self.code = code

class ValidationError(APIError):
    """参数验证错误"""
    pass

class NotFoundError(APIError):
    """资源不存在"""
    pass

# 使用示例
def get_user(user_id: int) -> User:
    if user_id <= 0:
        raise ValidationError("Invalid user_id", code=400)
    
    user = db.query(user_id)
    if not user:
        raise NotFoundError(f"User {user_id} not found", code=404)
    
    return user

5. 装饰器模式

import functools
import time
from typing import Callable

def retry(max_attempts: int = 3, delay: float = 1.0):
    """重试装饰器"""
    def decorator(func: Callable) -> Callable:
        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(max_attempts):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    if attempt == max_attempts - 1:
                        raise
                    time.sleep(delay)
            return None
        return wrapper
    return decorator

@retry(max_attempts=3)
def fetch_data(url: str) -> dict:
    pass

6. 上下文管理器

from contextlib import contextmanager

@contextmanager
def database_connection():
    """数据库连接上下文管理器"""
    conn = create_connection()
    try:
        yield conn
    finally:
        conn.close()

# 使用
with database_connection() as conn:
    conn.execute("SELECT * FROM users")

7. 结论

优秀的 API 设计需要遵循简洁、一致、可预测的原则，配合类型提示、完善的文档和合理的错误处理，可以显著提升代码质量和开发效率。

转载自CSDN-专业IT技术社区

原文链接：https://blog.csdn.net/lady_mumu/article/details/159729417