Python

函数命名不是取名字：它是在描述系统边界 副标题： 好的函数名不只是“好听”。它应该让读者看出：这个函数在做读取、 解析、校验、筛选、创建，还是修改状态。 适读人群： 正在写 Python service、runner、pipeline、SDK 或业务模块的开发者 阅读时间： 8 min 背景：为什么 get_dependencies 不是总比 resolve_graph 直观？ 看一个小型 graph pipeline runner： def trigger(self, mode, context): dependencies = self._resolve_graph(mode) self._validate_graph(dependencies) record = self._create_graph_record(mode, dependencies, context) while True: ready_nodes = self._ready_nodes(record) if not ready_nodes: break for node_name in ready_nodes: ... 刚开始可能会问： 为什么不叫 get_dependencies？ 为什么不叫 get_handler？ 为什么 ready_nodes 没有动词？ 为什么 skip_dependents 一看就像会改状态？ 这些不是风格洁癖。函数命名背后其实是在表达系统边界： mode 是外部语言，graph 是内部执行结构。 handler name 是配置语言，handler 是可调用对象。 ready node 是运行时状态，不是普通列表。 skip dependents 是副作用，不是查询。 这篇文章用一个 pipeline runner 作为例子，讲清楚函数命名应该如何暴露设计意图。 ...

本文是最小 Pipeline Runner 系列的 v1 后续章节：从 v0 的顺序 workflow list 出发，推导 dependency graph、ready wave、graph validation、node record 和 failed dependency blocking。

本文保留 nano-pipeline-runner v0 的完整推导链条：先证明普通函数调用什么时候足够，再通过工程接入、运行观察、失败记录、重复执行策略和共享 context 的压力，构建一个最小顺序 Pipeline Runner。

标题 请求日志一定要带 RequestId 吗？Python 成熟实践与落地指南 副标题 / 摘要 几乎所有“请求相关”的日志都应该带 requestId，但要通过自动注入而不是手工拼接。 本文给出 Python 成熟做法、工程场景与与 tracing 的关系，帮你真正落地。 目标读者 初学者：第一次处理线上问题，不懂为什么日志要串 requestId。 中级开发者：需要一套可复制的 Python 日志注入方案。 团队负责人：想建立统一的日志与追踪规范。 背景 / 动机 当系统出现错误时，最常见的现场是： “某个时间点报错了，但不知道是哪次请求导致的。” 如果所有“请求相关日志”都有 requestId，你就能一条链串起来： 从入口 → DB → RPC → 异常，一次请求的关键路径一眼可见。 在微服务/多进程环境里，requestId 更是日志协作的最低门槛。 核心概念 requestId：一次请求的唯一编号，用于日志串联与快速定位。 trace_id / span_id：分布式追踪中的链路标识（trace）与步骤标识（span）。 上下文传播：跨线程 / 协程 / 服务传递 requestId 或 trace。 自动注入：通过 middleware + logging filter，在日志里自动带 requestId。 思维推导（从朴素到工程可用） 朴素做法：每条日志手动写 request_id，很快遗漏、重复、维护成本高。 痛点暴露：一次请求会跨多个函数/协程/库层，手写方式不可控。 关键观察：requestId 本质是“请求上下文”，应由框架统一注入。 方法选择：在入口生成 requestId → 传入上下文 → logging 自动注入。 正确性理由：上下文随请求自然传播，日志格式统一且不侵入业务代码。 A — Algorithm（题目与算法） 题目还原 “是不是每一条日志都应该带 requestId？” ...

副标题 / 摘要 Python 高效易用，但也有明显工程代价。本文从 GIL、性能与类型系统三个角度分析缺陷与应对策略。 目标读者 使用 Python 的开发者 进行语言选型的团队 关注性能与工程质量的工程师 背景 / 动机 每种语言都有取舍。 理解缺陷能帮助你在工程上做出更好的决策。 核心概念 GIL：限制多线程 CPU 并行 解释执行：性能受限 类型系统：静态保障较弱 实践指南 / 步骤 CPU 密集任务用多进程或 C 扩展 性能瓶颈用 profile 工具定位 用类型标注与静态检查减少错误 在关键模块考虑更高性能语言 可运行示例 import time def cpu_task(n): s = 0 for i in range(n): s += i return s if __name__ == "__main__": start = time.time() cpu_task(10_000_00) print(time.time() - start) 解释与原理 Python 为了易用性牺牲了部分性能与并发能力。 工程上需要用多进程、缓存与类型检查弥补。 常见问题与注意事项 GIL 是否意味着不能并发？ IO 密集仍可并发，CPU 密集不行。 ...

