萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python 裝飾器實戰:參數合法性驗證器的設計與實現

動機:橫切關注點分離

參數驗證是典型的橫切關注點:業務邏輯函數不應混雜大量 if not isinstance(...) 判斷。裝飾器將驗證邏輯剝離,保持業務代碼純粹。

設計目標

  • 支持位置參數、關鍵字參數、*args/**kwargs 驗證
  • 支持類型、可空、多類型、自定義驗證函數
  • 聲明式語法:@validParam(int, name=str)
  • 異常信息清晰,指明參數名、期望類型、實際值

核心實現

# validator.py
# -*- coding: UTF-8 -*-
from functools import wraps
import inspect

class ValidationError(TypeError):
    """參數驗證失敗異常"""
    pass

def _check_type(value, expected, param_name):
    """核心類型檢查邏輯"""
    # 支持類型元組:(int, float)
    if isinstance(expected, tuple):
        if not isinstance(value, expected):
            raise ValidationError(f"參數 '{param_name}' 期望類型 {expected}, 實際 {type(value).__name__}")
        return

    # 特殊標記:nullOk 允許 None
    if expected is nullOk:
        return  # None 合法,任意類型也合法(由調用者決定)

    # 普通類型檢查
    if not isinstance(value, expected):
        raise ValidationError(f"參數 '{param_name}' 期望類型 {expected.__name__}, 實際 {type(value).__name__}: {value!r}")

# 標記對象
class _NullOk: pass
nullOk = _NullOk()

class _MultiType:
    def __init__(self, *types):
        self.types = types
    def __instancecheck__(self, instance):
        return isinstance(instance, self.types)

def multiType(*types):
    """支持多類型:@validParam(x=multiType(int, float))"""
    return _MultiType(*types)

def validParam(*type_args, **type_kwargs):
    """
    參數驗證裝飾器
    @validParam(int, str, name=str, age=int)
    @validParam(*args=int, **kwargs=str)
    """
    def decorator(func):
        sig = inspect.signature(func)
        params = list(sig.parameters.values())

        @wraps(func)
        def wrapper(*args, **kwargs):
            bound = sig.bind(*args, **kwargs)
            bound.apply_defaults()

            # 1. 位置參數類型映射
            pos_iter = iter(type_args)
            # 2. 關鍵字參數類型映射
            kw_map = type_kwargs

            for param in params:
                pname = param.name
                pkind = param.kind
                expected = None

                if pkind in (param.POSITIONAL_ONLY, param.POSITIONAL_OR_KEYWORD):
                    # 位置參數:按順序消費 type_args
                    try:
                        expected = next(pos_iter)
                    except StopIteration:
                        pass  # 無聲明則不驗證
                elif pkind == param.VAR_POSITIONAL:
                    # *args:驗證每個元素
                    expected = ('*', type_args[0]) if type_args else None
                elif pkind == param.KEYWORD_ONLY or pkind == param.POSITIONAL_OR_KEYWORD:
                    # 關鍵字參數:按名查找
                    expected = kw_map.get(pname)
                elif pkind == param.VAR_KEYWORD:
                    # **kwargs:驗證每個值
                    expected = ('**', type_kwargs.get('**', None))

                if expected is None:
                    continue

                value = bound.arguments[pname]

                if isinstance(expected, tuple) and expected[0] in ('*', '**'):
                    # 容器類型驗證
                    container_type = expected[1]
                    if container_type is None:
                        continue
                    for i, v in enumerate(value):
                        try:
                            _check_type(v, container_type, f"{pname}[{i}]")
                        except ValidationError as e:
                            raise ValidationError(f"{func.__name__}: {e}")
                else:
                    _check_type(value, expected, pname)

            return func(*args, **kwargs)
        return wrapper
    return decorator

使用示例

from validator import validParam, nullOk, multiType

# 基礎類型驗證
@validParam(int, str)
def greet(age, name):
    return f"{name} is {age} years old"

# 指定參數名驗證
@validParam(name=str, age=int)
def greet2(age, name):
    return f"{name} is {age}"

# 允許 None
@validParam(nullOk, int)
def foo(opt_str, num):
    pass

# 多類型
@validParam(multiType(int, float))
def calc(num):
    return num * 2

# *args 驗證
@validParam(*args=int)
def sum_all(*numbers):
    return sum(numbers)

# **kwargs 驗證
@validParam(**kwargs=str)
def concat(**parts):
    return ''.join(parts.values())

# 測試
print(greet(25, "Alice"))      # OK
print(greet("25", "Alice"))    # ValidationError: 參數 'age' 期望類型 int...
print(foo(None, 10))           # OK
print(foo("not none", 10))     # OK (nullOk 允許任意)
print(calc(3.14))              # OK
print(sum_all(1, 2, 3))        # 6
print(concat(a="x", b="y"))    # "xy"

進階擴展方向

  • 值範圍驗證:@validParam(age=Range(0, 150))
  • 正則匹配:@validParam(email=Regex(r'...'))
  • 自定義驗證函數:@validParam(id=Validator(lambda x: x>0))
  • 異常處理集成:Web 框架中統一捕獲 ValidationError 返回 400 響應。

總結

基於 inspect.Signature 的參數綁定機制,結合靈活的類型聲明系統,可構建強大且易用的參數驗證裝飾器。該模式將「驗證什麼」與「如何驗證」分離,業務代碼保持清爽,驗證邏輯集中維護,是 Python 元編程實踐的經典案例。

copyright © 萬盛學電腦網 all rights reserved