python-runtime-operations

Python 运行时运维

概述

每个服务、工作进程和 CLI 入口点都必须先验证环境，再执行实际工作；无论通过何种路径退出，都必须干净地关闭，并发出结构化信号，使运行时行为可观测。 将这些建议视为优先默认做法——若项目约束要求偏离，可酌情调整，但要说明权衡与补偿措施。

适用场景

• 配置在工作开始后才验证，导致启动失败过晚。
• 关闭时遗留开放连接、孤立子进程或未完成的事务。
• 作业无限重试，没有死信或终止状态处理机制。
• 日志缺少结构、关联 ID，或各服务间格式不一致。
• 缺少健康检查和就绪探针，或探针不能准确反映状态。
• 缺少信号处理（SIGTERM、SIGINT），或处理存在竞态。

不适用场景

• 不涉及进程生命周期的纯库代码或数据模型代码。
• 构建、打包或 CI/CD 流水线配置。
• 不涉及运行时接口的算法或业务逻辑设计。

快速参考

• 在启动时验证所有运行时配置；在执行实际工作前快速失败，并提供清晰的错误信息。
• 注册信号处理器，并确保优雅关闭时的清理超时时间有上限。
• 在每个作业系统中明确设置重试次数上限、退避策略，以及死信或终止状态处理方式。
• 输出带有统一严重性级别和关联 ID 的结构化日志（JSON）。
• 提供健康检查、就绪和存活探针，以反映实际依赖状态。
• 跟踪核心运行时信号：启动延迟、队列深度、错误率和关闭耗时。

常见错误

• 延迟验证配置 — 首次使用时才检查环境变量或密钥，而不是在启动时检查，导致运行数分钟或数小时后才失败。
• 无界清理 — 关闭处理器无限期等待连接排空或缓冲区刷新，使原本干净的重启变成进程挂起。
• 重试耗尽时不记录 — 无限重试失败作业，却不记录最终失败，也不将其路由到死信队列。
• 日志缺乏结构 — 使用纯文本 print 或无结构的 logging.info 调用，导致生产环境中无法解析、筛选或关联日志。
• 健康探针提供错误信息 — 健康端点不检查下游依赖便返回 200 OK，掩盖连锁故障。

适用范围说明

• 对常见情形，将这些建议视为优先默认做法，而非通用规则。
• 如果某项默认做法与项目约束冲突，或会导致更差的结果，请提出更合适的替代方案，并说明为何它更适用于当前情形。
• 偏离默认做法时，请说明权衡与补偿措施（测试、可观测性、迁移、回滚）。

调用说明

• 按名称调用此技能时，告知用户正在调用：python-design-modularity。

参考资料

• references/runtime-behavior.md
• references/logging-metrics-tracing.md
• references/process-lifecycle-and-cleanup.md