python-runtime-operations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Runtime Operations

Python 运行时操作

Overview

概述

Every service, worker, and CLI entrypoint must validate its environment before doing real work, shut down cleanly under all exit paths, and emit structured signals that make runtime behavior observable. Treat these as preferred defaults — deviate when project constraints demand it, but call out tradeoffs and compensating controls.

每个服务、工作进程和CLI入口点在执行实际工作前必须验证其运行环境，在所有退出路径下实现优雅关闭，并生成结构化信号以确保运行时行为的可观测性。请将这些作为推荐默认规范——仅当项目约束要求时才偏离，但需明确说明权衡点和补偿控制措施。

When to Use

适用场景

Startup fails late because config is validated after work begins.
Shutdown leaves open connections, orphaned subprocesses, or incomplete transactions.
Job retries run forever with no dead-letter or terminal-state handling.
Logs are unstructured, missing correlation IDs, or inconsistent across services.
Health and readiness probes are missing or misleading.
Signal handling (SIGTERM, SIGINT) is absent or racy.

因在开始工作后才验证配置，导致启动阶段后期失败。
关闭后遗留未关闭的连接、孤儿子进程或未完成的事务。
作业重试无限循环，未处理死信或终端状态。
日志无结构化，缺少关联ID，或在各服务间不一致。
缺失健康检查和就绪探针，或探针信息存在误导性。
缺少信号处理（SIGTERM、SIGINT），或处理存在竞态条件。

When NOT to Use

不适用场景

Pure library or data-model code with no process lifecycle concerns.
Build, packaging, or CI/CD pipeline configuration.
Algorithm or business-logic design with no runtime surface.

无进程生命周期相关需求的纯库或数据模型代码。
构建、打包或CI/CD流水线配置。
无运行时交互的算法或业务逻辑设计。

Quick Reference

快速参考

Validate all runtime config at startup; fail fast with clear errors before doing real work.
Register signal handlers and ensure graceful shutdown with bounded cleanup timeouts.
Make retry limits, backoff, and dead-letter/terminal-state behavior explicit in every job system.
Emit structured logs (JSON) with consistent severity levels and correlation IDs.
Expose health, readiness, and liveness probes that reflect actual dependency state.
Track core runtime signals: startup latency, queue depth, error rates, shutdown duration.

在启动阶段验证所有运行时配置；在执行实际工作前快速失败并给出清晰错误信息。
注册信号处理程序，确保在有限的清理超时时间内完成优雅关闭。
在每个作业系统中明确重试限制、退避策略以及死信/终端状态处理逻辑。
生成带一致严重级别和关联ID的结构化日志（JSON格式）。
暴露能反映实际依赖状态的健康、就绪和存活探针。
跟踪核心运行时指标：启动延迟、队列深度、错误率、关闭时长。

Common Mistakes

常见错误

Validating config lazily — checking environment variables or secrets on first use instead of at startup, causing failures minutes or hours into a run.
Unbounded cleanup — shutdown handlers that wait forever on draining connections or flushing buffers, turning a clean restart into a hung process.
Silent retry exhaustion — retrying failed jobs indefinitely without logging terminal failures or routing to a dead-letter queue.
Logging without structure — using plain-text
```
print
```
or unstructured
```
logging.info
```
calls that cannot be parsed, filtered, or correlated in production.
Health probes that lie — returning 200 OK from a health endpoint without checking downstream dependencies, masking cascading failures.

延迟验证配置——在首次使用时才检查环境变量或密钥，而非在启动阶段，导致运行数分钟或数小时后才出现故障。
无限制清理——关闭处理程序无限期等待连接排空或缓冲区刷新，将正常重启变为进程挂起。
重试耗尽无提示——无限重试失败的作业，未记录终端故障或路由到死信队列。
无结构化日志——使用纯文本
```
print
```
或无结构化的
```
logging.info
```
调用，导致生产环境中无法解析、过滤或关联日志。
健康检查失真——健康端点返回200 OK但未检查下游依赖，掩盖级联故障。

Scope Note

范围说明

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

请将这些建议作为常见场景的推荐默认规范，而非通用规则。
如果默认规范与项目约束冲突或导致更差结果，请提出更合适的替代方案并解释为何更适配该场景。
当偏离默认规范时，需明确说明权衡点和补偿控制措施（测试、可观测性、迁移、回滚）。

Invocation Notice

调用说明

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

当按名称调用此技能时，需告知用户：
```
python-design-modularity
```
。

References

参考资料

```
references/runtime-behavior.md
```
```
references/logging-metrics-tracing.md
```

references/process-lifecycle-and-cleanup.md

```
references/runtime-behavior.md
```
```
references/logging-metrics-tracing.md
```

references/process-lifecycle-and-cleanup.md