副标题 / 摘要 ABC 用来“写抽象接口并阻止未实现的类被实例化”；ABCMeta 用来“在创建类时施加规则（自动注入、校验、注册）”。本文用最短可运行例子帮你在两者之间做选择。 目标读者 Python 初学者：了解抽象类怎么用、为啥会报 TypeError 中级开发者：在“接口约束”和“元类自动化”之间做取舍 需要做插件/框架能力的人：统一约束子类结构、自动补齐类级属性 背景 / 动机 你可能遇到过这些痛点： 想规定“子类必须实现某些方法”，但团队里总有人忘写 想让一批子类都有统一的类属性（比如 plugin_name），不想每个子类手写一遍 看到别人写 metaclass=ABCMeta，不确定是不是“更高级/更正确” 结论先说：大多数业务代码只需要 ABC；只有当你真的需要“类创建期的自动化规则”时，才考虑直接使用 ABCMeta（或在它上面做扩展）。 核心概念 1）抽象方法（@abstractmethod） 被标记为抽象的方法/属性，表示“必须由子类提供实现”。只要类里还有抽象成员未实现，它就不能被实例化。 2）抽象基类（ABC, Abstract Base Class） 用于定义一组接口约束：能继承、能被 isinstance/issubclass 判断，并能阻止不完整实现的类被实例化。 3）元类（metaclass） 普通类的“类”是 type；元类决定“类是怎么被创建出来的”。你可以在元类里： 在类创建时自动添加/修改类属性 校验子类是否符合规则（命名、属性、方法签名等） 统一注册子类到某个 registry ABCMeta 就是 abc 模块提供的元类：它把“抽象基类能力”实现为一套类创建/实例化规则。 实践指南 / 步骤 步骤 1：只需要“接口约束”——用 ABC 如果你只关心“子类必须实现哪些方法”，直接继承 ABC 是最简洁的写法。 步骤 2：需要“类创建期自动化规则”——用（或继承）ABCMeta 当你希望“子类不用手写，也能按规则自动拥有某些类属性/被校验/被注册”，再考虑元类。 可运行示例 示例 A：用 ABC 做接口约束（推荐默认选项） from abc import ABC, abstractmethod class Repo(ABC): @abstractmethod def save(self, obj) -> None: ... class MemoryRepo(Repo): def save(self, obj) -> None: print("saved:", obj) # Repo() # 取消注释会抛 TypeError：抽象类不能实例化 MemoryRepo().save({"id": 1}) 你得到的是：强约束（没实现抽象方法就不能实例化），且写法清晰。 ...

这篇文章从一个简单的工单系统出发，展示如何在 Python 项目中以业务对象为中心设计接口、仓储与服务，而不是让 ORM、框架和表结构牵着鼻子走。

以一个权限组管理模块为例，展示如何用领域模型 + 聚合仓储的方式设计后端，而不是让业务直接围着数据库表转。

