私有字段与类的模块导出一致性

私有字段与模块导出控制共同服务于“明确边界、隐藏实现、暴露契约”原则：私有字段（如__xxx）通过名称改写限制类内访问，__all__则显式声明模块对外接口，二者协同实现可靠封装。

私有字段的设计目标和模块导出的控制逻辑，本质上都服务于同一个核心原则：**明确边界、隐藏实现、暴露契约**。它们不是孤立机制，而是一体两面的封装策略——一个管类内部的数据可见性，一个管模块对外的接口可见性。

私有字段决定“类里谁能看到”

Python 中以双下划线 __ 开头的字段（如 __password）会触发名称改写（name mangling），变成 _ClassName__password。这并非强制访问禁止，而是发出明确信号：该字段属于类的内部实现细节，外部不应依赖其存在或格式。

• 子类无法直接继承或覆盖 __xxx 字段（会被各自重命名为不同形式）
• 模块外代码若硬写 obj._ClassName__password，虽能读取，但等于绕过约定，后续类重构可能直接失效
• 单下划线 _xxx 是弱提示，表示“受保护”，不改名，但语义上仍建议仅在本模块或子类中使用

模块导出控制“外面能拿到什么”

一个 Python 模块（.py 文件）默认导出所有顶层名称（函数、类、变量），但可通过 __all__ 显式声明公共接口：

• __all__ = ["User", "create_user"] 表示只允许外部 import 这两个名称，其他（包括 _helper 或 __version）视为私有，IDE 和文档工具会据此过滤
• 未在 __all__ 中列出的名称，即使被 import，也属于“未承诺行为”，随时可能删除或修改
• 这与 Go 的首字母大小写导出规则、Rust 的 pub 关键字逻辑一致：导出即承诺，未导出即保留修改自由

两者协同才能形成可靠封装

如果只设私有字段却不控制模块导出，外部仍可能通过 from module import * 拿到你不希望暴露的辅助类或测试函数；反之，若模块导出很干净，但类内部把关键状态全用公有字段暴露，那封装就只剩一层薄纸。

• 典型错误：在模块里定义了 class DatabaseConnection，含公有字段 host、port、password —— 即使加了 __all__，只要类被导出，密码就裸奔
• 正确做法：password 声明为 __password，连接逻辑封装在 connect() 方法中，模块只导出 DatabaseConnection 类本身（而非其字段）
• 更进一步：模块内定义的辅助函数（如 _encrypt_key()）不列入 __all__，且命名带下划线，双重保险

调试与序列化时的例外处理

实际开发中，日志、调试器、JSON 序列化等场景常需临时突破封装。此时应提供受控通道，而非放任直连：

• 为类添加 __repr__ 或 to_dict() 方法，按需返回脱敏后的字段（如 "password": "***"）
• 模块导出专用调试工具（如 debug_dump(obj)），并明确标注“仅供开发使用”，不放入 __all__
• 避免在生产代码中出现 obj._Class__field 或 getattr(obj, "_Class__field") 这类硬编码访问