模块化核心是职责分离与接口清晰：函数应单一职责、命名动词化；业务按概念建包并分层；配置驱动行为；模块间通过显式接口通信而非直接导入。
把重复逻辑抽成独立函数，而不是塞进主流程
很多初级项目里，main() 或入口函数动辄两三百行，里面混着数据读取、校验、转换、输出，改一处牵连五处。真正该做的，是顺着“做了什么”去切分——比如读 CSV、清洗手机号、生成报告，每个动作都对应一个有明确输入输出的函数。
实操建议：
- 函数名用动词开头，如
parse_user_csv()、normalize_phone_number()，别叫do_something() - 单个函数只做一件事，返回值类型要稳定（比如统一返回
dict或list，别有时返回None有时返回结果） - 避免函数内部直接读文件或打印——把路径、日志句柄作为参数传入，方便单元测试和替换
按职责分目录，别按文件类型堆砌
看到 /src/utils/ 下全是 string_helper.py、time_helper.py、file_helper.py 就该警觉了：这不是模块化，这是分类垃圾桶。真正的模块应该围绕业务概念组织，比如用户管理、订单处理、配置加载。
实操建议：
- 先列出现有核心名词（如
User、Order、Config），每个建一个子包：/user/、/order/、/config/ - 每个子包内放
models.py（数据结构）、service.py（核心逻辑）、repository.py（数据存取），不用强求三者全有，但别把模型定义和数据库连接写在同一个文件里 -
/utils/只保留跨领域通用工具，比如retry_on_failure()、safe_json_load()；一旦发现某个 “工具函数” 只被/user/下的代码调用，就把它移到/user/utils.py
用配置驱动行为，别让逻辑散落在 if 判断里
当代码里频繁出现 if env == "prod": ... elif env == "dev": ...，或者硬编码路径、超时时间、API 地址，说明配置和逻辑已经缠在一起。这类分支不仅难测，而且每次换环境都要改代码。
实操建议：
- 用一个统一入口加载配置，比如
config.load_config()，返回一个不可变对象（types.SimpleNamespace或pydantic.BaseModel实例） - 把环境相关参数（
DB_URL、TIMEOUT_SEC、LOG_LEVEL）从代码中彻底移出，放到config.yaml或.env中 - 不要在业务函数里写
if config.ENABLE_CACHE:—— 把缓存逻辑封装进cache_service.py，由配置决定是否注入该服务实例
模块间通信走显式接口，别直接 import 全局变量或模块内部函数
常见陷阱：A 模块直接 from user.models import User，B 模块又 from user.service import create_user，C 模块再 import user 然后调 user.create_user()。表面看没问题，但一旦 user.service 重构，所有引用点都得手动查漏补缺。
实操建议：
- 每个业务子包提供清晰的对外接口，在
__init__.py中显式导出：from .service import create_user, get_user_by_id，然后__all__ = ["create_user", "get_user_by_id"] - 调用方只导入包一级，如
from user import create_user，不深入到user.service或user.models - 如果两个模块需要协作（比如订单创建要校验用户状态），别让
order.service直接调user.service.get_user()，而是通过依赖注入或回调函数传入校验能力，降低耦合
