Agent Skills
返回列表
💻

Python 开发规范

开发编程 更新于 2026.08.30

将以下提示词粘贴到你的 AI 对话框中:

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/siviter-xyz-dot-agent-python。

技能介绍

何时需要这套约束

团队里的 Python 服务越写越长时,常见问题不是语法错误,而是类型注解风格不统一、__init__.py 被当成 barrel export、环境变量散落在各模块里导致测试难以 mock,以及改业务代码时没人对照 pytest 目录结构补测试。本技能不是语法速查表,而是一套可执行的工程约定,覆盖从命名、文档字符串到架构分层与提交流程。

技能如何约束你的实现

设计与代码风格方面强调 DRY、KISS、SOLID;有状态时优先类,可组合处用 Protocol 定义接口而非深层继承;模块保持单一职责,类依赖通过构造函数或方法注入。

类型注解要求用内置泛型(dict、list)、str | None 替代旧式 Optional,并在含注解文件顶部加入 from __future__ import annotations。

架构与数据约定每包用 environment.py 集中读取环境变量(如 api_key() 对应 API_KEY);数据模型统一走 Pydantic v2,用于 API schema、配置与 DTO。

测试侧要求目录镜像 src/,方法以 test_ 开头,套件命名为 TestFoo;执行 AAA 模式,工具链偏向 pytest、pytest-mock 与 conftest.py。实现改动前需通过类型检查与测试,相关逻辑与测试尽量同次原子提交。

边界与注意点

技能侧重「怎么写、怎么测、怎么组织模块」,不替代具体业务领域设计。附带的 references/uv-scripts.md 与 references/uv-monorepo.md 只针对 uv / Hatch 单体仓库场景;若项目仍大量用 unittest 或 Pydantic v1,需要先与团队对齐迁移范围再机械套用全文。

使用场景

  • 在现有 FastAPI 服务里新增模块时,需要按单模块单服务与 Protocol 接口拆分依赖注入。
  • 重构遗留代码时,要把 `typing.List` 和 `Optional` 统一成内置泛型与 `str | None` 写法。
  • 为微服务封装第三方 API 时,用 Pydantic v2 定义请求响应 schema 并补镜像 src 的单元测试。
  • 多人协作提交前,按 AAA 用 pytest 补用例并确认类型检查与测试在同一原子提交里通过。

适合人员

  • 维护内部 Python 微服务的后端工程师,希望新 PR 默认带类型注解与 pytest 目录约定。
  • 负责单体仓库拆模块的技术负责人,需要 environment.py 集中读配置以便测试 mock。
  • 从 Pydantic v1 升级的库维护者,要对齐 v2 模型与序列化写法并收紧提交前检查。
  • 在 uv 管理的多包仓库里写脚本的同学,需要对照 references 里的 monorepo 与脚本约定。