高质量 Python 项目是分层设计、基础设施、日志监控与工程化管理的综合产物。以下是个人在实战中沉淀的项目“骨架”核心准则：

1. DTO (Data Transfer Objects)

  • 准则：DTO 是系统稳定性的基石。必须区分：
    • Req/Resp：外部交互协议。
    • Params/Result：内部 Service 契约。
    • PO/BO/FO：细分持久化、业务与展现对象。
  • 推荐：首选 pydantic 或 msgspec。

2. 解耦与结构驱动

  • 路径：Schema (结构) -> Service (业务) -> Controller (入口)。
  • 原则：先定义结构，再填充逻辑。
  • 解耦准则：模块间严禁循环依赖。
    • 依赖抽象：高层不应直接依赖底层实现。应通过 typing.Protocol 或抽象基类（ABC）定义的接口进行注入。
    • 单向流动：依赖链必须单向。双向通信应引入中转模块（Schema/Event）或回调机制。
  • 设计模式：
    • 组合优于继承：优先使用 Mixin 模式。
    • 面向协议：使用 typing.Protocol 实现鸭子类型校验。

3. SQLite 使用准则

  • 用途平反：SQLite 的性能长期被低估。在 WAL 模式及合理配置下，其读写吞吐足以支撑多数业务规模，且运维成本极低。
  • 优势：多线程安全，轻量级持久化首选。
  • 扩展：建议配合 diskcache、sqlitedict 使用。
  • 迁移：通过 SQLAlchemy 等 ORM 屏蔽差异，支持随时切换到 MySQL。
  • 警示：注意 Session 线程安全，严禁过度依赖文件锁。

4. 基础设施与并发

  • 首选中间件：优先使用 Redis 或 Diskcache 处理并发协作。
  • 锁管理：分布式或多进程场景下慎用锁。
    • 禁止嵌套锁：极易死锁。
    • 逻辑替代：优先通过原子操作、版本号（CAS）或队列解耦。
  • 通信解耦：服务间解耦首选 HTTP/gRPC。
  • 底层避坑：严禁直接调用 SharedMemory、Pipe 或 Unix Domain Socket。跨平台性差，易引发死锁或内存泄漏。

5. 持久化层节制

  • 注：引入 SQL/NoSQL 前必评估必要性。拒绝基础设施滥用，简单的内存结构在 80% 场景下足以应对。

6. 日志：高效可观测

  • 原则：每条日志必须具备有效定位信息。
  • 禁忌 (Bad Cases)：
    • 无链路上下文：缺 Trace ID，无法还原请求拓扑。
    • 无效描述：如 "Error"、"Finished" 等无定位价值的内容。
    • 非法格式：缺标准时间戳、日期或模块前缀。
    • 泄露隐私：打印明文密码、密钥或用户隐私 (PII)。
    • 吞噬堆栈：捕获异常仅打印简述，不记录 exc_info。
  • 准则：标准化日志应能直接对接 ELK 或 Prometheus 告警。
  • 优先级：统计指标（成功率）与服务心跳价值高于调试日志。

7. 技术深度：保持克制

  • 纯函数优先：纯函数是逻辑校验、单元测试及并行计算的一等公民。它无副作用，给定相同输入必得相同输出。核心业务逻辑应尽可能抽离为纯函数，并与 IO 操作严格分离。
  • 警惕特性：除非核心开发完全掌握，否则严禁在业务逻辑中引入 异步 (Asyncio) 或 元类 (Metaclass)。
  • 状态隔离：异步或并发环境下，必须使用 contextvars 替代 threading.local 管理上下文（如 Trace ID），确保数据在协程间隔离。
  • 作用域最小化：
    • 精简暴露：优先使用私有（_）成员；严禁非必要全局变量。
    • 变量寿命：缩短变量生命周期，防止状态混淆。
  • 核心风险：
    • Asyncio 陷阱：阻塞协程（如同步 requests 或 time.sleep）会导致进程假死。性能监控必开 PYTHONASYNCIODEBUG=1。
    • 元类副作用：劫持创建行为，极难调试。
  • 限制：禁止使用自定义描述符或 sys._getframe() 等堆栈劫持技术。

8. 配置管理：外置解耦

  • 原则：禁止硬编码配置。
  • 最佳实践：使用 pydantic-settings 配合 .env 管理，享受类型提示与自动发现。

9. 异常管理：全局可控

  • 准则：异常必须 统一捕获、统一返回、统一处理。
  • 落地：在框架层（如 Controller Middleware）统一拦截自定义异常。严禁裸捕获（bare except:）。

10. 工程环境

  • 环境管理：必须使用 lock 机制。首选 uv；备选 Poetry/PDM。
  • IDE 与 Linter：强制集成 Pylance/Pyright、Mypy 及 Ruff。
  • Conda：仅限涉及 CUDA 等系统级依赖的深度学习场景。
  • 工具链选择：
    • HTML 解析：数据抓取场景 selectolax 性能远超 lxml。
    • 序列化：优先 msgspec。解析与校验速度优于 pydantic 与 orjson。

11. 鲁棒性准则

  • 无幂等不重试：引入指数退避重试前必确保接口幂等。
  • 回归底线：存量变更必配自动化回归测试。
  • 无测试不开发：复杂功能强制 TDD。
  • ID 策略：
    • 可读型：包含时间戳 + 类型前缀（用于人工审计）。
    • 有序型：如 Snowflake 或 UUIDv7。MySQL 严禁使用无序 UUID 作主键；Snowflake 产生的 64位有序 int 能显著提升聚簇索引写入性能，且占用空间更小。
    • 随机型：用于匿名化或防业务量泄露。

13. 两大难题：缓存失效与命名

  • 生命周期管理：Redis 键必须包含 Namespace 前缀（如 app:module:key），并设置合理的 TTL，严禁产生永久键值。
  • 命名规范：遵循 PEP 8，名字反映意图。
    • 严禁歧义：如 process_data、obj、item 等模糊词汇。
    • 拒绝冗余：如 User.name 而非 User.user_name。

精简骨架，面向未来。