Python代码边界不清表现为函数职责混乱、模块划分模糊、变量作用域滥用、输入输出不明确，导致可读性、可维护性、可测试性下降；应遵循单一职责、分层隔离、参数传递、类型标注等原则重构。
Python 代码边界不清，主要指函数职责混乱、模块划分模糊、变量作用域滥用、输入输出不明确等问题。这会让代码逐渐失去可读性、可维护性和可测试性，小问题容易滚雪球变成大隐患。
函数职责越界，逻辑越来越难理清
一个函数既查数据库、又处理业务规则、还拼接前端 HTML，看起来“一气呵成”，实则埋下三重风险：修改某处逻辑时不敢动，怕牵连其他功能；写单元测试无从下手，因为依赖太多外部状态；多人协作时容易重复实现或互相覆盖。
- 建议每个函数只做一件事，比如 validate_input 只校验参数，fetch_user 只查库，format_response 只组装返回值
- 把跨层操作（如 DB + HTTP + 日志）拆到不同层级，用参数或返回值传递数据，而非在函数内部硬编码调用链
模块/包边界模糊，项目结构迅速失控
当 utils.py 里塞了加密、日期处理、HTTP 封装、甚至某个业务的临时脚本，models.py 开始包含 API 调用和缓存逻辑，整个项目的“分层感”就消失了。新成员看不懂哪部分该改、哪部分该复用，重构时也常误删关键逻辑。
- 按关注点分离：models 管数据结构与持久化，services 管核心业务流程，api 或 views 只负责接收请求与返回响应
- 避免跨层直连，比如视图层直接调用数据库查询——应通过 service 层中转，保持各层接口清晰
变量作用域泛滥，状态变得不可预测
全局变量、模块级 mutable 对象（如 list/dict）、闭包中随意修改外层变量，会让函数行为随执行顺序或调用路径变化。看似简单的函数，在并发或多次调用时可能返回不同结果，调试时很难复现问题。
立即学习“Python免费学习笔记（深入）”；
- 优先使用函数参数传入所需数据，返回新对象而非修改原对象（尤其对 list/dict）
- 避免在模块顶层初始化可变对象，如 cache = {}，改用函数内懒加载或依赖注入方式管理生命周期
输入输出定义模糊，集成成本越来越高
函数不声明参数类型、不注明返回结构、不说明异常场景，调用方只能靠猜或读源码。时间一长，连作者自己都记不清某个字段是字符串还是 int，是否允许 None，有没有副作用。
- 用 type hints 明确标注参数与返回值，配合 pydantic 或 dataclass 定义结构化输入输出
- 文档字符串中说明典型用例、边界情况（如空输入、超长文本）、以及可能抛出的异常类型
