Python 反模式审查清单在 Python 开发中规避 14 类常见错误的实战指南agents24 插件市场【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本篇技术指南以 GitHub推荐项目精选 agents24 仓库中 python-anti-patterns 技能文档 为骨架系统梳理 Python 代码中从基础设施、架构、错误处理到测试环节的 14 类高频反模式。读者将获得一份可直接在代码评审、调试、重构场景中逐项打勾的检查清单并掌握每一类反模式对应的修复方案集中化重试、类型化配置、DTO、仓储模式、上下文管理器、异步原生库、严格类型检查等同时结合仓库内同族的正向模式技能与源码实现理解其底层原理。这份清单应该在什么时候使用python-anti-patterns是 Python 开发插件中一个反向清单型技能它的定位非常明确告诉开发者什么不该写。其 frontmatter 中声明了适用范围——在评审 Python 代码、最终确定实现方案之前、或调试疑似由已知坏实践引发的问题时作为对照清单使用。该技能在文档中列出的典型使用时机包括合并代码前的代码评审Reviewing code before merge排查诡异问题Debugging mysterious issues教学或学习 Python 最佳实践建立团队编码标准重构遗留代码文档末尾特别强调了一条边界本技能聚焦于要避免什么。如果需要正向的模式与架构指导应转向同目录下的 python-design-patterns 技能涵盖 KISS、单一职责、组合优于继承、三法则等原则。两者一防一建配合使用才能形成完整的代码质量闭环。基础设施层反模式分散的超时/重试逻辑Scattered Timeout/Retry Logic最典型的表现是timeout参数、try/except Timeout分支在代码库里到处复制粘贴每个调用方各写一份一旦需要调整超时时间或告警策略就得全局搜索逐个修改。# BAD: Timeout logic duplicated everywhere def fetch_user(user_id): try: return requests.get(url, timeout30) except Timeout: logger.warning(Timeout fetching user) return None def fetch_orders(user_id): try: return requests.get(url, timeout30) except Timeout: logger.warning(Timeout fetching orders) return None修复思路集中化到装饰器或客户端包装层。# GOOD: Centralized retry logic retry(stopstop_after_attempt(3), waitwait_exponential()) def http_get(url: str) - Response: return requests.get(url, timeout30)这一修复在仓库中有完整的正向支撑。同插件的 python-resilience 技能 给出了生产级重试的完整写法包括用tenacity的retry_if_exception_type白名单只重试瞬时错误ConnectionError、TimeoutError、httpx.ConnectTimeout等、用wait_exponential_jitter(initial1, max30)做指数退避加抖动、用stop_after_attempt(5) | stop_after_delay(60)同时限制次数与总时长以及用before_sleep_log记录每次重试。它还明确列出了绝不能重试的错误类型ValueError/TypeError属于代码 bug、认证失败凭据不会自动变有效、除 429 外的 4xx 客户端错误永久性错误。将超时/重试收敛到单一装饰器之后这些策略只需维护一处。双重重试Double Retry与分散重试相对的另一个极端是多层重试叠加应用层配了重试底层客户端 SDK 自己也配了重试导致一次失败实际触发 N×M 次请求放大了故障时对下游服务的压力。# BAD: Retrying at multiple layers retry(max_attempts3) # Application retry def call_service(): return client.request() # Client also has retry configured!修复原则只在单一层做重试并且必须了解你所用基础设施自身的重试行为。从 python-resilience 技能 的最佳实践第 6 条可以看到同样的要求——用装饰器让重试逻辑与业务逻辑分离正因如此重试应该被显式地放在一个层次而不是隐式地散落在多层里。硬编码配置Hard-Coded Configuration把数据库地址、API Key 等直接写死在源码里是安全与运维的双重隐患密钥会随代码进入版本库环境切换dev/staging/prod必须改代码。# BAD: Secrets and config in code DB_HOST prod-db.example.com API_KEY sk-12345 def connect(): return psycopg.connect(fhost{DB_HOST}...)修复思路环境变量 类型化设置。# GOOD from pydantic_settings import BaseSettings class Settings(BaseSettings): db_host: str Field(aliasDB_HOST) api_key: str Field(aliasAPI_KEY) settings Settings()这一点在同插件的 python-configuration 技能 中被系统化展开其核心理念与本反模式清单完全对应所有环境相关值URL、密钥、特性开关来自环境变量而非代码在启动时把配置解析校验成类型化对象而非散落各处os.getenv缺失的必填配置应在应用启动时立刻报错退出fail fast。文档还给出了补全后的完整Settings类包括用Field(alias...)映射环境变量、用model_config {env_file: .env}支持本地.env文件、对必填密钥不设默认值、以及通过命名空间前缀DB_*、REDIS_*、AUTH_*、FEATURE_*让env | grep DB_式的排查变得可用。注意.env文件要加入.gitignore绝不能提交进仓库。架构层反模式暴露内部类型Exposed Internal Types把 ORM 模型、protobuf 消息等内部表示直接作为 API 返回类型暴露给调用方会带来耦合问题内部字段变更会穿透 API 边界序列化时还可能泄露不该暴露的字段如密码哈希。# BAD: Leaking ORM model to API app.get(/users/{id}) def get_user(id: str) - UserModel: # SQLAlchemy model return db.query(UserModel).get(id)修复思路使用 DTO / 响应模型。# GOOD app.get(/users/{id}) def get_user(id: str) - UserResponse: user db.query(UserModel).get(id) return UserResponse.from_orm(user)在仓库的 python-design-patterns 技能 中这条反模式被视为评审 PR 时结构性问题如紧耦合、内部类型泄漏的典型示例其 Troubleshooting 部分还给出了配套的分层约束——Service 层不得反向 import Handler/API 层应引入共享的 types/models 层保持 API → Service → Repository 的依赖方向。此外 python-scaffold 命令 生成的 FastAPI 工程结构里models/与schemas/目录分离正是从目录层面强制内部模型与API 模式隔离。I/O 与业务逻辑混合Mixed I/O and Business Logic在业务函数里直接内嵌 SQL、直接操作网络或文件会让业务逻辑难以单元测试每次测试都要连真实数据库也让 SQL 细节与折扣规则等高价值逻辑纠缠在一起。# BAD: SQL embedded in business logic def calculate_discount(user_id: str) - float: user db.query(SELECT * FROM users WHERE id ?, user_id) orders db.query(SELECT * FROM orders WHERE user_id ?, user_id) # Business logic mixed with data access if len(orders) 10: return 0.15 return 0.0修复思路仓储模式让业务逻辑保持纯函数。# GOOD def calculate_discount(user: User, orders: list[Order]) - float: # Pure business logic, easily testable if len(orders) 10: return 0.15 return 0.0改造后calculate_discount只依赖传入的数据对象不触碰任何 I/O测试时直接构造User与Order列表即可断言。这一可测试性收益正是 python-design-patterns 技能 中强调的因 I/O 与业务逻辑纠缠而难以测试的代码库的解法其最佳实践第 9 条每一层独立测试也依赖这种分层。纯函数化后结合 python-testing-patterns 技能 的 AAAArrange-Act-Assert结构可以轻松为折扣计算等规则写全量边界用例。错误处理反模式裸异常处理Bare Exception Handlingexcept Exception: pass是静默失败的代名词异常被吞掉后bug 被永久隐藏线上问题只能靠玄学排查。# BAD: Swallowing all exceptions try: process() except Exception: pass # Silent failure - bugs hidden forever修复思路捕获具体异常类型记录日志或做相应处理。# GOOD try: process() except ConnectionError as e: logger.warning(Connection failed, will retry, errorstr(e)) raise except ValueError as e: logger.error(Invalid input, errorstr(e)) raise BadRequestError(str(e))python-error-handling 技能 对这条给出了完整的异常类型映射表可作为选择具体异常的依据失败类型异常示例输入无效ValueError参数值错误类型错误TypeError期望 str 得到 int元素缺失KeyError字典键不存在操作失败RuntimeError服务不可用超时TimeoutError操作耗时过长文件不存在FileNotFoundError路径不存在权限拒绝PermissionError访问被禁止其最佳实践还补充了两条与本反模式直接相关的要求错误消息要包含发生了什么、为什么、如何修复的上下文链式异常要用raise ... from e保留完整的调试轨迹。忽略部分失败Ignored Partial Failures批处理任务中如果某个元素失败就中断整个批次会导致整体任务重复执行、成功项被浪费。更隐蔽的问题是调用方只看到失败看不到哪些成功。# BAD: Stops on first error def process_batch(items): results [] for item in items: result process(item) # Raises on error - batch aborted results.append(result) return results修复思路同时记录成功与失败返回批量结果对象。# GOOD def process_batch(items) - BatchResult: succeeded {} failed {} for idx, item in enumerate(items): try: succeeded[idx] process(item) except Exception as e: failed[idx] e return BatchResult(succeeded, failed)部分失败是 python-error-handling 技能 的四大核心概念之一Fail Fast、Meaningful Exceptions、Partial Failures、Preserve Context其立场与清单完全一致批处理中不要让单个失败中止一切要分开追踪成功与失败。同时注意这里逐项try/except捕获的是元素级错误与裸异常处理并不矛盾——关键在于异常被显式归类记录并继续推进而不是被吞掉。缺少输入校验Missing Input Validation未在边界校验的输入会一路穿透到代码深处才崩溃报错位置远离真正的问题源头排障成本极高。# BAD: No validation def create_user(data: dict): return User(**data) # Crashes deep in code on bad input修复思路在 API 边界尽早校验。# GOOD def create_user(data: dict) - User: validated CreateUserInput.model_validate(data) return User.from_input(validated)这条反模式的修复与Fail Fast原则一脉相承。python-error-handling 技能 用三个正向模式把它展开一是早期输入校验——在边界对所有参数做范围与必填检查后再进入处理流程二是尽早转换为领域类型——把字符串解析为枚举/领域对象非法输入在入口即被拦截三是用 Pydantic 做复杂校验——BaseModelField(min_length..., ge..., le...)field_validator提供结构化错误e.errors()并自动处理ValidationError。文档中的CreateUserInput示例含邮箱格式校验、姓名归一化可以直接照搬到本项目或任何 FastAPI/Pydantic 服务中。资源管理反模式资源未关闭Unclosed Resources文件句柄、数据库连接、网络 socket 等资源若不保证释放长时间运行的服务会耗尽文件描述符或连接池。手动open后return的风险在于读取中途抛异常时f.close()永远不会执行。# BAD: File never closed def read_file(path): f open(path) return f.read() # What if this raises?修复思路使用上下文管理器。# GOOD def read_file(path): with open(path) as f: return f.read()python-resource-management 技能 将这一思路系统化其四大核心概念与修复方案一一对应with语句保证异常时资源也被自动释放同步用__enter__/__exit__、异步用__aenter__/__aexit____exit__无论是否发生异常都会执行__exit__返回True抑制异常、返回False/None传播异常。文档进一步给出了完整进阶写法类式上下文管理器DatabaseConnection实现__enter__建立连接、__exit__无条件close()并保留try/finally手动管理作为兜底异步上下文管理器AsyncDatabasePool用async with self._pool.acquire()管理连接池装饰器简化contextmanager/asynccontextmanager配合yieldfinally实现计时块、事务BEGIN/COMMIT/ROLLBACK等场景无条件清理FileProcessor在__exit__中无论成败都关闭主文件并尽力删除临时文件。异步中阻塞Blocking in Async在async函数里调用time.sleep或同步requests.get会阻塞整个事件循环——并发场景下所有协程一起卡住吞吐量断崖式下跌。# BAD: Blocks the entire event loop async def fetch_data(): time.sleep(1) # Blocks everything! response requests.get(url) # Also blocks!修复思路使用异步原生库。# GOOD async def fetch_data(): await asyncio.sleep(1) async with httpx.AsyncClient() as client: response await client.get(url)同插件的 async-python-patterns 技能 即专门围绕此类问题展开python-proAgent 的能力清单也把Advanced async/await patterns with asyncio, aiohttp, and trio列为专长。实践中的通用检查项是time.sleep→asyncio.sleeprequests→httpx.AsyncClient/aiohttp同步数据库驱动 →asyncpg/ SQLAlchemy 2.0 async 模式CPU 密集任务则交给concurrent.futures或进程池避免占用事件循环。类型安全反模式缺少类型注解Missing Type Hints无类型的 Python 函数把错误发现推迟到运行时也让 IDE 无法提供补全与跳转。# BAD: No types def process(data): return data[value] * 2修复思路为所有公共函数添加注解。# GOOD def process(data: dict[str, int]) - int: return data[value] * 2python-type-safety 技能 将注解定位为可被工具自动验证的强制性文档并给出两条配套要求在 CI 中跑mypy --strict或pyright存量项目可用 per-module override 增量开启对公共 API 一律注解——函数参数、返回值、方法、类属性。它还提供了类型收窄type narrowing的范例get_user(id) - User | None后通过if user is None: raise ...分支让类型检查器在后续代码中确信user是User。未参数化的集合类型Untyped Collections裸list、dict丢失了元素类型信息调用方拿到后无法推断内容检查器也无从校验。# BAD: Generic list without type parameter def get_users() - list: ...修复思路为集合标注类型参数。# GOOD def get_users() - list[User]: ...python-type-safety 技能 还给出了泛型进阶用TypeVarGeneric实现Result[T, E]这样的成功/失败容器让parse_config(path) - Result[Config, ConfigError]这类返回值的类型信息在调用链中完整保留并建议用T | NonePython 3.10 现代联合语法取代Optional[T]、尽量缩小Any的使用范围。仓库的 python-scaffold 命令 在pyproject.toml的 ruff 配置里target-version py311说明该插件默认面向支持现代联合语法的 Python 3.11。测试反模式只测快乐路径Only Testing Happy Paths只覆盖输入合法 → 成功路径的测试会让异常处理代码处于零覆盖状态恰恰是最容易出 bug 的部分得不到验证。# BAD: Only tests success case def test_create_user(): user service.create_user(valid_data) assert user.id is not None修复思路覆盖错误条件与边界情况。# GOOD def test_create_user_success(): user service.create_user(valid_data) assert user.id is not None def test_create_user_invalid_email(): with pytest.raises(ValueError, matchInvalid email): service.create_user(invalid_email_data) def test_create_user_duplicate_email(): service.create_user(valid_data) with pytest.raises(ConflictError): service.create_user(valid_data)这一模式与 python-testing-patterns 技能 的命名规范test_unit_scenario_expected_outcome完全吻合也与 python-error-handling 技能 的最佳实践第 10 条测试错误路径验证异常被正确抛出互为印证。该技能还提供了断言风格之外的实测手段用Mock的side_effect列表模拟前两次失败、第三次成功验证重试次数call_count 3用pytest.mark.skipif/xfail管理平台差异与已知缺陷用freezegun冻结时间测试令牌过期逻辑。过度 MockOver-Mocking把仓库、缓存、日志、指标全部 Mock 成空壳后测试验证的只是 Mock 之间的假交互真实行为完全失控——重构后测试照常通过但功能已经坏掉。# BAD: Mocking everything def test_user_service(): mock_repo Mock() mock_cache Mock() mock_logger Mock() mock_metrics Mock() # Test doesnt verify real behavior修复思路关键路径用集成测试只 Mock 外部服务。python-testing-patterns 技能 用测试组织目录给出了落地方式tests/test_unit/放单元测试、tests/test_integration/放组件交互测试、tests/test_e2e/放端到端流程测试通过conftest.py共享 fixture。同时该技能建议Mock 仅限外部依赖——像重试逻辑这类核心行为应当用真实对象加可控side_effect来验证而不是把一切替换成Mock()。快速审查清单在代码定稿前逐项核对以下清单源自原文档全部打勾即可放行没有分散的超时/重试逻辑已集中化没有双重重试应用层 基础设施层没有硬编码配置或密钥没有暴露内部类型ORM 模型、protobuf没有混合 I/O 与业务逻辑没有裸except Exception: pass批处理中没有被忽略的部分失败没有缺失的输入校验没有未关闭的资源已使用上下文管理器异步代码中没有阻塞调用所有公共函数都有类型注解集合类型都有类型参数错误路径已测试边界情况已覆盖常见修复速查表反模式修复方案分散的重试逻辑集中化装饰器硬编码配置环境变量 pydantic-settings暴露 ORM 模型DTO / 响应模式混合 I/O 逻辑仓储模式裸 except捕获具体异常批次遇错即停返回含成功/失败的BatchResult缺少校验边界用 Pydantic 校验资源未关闭上下文管理器异步中阻塞异步原生库缺少类型公共 API 全部注解只测快乐路径补测错误与边界在仓库中继续深入本清单属于减法型技能与其配套的加法型技能共同构成了完整的 Python 质量体系读者可按需翻阅python-design-patternsKISS、单一职责、组合优于继承、三法则等正向设计原则python-error-handlingFail Fast、异常映射表、Pydantic 校验、部分失败处理python-resiliencetenacity 重试、指数退避、抖动、熔断python-configurationpydantic-settings 类型化配置、fail fast 启动校验python-resource-management上下文管理器与无条件清理python-type-safety类型注解、泛型、Protocol、严格检查python-testing-patternspytest、fixture、Mock、覆盖率async-python-patterns异步并发与阻塞规避python-pro Agent 与 python-scaffold 命令前者提供覆盖本清单全部主题的专家角色后者生成自带类型安全、测试与配置基础设施的工程骨架从源头避免反模式生根。把这份清单固化为团队评审模板或 Agent 审查提示词就能让规避反模式从个人经验沉淀为可重复执行的工程纪律。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Python 反模式审查清单：在 Python 开发中规避 14 类常见错误的实战指南（agents24 插件市场）
Python 反模式审查清单在 Python 开发中规避 14 类常见错误的实战指南agents24 插件市场【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本篇技术指南以 GitHub推荐项目精选 agents24 仓库中 python-anti-patterns 技能文档 为骨架系统梳理 Python 代码中从基础设施、架构、错误处理到测试环节的 14 类高频反模式。读者将获得一份可直接在代码评审、调试、重构场景中逐项打勾的检查清单并掌握每一类反模式对应的修复方案集中化重试、类型化配置、DTO、仓储模式、上下文管理器、异步原生库、严格类型检查等同时结合仓库内同族的正向模式技能与源码实现理解其底层原理。这份清单应该在什么时候使用python-anti-patterns是 Python 开发插件中一个反向清单型技能它的定位非常明确告诉开发者什么不该写。其 frontmatter 中声明了适用范围——在评审 Python 代码、最终确定实现方案之前、或调试疑似由已知坏实践引发的问题时作为对照清单使用。该技能在文档中列出的典型使用时机包括合并代码前的代码评审Reviewing code before merge排查诡异问题Debugging mysterious issues教学或学习 Python 最佳实践建立团队编码标准重构遗留代码文档末尾特别强调了一条边界本技能聚焦于要避免什么。如果需要正向的模式与架构指导应转向同目录下的 python-design-patterns 技能涵盖 KISS、单一职责、组合优于继承、三法则等原则。两者一防一建配合使用才能形成完整的代码质量闭环。基础设施层反模式分散的超时/重试逻辑Scattered Timeout/Retry Logic最典型的表现是timeout参数、try/except Timeout分支在代码库里到处复制粘贴每个调用方各写一份一旦需要调整超时时间或告警策略就得全局搜索逐个修改。# BAD: Timeout logic duplicated everywhere def fetch_user(user_id): try: return requests.get(url, timeout30) except Timeout: logger.warning(Timeout fetching user) return None def fetch_orders(user_id): try: return requests.get(url, timeout30) except Timeout: logger.warning(Timeout fetching orders) return None修复思路集中化到装饰器或客户端包装层。# GOOD: Centralized retry logic retry(stopstop_after_attempt(3), waitwait_exponential()) def http_get(url: str) - Response: return requests.get(url, timeout30)这一修复在仓库中有完整的正向支撑。同插件的 python-resilience 技能 给出了生产级重试的完整写法包括用tenacity的retry_if_exception_type白名单只重试瞬时错误ConnectionError、TimeoutError、httpx.ConnectTimeout等、用wait_exponential_jitter(initial1, max30)做指数退避加抖动、用stop_after_attempt(5) | stop_after_delay(60)同时限制次数与总时长以及用before_sleep_log记录每次重试。它还明确列出了绝不能重试的错误类型ValueError/TypeError属于代码 bug、认证失败凭据不会自动变有效、除 429 外的 4xx 客户端错误永久性错误。将超时/重试收敛到单一装饰器之后这些策略只需维护一处。双重重试Double Retry与分散重试相对的另一个极端是多层重试叠加应用层配了重试底层客户端 SDK 自己也配了重试导致一次失败实际触发 N×M 次请求放大了故障时对下游服务的压力。# BAD: Retrying at multiple layers retry(max_attempts3) # Application retry def call_service(): return client.request() # Client also has retry configured!修复原则只在单一层做重试并且必须了解你所用基础设施自身的重试行为。从 python-resilience 技能 的最佳实践第 6 条可以看到同样的要求——用装饰器让重试逻辑与业务逻辑分离正因如此重试应该被显式地放在一个层次而不是隐式地散落在多层里。硬编码配置Hard-Coded Configuration把数据库地址、API Key 等直接写死在源码里是安全与运维的双重隐患密钥会随代码进入版本库环境切换dev/staging/prod必须改代码。# BAD: Secrets and config in code DB_HOST prod-db.example.com API_KEY sk-12345 def connect(): return psycopg.connect(fhost{DB_HOST}...)修复思路环境变量 类型化设置。# GOOD from pydantic_settings import BaseSettings class Settings(BaseSettings): db_host: str Field(aliasDB_HOST) api_key: str Field(aliasAPI_KEY) settings Settings()这一点在同插件的 python-configuration 技能 中被系统化展开其核心理念与本反模式清单完全对应所有环境相关值URL、密钥、特性开关来自环境变量而非代码在启动时把配置解析校验成类型化对象而非散落各处os.getenv缺失的必填配置应在应用启动时立刻报错退出fail fast。文档还给出了补全后的完整Settings类包括用Field(alias...)映射环境变量、用model_config {env_file: .env}支持本地.env文件、对必填密钥不设默认值、以及通过命名空间前缀DB_*、REDIS_*、AUTH_*、FEATURE_*让env | grep DB_式的排查变得可用。注意.env文件要加入.gitignore绝不能提交进仓库。架构层反模式暴露内部类型Exposed Internal Types把 ORM 模型、protobuf 消息等内部表示直接作为 API 返回类型暴露给调用方会带来耦合问题内部字段变更会穿透 API 边界序列化时还可能泄露不该暴露的字段如密码哈希。# BAD: Leaking ORM model to API app.get(/users/{id}) def get_user(id: str) - UserModel: # SQLAlchemy model return db.query(UserModel).get(id)修复思路使用 DTO / 响应模型。# GOOD app.get(/users/{id}) def get_user(id: str) - UserResponse: user db.query(UserModel).get(id) return UserResponse.from_orm(user)在仓库的 python-design-patterns 技能 中这条反模式被视为评审 PR 时结构性问题如紧耦合、内部类型泄漏的典型示例其 Troubleshooting 部分还给出了配套的分层约束——Service 层不得反向 import Handler/API 层应引入共享的 types/models 层保持 API → Service → Repository 的依赖方向。此外 python-scaffold 命令 生成的 FastAPI 工程结构里models/与schemas/目录分离正是从目录层面强制内部模型与API 模式隔离。I/O 与业务逻辑混合Mixed I/O and Business Logic在业务函数里直接内嵌 SQL、直接操作网络或文件会让业务逻辑难以单元测试每次测试都要连真实数据库也让 SQL 细节与折扣规则等高价值逻辑纠缠在一起。# BAD: SQL embedded in business logic def calculate_discount(user_id: str) - float: user db.query(SELECT * FROM users WHERE id ?, user_id) orders db.query(SELECT * FROM orders WHERE user_id ?, user_id) # Business logic mixed with data access if len(orders) 10: return 0.15 return 0.0修复思路仓储模式让业务逻辑保持纯函数。# GOOD def calculate_discount(user: User, orders: list[Order]) - float: # Pure business logic, easily testable if len(orders) 10: return 0.15 return 0.0改造后calculate_discount只依赖传入的数据对象不触碰任何 I/O测试时直接构造User与Order列表即可断言。这一可测试性收益正是 python-design-patterns 技能 中强调的因 I/O 与业务逻辑纠缠而难以测试的代码库的解法其最佳实践第 9 条每一层独立测试也依赖这种分层。纯函数化后结合 python-testing-patterns 技能 的 AAAArrange-Act-Assert结构可以轻松为折扣计算等规则写全量边界用例。错误处理反模式裸异常处理Bare Exception Handlingexcept Exception: pass是静默失败的代名词异常被吞掉后bug 被永久隐藏线上问题只能靠玄学排查。# BAD: Swallowing all exceptions try: process() except Exception: pass # Silent failure - bugs hidden forever修复思路捕获具体异常类型记录日志或做相应处理。# GOOD try: process() except ConnectionError as e: logger.warning(Connection failed, will retry, errorstr(e)) raise except ValueError as e: logger.error(Invalid input, errorstr(e)) raise BadRequestError(str(e))python-error-handling 技能 对这条给出了完整的异常类型映射表可作为选择具体异常的依据失败类型异常示例输入无效ValueError参数值错误类型错误TypeError期望 str 得到 int元素缺失KeyError字典键不存在操作失败RuntimeError服务不可用超时TimeoutError操作耗时过长文件不存在FileNotFoundError路径不存在权限拒绝PermissionError访问被禁止其最佳实践还补充了两条与本反模式直接相关的要求错误消息要包含发生了什么、为什么、如何修复的上下文链式异常要用raise ... from e保留完整的调试轨迹。忽略部分失败Ignored Partial Failures批处理任务中如果某个元素失败就中断整个批次会导致整体任务重复执行、成功项被浪费。更隐蔽的问题是调用方只看到失败看不到哪些成功。# BAD: Stops on first error def process_batch(items): results [] for item in items: result process(item) # Raises on error - batch aborted results.append(result) return results修复思路同时记录成功与失败返回批量结果对象。# GOOD def process_batch(items) - BatchResult: succeeded {} failed {} for idx, item in enumerate(items): try: succeeded[idx] process(item) except Exception as e: failed[idx] e return BatchResult(succeeded, failed)部分失败是 python-error-handling 技能 的四大核心概念之一Fail Fast、Meaningful Exceptions、Partial Failures、Preserve Context其立场与清单完全一致批处理中不要让单个失败中止一切要分开追踪成功与失败。同时注意这里逐项try/except捕获的是元素级错误与裸异常处理并不矛盾——关键在于异常被显式归类记录并继续推进而不是被吞掉。缺少输入校验Missing Input Validation未在边界校验的输入会一路穿透到代码深处才崩溃报错位置远离真正的问题源头排障成本极高。# BAD: No validation def create_user(data: dict): return User(**data) # Crashes deep in code on bad input修复思路在 API 边界尽早校验。# GOOD def create_user(data: dict) - User: validated CreateUserInput.model_validate(data) return User.from_input(validated)这条反模式的修复与Fail Fast原则一脉相承。python-error-handling 技能 用三个正向模式把它展开一是早期输入校验——在边界对所有参数做范围与必填检查后再进入处理流程二是尽早转换为领域类型——把字符串解析为枚举/领域对象非法输入在入口即被拦截三是用 Pydantic 做复杂校验——BaseModelField(min_length..., ge..., le...)field_validator提供结构化错误e.errors()并自动处理ValidationError。文档中的CreateUserInput示例含邮箱格式校验、姓名归一化可以直接照搬到本项目或任何 FastAPI/Pydantic 服务中。资源管理反模式资源未关闭Unclosed Resources文件句柄、数据库连接、网络 socket 等资源若不保证释放长时间运行的服务会耗尽文件描述符或连接池。手动open后return的风险在于读取中途抛异常时f.close()永远不会执行。# BAD: File never closed def read_file(path): f open(path) return f.read() # What if this raises?修复思路使用上下文管理器。# GOOD def read_file(path): with open(path) as f: return f.read()python-resource-management 技能 将这一思路系统化其四大核心概念与修复方案一一对应with语句保证异常时资源也被自动释放同步用__enter__/__exit__、异步用__aenter__/__aexit____exit__无论是否发生异常都会执行__exit__返回True抑制异常、返回False/None传播异常。文档进一步给出了完整进阶写法类式上下文管理器DatabaseConnection实现__enter__建立连接、__exit__无条件close()并保留try/finally手动管理作为兜底异步上下文管理器AsyncDatabasePool用async with self._pool.acquire()管理连接池装饰器简化contextmanager/asynccontextmanager配合yieldfinally实现计时块、事务BEGIN/COMMIT/ROLLBACK等场景无条件清理FileProcessor在__exit__中无论成败都关闭主文件并尽力删除临时文件。异步中阻塞Blocking in Async在async函数里调用time.sleep或同步requests.get会阻塞整个事件循环——并发场景下所有协程一起卡住吞吐量断崖式下跌。# BAD: Blocks the entire event loop async def fetch_data(): time.sleep(1) # Blocks everything! response requests.get(url) # Also blocks!修复思路使用异步原生库。# GOOD async def fetch_data(): await asyncio.sleep(1) async with httpx.AsyncClient() as client: response await client.get(url)同插件的 async-python-patterns 技能 即专门围绕此类问题展开python-proAgent 的能力清单也把Advanced async/await patterns with asyncio, aiohttp, and trio列为专长。实践中的通用检查项是time.sleep→asyncio.sleeprequests→httpx.AsyncClient/aiohttp同步数据库驱动 →asyncpg/ SQLAlchemy 2.0 async 模式CPU 密集任务则交给concurrent.futures或进程池避免占用事件循环。类型安全反模式缺少类型注解Missing Type Hints无类型的 Python 函数把错误发现推迟到运行时也让 IDE 无法提供补全与跳转。# BAD: No types def process(data): return data[value] * 2修复思路为所有公共函数添加注解。# GOOD def process(data: dict[str, int]) - int: return data[value] * 2python-type-safety 技能 将注解定位为可被工具自动验证的强制性文档并给出两条配套要求在 CI 中跑mypy --strict或pyright存量项目可用 per-module override 增量开启对公共 API 一律注解——函数参数、返回值、方法、类属性。它还提供了类型收窄type narrowing的范例get_user(id) - User | None后通过if user is None: raise ...分支让类型检查器在后续代码中确信user是User。未参数化的集合类型Untyped Collections裸list、dict丢失了元素类型信息调用方拿到后无法推断内容检查器也无从校验。# BAD: Generic list without type parameter def get_users() - list: ...修复思路为集合标注类型参数。# GOOD def get_users() - list[User]: ...python-type-safety 技能 还给出了泛型进阶用TypeVarGeneric实现Result[T, E]这样的成功/失败容器让parse_config(path) - Result[Config, ConfigError]这类返回值的类型信息在调用链中完整保留并建议用T | NonePython 3.10 现代联合语法取代Optional[T]、尽量缩小Any的使用范围。仓库的 python-scaffold 命令 在pyproject.toml的 ruff 配置里target-version py311说明该插件默认面向支持现代联合语法的 Python 3.11。测试反模式只测快乐路径Only Testing Happy Paths只覆盖输入合法 → 成功路径的测试会让异常处理代码处于零覆盖状态恰恰是最容易出 bug 的部分得不到验证。# BAD: Only tests success case def test_create_user(): user service.create_user(valid_data) assert user.id is not None修复思路覆盖错误条件与边界情况。# GOOD def test_create_user_success(): user service.create_user(valid_data) assert user.id is not None def test_create_user_invalid_email(): with pytest.raises(ValueError, matchInvalid email): service.create_user(invalid_email_data) def test_create_user_duplicate_email(): service.create_user(valid_data) with pytest.raises(ConflictError): service.create_user(valid_data)这一模式与 python-testing-patterns 技能 的命名规范test_unit_scenario_expected_outcome完全吻合也与 python-error-handling 技能 的最佳实践第 10 条测试错误路径验证异常被正确抛出互为印证。该技能还提供了断言风格之外的实测手段用Mock的side_effect列表模拟前两次失败、第三次成功验证重试次数call_count 3用pytest.mark.skipif/xfail管理平台差异与已知缺陷用freezegun冻结时间测试令牌过期逻辑。过度 MockOver-Mocking把仓库、缓存、日志、指标全部 Mock 成空壳后测试验证的只是 Mock 之间的假交互真实行为完全失控——重构后测试照常通过但功能已经坏掉。# BAD: Mocking everything def test_user_service(): mock_repo Mock() mock_cache Mock() mock_logger Mock() mock_metrics Mock() # Test doesnt verify real behavior修复思路关键路径用集成测试只 Mock 外部服务。python-testing-patterns 技能 用测试组织目录给出了落地方式tests/test_unit/放单元测试、tests/test_integration/放组件交互测试、tests/test_e2e/放端到端流程测试通过conftest.py共享 fixture。同时该技能建议Mock 仅限外部依赖——像重试逻辑这类核心行为应当用真实对象加可控side_effect来验证而不是把一切替换成Mock()。快速审查清单在代码定稿前逐项核对以下清单源自原文档全部打勾即可放行没有分散的超时/重试逻辑已集中化没有双重重试应用层 基础设施层没有硬编码配置或密钥没有暴露内部类型ORM 模型、protobuf没有混合 I/O 与业务逻辑没有裸except Exception: pass批处理中没有被忽略的部分失败没有缺失的输入校验没有未关闭的资源已使用上下文管理器异步代码中没有阻塞调用所有公共函数都有类型注解集合类型都有类型参数错误路径已测试边界情况已覆盖常见修复速查表反模式修复方案分散的重试逻辑集中化装饰器硬编码配置环境变量 pydantic-settings暴露 ORM 模型DTO / 响应模式混合 I/O 逻辑仓储模式裸 except捕获具体异常批次遇错即停返回含成功/失败的BatchResult缺少校验边界用 Pydantic 校验资源未关闭上下文管理器异步中阻塞异步原生库缺少类型公共 API 全部注解只测快乐路径补测错误与边界在仓库中继续深入本清单属于减法型技能与其配套的加法型技能共同构成了完整的 Python 质量体系读者可按需翻阅python-design-patternsKISS、单一职责、组合优于继承、三法则等正向设计原则python-error-handlingFail Fast、异常映射表、Pydantic 校验、部分失败处理python-resiliencetenacity 重试、指数退避、抖动、熔断python-configurationpydantic-settings 类型化配置、fail fast 启动校验python-resource-management上下文管理器与无条件清理python-type-safety类型注解、泛型、Protocol、严格检查python-testing-patternspytest、fixture、Mock、覆盖率async-python-patterns异步并发与阻塞规避python-pro Agent 与 python-scaffold 命令前者提供覆盖本清单全部主题的专家角色后者生成自带类型安全、测试与配置基础设施的工程骨架从源头避免反模式生根。把这份清单固化为团队评审模板或 Agent 审查提示词就能让规避反模式从个人经验沉淀为可重复执行的工程纪律。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考