python-engineering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Engineering

Python工程实践

Production-grade patterns drawn from (not requiring) exemplar projects—FastAPI, Poetry, HTTPX, Celery, Black—as reference. Apply the patterns with any stack.

This skill is structured per the skill-creator: essentials and navigation in SKILL.md; detailed patterns in

references/

, loaded only when needed (progressive disclosure).

这些生产级模式参考了（但不强制依赖）标杆项目——FastAPI、Poetry、HTTPX、Celery、Black——你可以在任何技术栈中应用这些模式。

本技能由创作者按以下结构组织：核心内容与导航在SKILL.md中；详细模式在

references/

目录下，仅在需要时加载（渐进式展示）。

When to Read Which Reference

何时阅读对应参考文档

Need	Read
Package layout, DI, config, plugins	references/architecture.md
Logging, metrics, tracing, health	references/observability.md
Test structure, fixtures, CI	references/testing.md
Async safety, concurrency, throughput	references/performance-concurrency.md
GIL, packaging, I/O, reliability	references/core-practices.md

需求	阅读文档
包结构、依赖注入、配置、插件	references/architecture.md
日志、指标、链路追踪、健康检查	references/observability.md
测试结构、测试夹具、CI	references/testing.md
异步安全、并发、吞吐量	references/performance-concurrency.md
GIL、打包、I/O、可靠性	references/core-practices.md

Quick Patterns

快速概览模式

Structure: Separate routing, domain, persistence, integration; use dependency injection and typed config (any framework or stdlib).
Observability: Structured logs with correlation IDs; metrics (Prometheus/StatsD); health/readiness endpoints; distinguish operational vs programmer errors.
Tests: Pyramid (unit → integration → e2e); fixtures for isolation; parametrize edge cases; parallel CI; avoid hidden network/time.
Concurrency: Async for I/O; threads for blocking libs; processes for CPU-bound. One long-lived client per dependency; timeouts and backpressure everywhere.
Reliability: Context managers for cleanup; validate at boundaries; no blocking calls in async paths; idempotent retries and circuit breaking for I/O.

结构：分离路由、领域逻辑、持久化、集成层；使用依赖注入和类型化配置（支持任何框架或标准库）。
可观测性：带关联ID的结构化日志；指标（Prometheus/StatsD）；健康/就绪检查端点；区分运维错误与开发者错误。
测试：测试金字塔（单元测试 → 集成测试 → 端到端测试）；使用测试夹具实现隔离；参数化边界用例；CI并行执行；避免隐藏的网络/时间依赖。
并发：I/O密集型任务用异步；阻塞型库用线程；CPU密集型任务用进程。每个依赖对应一个长连接客户端；所有操作都设置超时与背压。
可靠性：使用上下文管理器进行资源清理；在边界处做校验；异步路径中避免阻塞调用；I/O操作实现幂等重试与熔断机制。

Quick Reference / Examples

快速参考/示例

Task	Approach
Inject dependencies	Use typed getters or framework DI; see references/architecture.md.
Structured logging	Log with extra dict and correlation ID; see references/observability.md.
Reuse HTTP client	One long-lived client per app; timeouts on every call. See references/performance-concurrency.md.
Resource cleanup	Use context managers; avoid blocking in async. See references/core-practices.md.
Isolate tests	Fixtures, parametrize, no hidden network/time. See references/testing.md.

Context manager (reliable cleanup):

python

with open(path) as f:
    process(f.read())

任务	实现方式
注入依赖	使用类型化获取器或框架DI；详见references/architecture.md。
结构化日志	附带额外字典与关联ID进行日志记录；详见references/observability.md。
复用HTTP客户端	每个应用对应一个长连接客户端；所有调用都设置超时。详见references/performance-concurrency.md。
资源清理	使用上下文管理器；避免在异步路径中阻塞。详见references/core-practices.md。
隔离测试	使用测试夹具、参数化用例，避免隐藏的网络/时间依赖。详见references/testing.md。

上下文管理器（可靠的资源清理）：

python

with open(path) as f:
    process(f.read())

or async: async with client: ...


**Structured log / typed config:**
```python
logger.info("request_handled", extra={"request_id": req_id, "path": path})


**结构化日志 / 类型化配置：**
```python
logger.info("request_handled", extra={"request_id": req_id, "path": path})

Config: Settings from Pydantic BaseSettings or env, validated at startup.

undefined

undefined

Workflow

工作流程

Designing a new service → Read references/architecture.md, then references/core-practices.md.
Adding monitoring → Read references/observability.md.
Writing or refactoring tests → Read references/testing.md.
Optimizing or introducing async/threads/workers → Read references/performance-concurrency.md.

Keep SKILL.md lean; load reference files only when relevant to the task.

设计新服务 → 阅读references/architecture.md，然后阅读references/core-practices.md。
添加监控 → 阅读references/observability.md。
编写或重构测试 → 阅读references/testing.md。
优化或引入异步/线程/工作进程 → 阅读references/performance-concurrency.md。

保持SKILL.md简洁；仅在与当前任务相关时加载参考文档。