python-data-state

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Data and State

Python 数据与状态

Overview

概述

Every data bug traces back to an unclear answer to three questions: who owns this data, where is it validated, and how far does it travel? This skill encodes boundary-first thinking — make ownership explicit, validate at the edge, and minimize what crosses a boundary.

Treat these defaults as starting points. When project constraints demand deviation, call out tradeoffs and compensating controls (tests, observability, rollback).

每一个数据问题的根源都可以归结为三个问题没有明确答案：谁拥有这些数据？在哪里验证数据？数据会流转到多远的地方？本技能融入了边界优先的思维模式——明确所有权、在入口处验证数据、最小化跨边界传输的数据量。

将这些默认规则作为起点。当项目约束要求偏离这些规则时，需明确说明取舍方案和补偿控制措施（如测试、可观测性、回滚）。

When to Use

适用场景

Data ownership is ambiguous or split across modules.
Validation logic is scattered or duplicated instead of concentrated at ingress.
Mutable state is shared across module or layer boundaries.
Multiple modules participate in a single transaction.
Configuration is stringly-typed, read lazily, or inconsistent across environments.
Lifecycle of a data object (creation, transformation, persistence) spans unclear boundaries.

数据所有权模糊或在模块间拆分。
验证逻辑分散或重复，而非集中在入口处。
可变状态跨模块或跨层边界共享。
多个模块参与单一事务。
配置为字符串类型、延迟读取或在不同环境间不一致。
数据对象的生命周期（创建、转换、持久化）跨越不清晰的边界。

When NOT to Use

不适用场景

Pure algorithmic or computational logic with no shared state.
Prototypes or throwaway scripts where boundary discipline adds no value.
UI/presentation-layer styling decisions with no data modeling impact.

无共享状态的纯算法或计算逻辑。
原型或一次性脚本，边界规范无法带来价值。
不影响数据建模的UI/展示层样式决策。

Quick Reference

快速参考

Make module ownership and invariants explicit.
Validate at ingress and normalize before domain decisions.
Share minimal data across boundaries — prefer narrow, typed interfaces.
Avoid cross-module transactions by default; if unavoidable, isolate coordination logic.
Keep configuration typed, environment-driven, and startup-validated.

明确模块所有权和不变量。
在入口处验证数据，并在做出领域决策前进行标准化处理。
跨边界共享最少的数据——优先使用窄幅、类型化的接口。
默认避免跨模块事务；若无法避免，隔离协调逻辑。
保持配置为类型化、环境驱动，并在启动时进行验证。

Common Mistakes

常见错误

Validating deep inside the call stack — pushing checks into domain logic instead of catching bad data at the boundary where it enters.
Exposing internal models across module boundaries — sharing ORM objects or rich domain models instead of narrow DTOs or typed dicts.
Relying on implicit ownership — assuming "whoever wrote it last" owns the data, leading to conflicting mutations and no single source of truth.
Lazy, untyped config reads — calling
```
os.getenv()
```
at point-of-use with string defaults, so missing or malformed config surfaces as a runtime surprise instead of a startup failure.
Wrapping unrelated modules in a shared transaction — coupling independent data stores for perceived consistency, creating hidden rollback complexity and contention.

在调用栈深处进行验证——将检查逻辑推入领域层，而非在数据进入的边界处拦截不良数据。
跨模块边界暴露内部模型——共享ORM对象或复杂领域模型，而非窄幅DTO或类型化字典。
依赖隐式所有权——假设“最后修改的人”拥有数据，导致冲突性修改和缺乏单一可信数据源。
延迟、无类型的配置读取——在使用点调用
```
os.getenv()
```
并设置字符串默认值，导致缺失或格式错误的配置在运行时才暴露，而非在启动时就检测到失败。
将不相关模块包裹在共享事务中——为了实现感知到的一致性而耦合独立的数据存储，带来隐藏的回滚复杂度和资源竞争。

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-data-state
```
.

当调用本技能时，需告知用户技能名称：
```
python-data-state
```
。

References

参考资料

```
references/data-lifecycle.md
```
```
references/consistency-boundaries.md
```
```
references/configuration.md
```

```
references/data-lifecycle.md
```
```
references/consistency-boundaries.md
```
```
references/configuration.md
```