Pylance 的类型检查不够用，因其仅做静态推断，无法校验运行时业务规则（如邮箱格式、枚举值）、第三方库无注解时推断为 Any、JSON/HTTP 动态数据无法覆盖。
为什么直接用 Pylance 的类型检查不够用
Pylance 能识别 def func(x: int) -> str: 这类标注，但对运行时传入的实际值（比如 func("abc")）只做静态推断，不执行逻辑校验。它无法判断“这个字符串是否符合业务规则”——例如邮箱格式、ID 长度、枚举值范围等。这类校验必须在函数入口处动态拦截，而 Pylance 不介入运行时。
常见错误现象包括：类型标注写对了，但传入空字符串、超长 ID 或非法状态码，直到下游抛 ValueError 或数据库报错才暴露问题。
- 静态检查覆盖不了业务约束（如
status in ("pending", "done")） - 第三方库函数没类型注解，Pylance 推断为
Any，完全跳过检查 - 运行时数据来自 JSON/HTTP 请求，类型在解析后才确定，静态分析无法触达
用装饰器 + 插件联动实现入参拦截
核心思路是：在函数定义处加一个轻量装饰器（如 @validate_args），VSCode 插件扫描到该装饰器后，在编辑器侧提示缺失校验项，并在保存时调用本地 Python 环境运行简易校验逻辑（非完整执行，仅模拟参数路径）。
示例代码：
from typing import Union <p>def validate_args(func): def wrapper(*args, **kwargs):</p><h1>实际运行时校验逻辑（可对接 Pydantic / 自定义规则）</h1><pre class="brush:php;toolbar:false;"> return func(*args, **kwargs) return wrapper
@validate_args def create_user(name: str, age: int, email: str) -> dict: ...
插件需识别 @validate_args 并检查以下三点：
- 每个参数是否在函数体开头有对应校验语句（如
assert len(email) > 5或if "@" not in email: raise ValueError） - 是否导入了校验依赖（如
import re或from pydantic import BaseModel） - 若使用 Pydantic 模型，是否定义了
class UserCreate(BaseModel)且函数签名用了该模型
VSCode 插件如何定位和提示校验缺失
插件本质是 Language Server，需解析 AST 而非正则匹配。关键点：
- 不依赖
python.analysis.typeCheckingMode，而是监听textDocument/didSave后触发自定义诊断（Diagnostic） - 对带
@validate_args的函数，扫描其 AST 中的ast.If、ast.Assert、ast.Raise节点，检查是否覆盖全部参数 - 提示信息要具体：
Missing validation for parameter 'email' (line 12)，而非笼统的“请校验参数” - 支持快速修复：光标悬停时提供插入
if not re.match(r".+@.+", email): raise ValueError("Invalid email")的选项
注意：不要在插件里嵌入完整校验逻辑（如实际调用 re.match），只做语法存在性检查。真实校验留给运行时或测试阶段。
容易被忽略的兼容性陷阱
很多团队踩坑在“装饰器链”和“类型擦除”上：
- 如果函数同时用了
@lru_cache和@validate_args，顺序必须是@validate_args在外层，否则 AST 扫描会看到缓存包装后的函数，找不到原始参数名 - 使用
functools.wraps时，若未正确传递__signature__，插件解析 AST 得到的参数名可能是*args而非真实名 - Pydantic v2 的
@validate_call装饰器返回的是新函数对象，插件需适配其 AST 结构（比手写装饰器多一层ast.Call嵌套） - 插件配置必须限定作用域：只对
**/*.py生效，且跳过tests/和migrations/目录，避免误报
真正的难点不在“怎么标”，而在“标了之后，编辑器能否稳定识别并给出可操作反馈”——这取决于 AST 解析的鲁棒性和装饰器约定的统一程度。
