CSDN 完整教程
系列：《从小白到 AI 大模型开发工程师的进阶之路》 技术点：AI-0126 模块与包 主人公：小蓝伞
本文是第 38 期，围绕【import、from、模块搜索路径、包结构和 init】展开。示例用于复现实验；标注【建议验证】的部分需要按读者自己的 Windows、Python 版本和网络条件执行。
一、问题背景与适用场景
将文本清洗函数与命令行入口拆分到 appkit 包，从项目根目录启动。 本期要把概念落成一个可观察、可回滚的小实践。
二、先给结论
模块拆职责，包做目录组织；从项目根目录用 python -m 运行入口，避免循环导入和依赖当前目录的隐式行为。 本期最小产出：可安装的练习包。
三、前置准备
-
Windows 10/11，建议 Python 3.11 或项目采用的兼容版本。
-
练习目录：
D:\ai-learning\issue-38；涉及文件、依赖或配置时先备份。 -
不要提交 Token、密码和个人路径；未执行命令不得写成实测结果。
四、最小可复现实践
在练习目录保存并执行：
分别创建以下文件，代码块中的注释就是文件路径：
# appkit/__init__.py
from .text import normalize
__all__ = ['normalize']# appkit/text.py
def normalize(text):
return ' '.join(text.split()).lower()# appkit/main.py
from appkit.text import normalize
if __name__ == '__main__':
print(normalize(' Hello Python '))# pyproject.toml
[build-system]
requires = ['setuptools>=68']
build-backend = 'setuptools.build_meta'
[project]
name = 'appkit-demo'
version = '0.1.0'
description = 'Python package practice'在项目根目录执行 python -m pip install -e .，再执行 python -m appkit.main。
预期结果：安装命令完成后，模块入口输出 hello python；修改源码后可被当前虚拟环境直接导入，说明这是可安装的练习包。
五、关键原理与工程判断
1. 先定义输入和成功判据
模块拆职责，包做目录组织；从项目根目录用 python -m 运行入口，避免循环导入和依赖当前目录的隐式行为。
2. 保留状态和失败原因
把输入、输出、版本、目录和完整错误记入 README 或日志，便于定位而不是只写【失败】。
3. 小步执行与回滚
先跑最小样例，再一次改一个变量；危险操作先 dry-run、备份或 Git 提交。
六、常见问题与避坑
-
直接运行包内文件导致相对导入失败；从项目根目录使用 python -m 包.模块。
-
文件名遮蔽标准库或第三方包；避免使用 json.py、requests.py 等名称。
-
模块顶层执行副作用或相互导入；把入口放进 main 并拆清依赖方向。
七、验证清单
-
正常、边界、失败三类输入均有验证。
-
重新打开终端或进程后复验，排除缓存和当前会话影响。
-
产物能再次读取、运行或恢复；未实测部分标记【建议验证】。
八、面试题
-
本期技术点解决什么问题？解决输入、状态或失败边界的可控性。
-
为什么先做最小实践？降低变量数量，区分语法、环境和业务问题。
-
出现错误先做什么？保存完整错误，确认版本、目录、权限和输入。
-
如何判断真正生效？重启相关进程后，用独立命令和功能测试复核。
-
什么时候不能照搬示例？系统、版本、权限或输入契约不同，就要先调整并阅读官方文档。
九、本期小结与下一期
本期完成 可安装的练习包，把正确路径和失败路径都变成可验证动作。下一期继续学习资料库中的下一个技术点。点个关注不迷路，跟着小蓝伞把 Python 基础变成工程能力。可靠的程序也要能解释失败。
官方资料
十、记录与回滚
建议记录时间、解释器版本、执行目录、关键输出和失败原因；出现异常先停止批量操作，保留现场后恢复备份或回退 Git。