让 FastAPI 异步真正“不卡”：asyncio.create_task + to_thread 并发实践（含 MySQL 写入） 副标题 / 摘要 把同步重活丢给线程、把可并行的子流程拆出来并发执行，让你的 FastAPI WebSocket/HTTP 服务在高并发文件处理场景下保持流畅与可靠。适合需要在事件循环中混合 CPU 计算与阻塞 I/O 的工程团队。 目标读者 中级后端工程师、服务端架构师 正在用 FastAPI/asyncio 落地异步工作流、混合 I/O/CPU 任务的开发者 背景 / 动机 常见痛点： 在异步服务里不小心执行了同步 CPU/数据库操作，单个请求“卡住”事件循环，导致同一 worker 上的其它请求/WebSocket 心跳/进度推送都被拖慢。 CPU/数据库步骤彼此本无强依赖，却被串行放到一条链上，整体时延被“关键路径”拖长。 目标： 不改变外部行为的前提下，消除事件循环阻塞。 让独立步骤并发执行，缩短关键路径。 核心概念 线程（Thread）：同一进程内共享内存，切换开销低；CPython 受 GIL 限制，纯 Python CPU 计算难并行，但适合并发等待阻塞 I/O。 进程（Process）：独立内存、无 GIL 约束，CPU 计算可多核并行；切换/通信成本更高，参数/结果需可序列化。 异步（async/await）：单线程事件循环的协作式调度；只有在 await 时让出控制权，同步阻塞会“卡死”循环。 asyncio.to_thread：把同步函数放到后台线程，释放事件循环；不等于多核加速，但对阻塞 I/O 有实效。 asyncio.create_task：并发启动一个协程，让它和当前协程重叠运行；用于编排并发，而非解除阻塞。 实践指南 / 步骤 识别阻塞点（示例项目） CPU 构树/展平/序列化：HeaderTree.from_documents、flatten_dfs、FlatHeaderTree.to_dict 同步 MySQL 写入：file_tree_table.upsert_tree 用 to_thread 包裹同步重活（释放事件循环） 在 build_file_tree 中，将 CPU/DB 步骤放入 await asyncio.to_thread(...)。 并发编排，缩短关键路径 在 full_pipeline_async：在 split 后立即 create_task(build_file_tree(...))，并发执行图片/表格处理、重组、存储；返回前再 await 构树结果。 可选：事件屏障与互斥 如需“保证某步骤不早于构树完成”，用 asyncio.Event。 多协程修改共享状态，用 asyncio.Lock 保护原子更新。 观测与参数 MySQL 连接池每进程默认较小（示例为 2），必要时调大。 Uvicorn workers 控制进程数，提升隔离与吞吐。 可运行示例 非阻塞构树与持久化（替换 build_file_tree 内部）： ...

现代加密替代方案：AES‑GCM 与 ChaCha20‑Poly1305 实战指南（附 Python 示例） 副标题 / 摘要 这篇延伸读聚焦现代 AEAD 算法，解释为什么 AES‑GCM 与 ChaCha20‑Poly1305 是 RC4 的安全替代，并提供可运行的 Python 示例、常见陷阱与最佳实践。 建议先阅读配套文章《用 Python 还原 RC4 + JWT + 自定义 SSO Token 加解密》，理解遗留方案，再迁移到本篇的现代实践。 目标读者 后端/安全工程师（中级以上） 需要在服务间或 Web 客户端安全传输数据的工程团队 计划从自研/过时算法迁移到现代 AEAD 的项目负责人 背景 / 动机 RC4 等过时算法存在结构性弱点，且难以正确、安全地使用。现代 AEAD（Authenticated Encryption with Associated Data）算法在保证“机密性”的同时还能“认证完整性”，有效防止篡改与重放，API 更易用，错误空间更小——因此成为主流推荐。 核心概念 AEAD：同时提供加密（Confidentiality）与认证（Integrity/Authenticity）的模式。 Nonce/IV（随机数）：每次加密必须唯一（对同一密钥）。常用长度：12 字节。 AAD（Associated Data）：不加密但要认证的额外上下文（例如请求头、资源标识）。 Tag（认证标签）：解密时必须验证；任何修改都会导致校验失败。 Key Derivation（密钥派生）：通过 HKDF/Argon2/Scrypt 将口令或主密钥派生为会话密钥，避免直接使用弱口令。 实践指南 / 步骤 安装依赖 pip install cryptography 生成或派生密钥 服务到服务：使用随机 16/32 字节密钥（AES‑128/256），KMS 管理与轮换。 口令到密钥：使用 HKDF（或 Argon2/Scrypt）派生固定长度密钥，避免直接使用口令。 选择算法 AES‑GCM：硬件加速广泛（x86 AES‑NI），在服务端通用、高性能。 ChaCha20‑Poly1305：对移动/无 AES 加速的设备更友好，性能稳定。 Nonce 策略 每条消息使用唯一 Nonce（12 字节），推荐 os.urandom(12)，将 Nonce 与密文一起存储/传输（前缀写入）。 AAD 的使用 将上下文信息（版本、用户ID、消息类型等）作为 AAD 提供，增强完整性绑定。 密钥轮换 引入 kid（Key ID），支持多活密钥与平滑迁移。 可运行示例 以下示例仅演示用法。请结合 KMS、密钥轮换、权限隔离与 TLS，构建完整的生产级方案。 ...