pycharm|学会模块（包）编码模式+旧.py重构+struture管理面板

一、模块（包）编码模式

✅ 适用版本：PyCharm Community / Professional（2023+）

✅ 项目类型：普通 Python 项目（非 Django/Flask 等框架）

---

第一步：创建新项目

1. 打开 PyCharm。
2. 点击 File → New Project。
3. 选择 Pure Python。
4. 设置项目位置，例如：my_app
5. 确保 Python 解释器已正确配置（如系统 Python 或虚拟环境）。
6. 点击 Create。

💡 建议勾选 "Create a main.py"（可选），方便后续测试。

---

第二步：理解"模块 = 目录"的原理

在 Python 中：

• 一个 .py 文件是一个 模块（module）。
• 一个包含 __init__.py 的文件夹是一个 包（package），而包本身也是一个模块。
• 因此，"每个功能模块一个目录" = 每个功能做成一个包。

---

第三步：创建你的第一个模块目录（包）

假设我们要开发一个用户管理功能：

1. 在项目根目录（如 my_app）上 右键。
2. 选择 New → Python Package。
3. 输入名称：user

✅ PyCharm 会自动创建：

1my_app/
2└── user/
3    └── __init__.py

🔍 __init__.py 可以是空文件，但它的存在让 Python 把 user 当作一个可导入的模块。

---

第四步：向模块中添加子功能文件

现在，在 user/ 目录下添加具体功能：

1. 右键 user 目录 → New → Python File
2. 创建以下文件：
   • models.py（定义用户数据结构）
   • service.py（处理业务逻辑）
   • api.py（对外接口）

最终结构：

1my_app/
2├── main.py
3└── user/
4    ├── __init__.py
5    ├── models.py
6    ├── service.py
7    └── api.py

示例代码：

user/models.py

1class User:
2    def __init__(self, name: str, email: str):
3        self.name = name
4        self.email = email

user/service.py

1from .models import User
2
3def create_user(name: str, email: str) -> User:
4    return User(name, email)

user/init.py（可选：简化外部导入）

1from .service import create_user
2from .models import User
3
4__all__ = ['create_user', 'User']

---

第五步：从主程序导入并使用模块

编辑 main.py：

1from user import create_user, User
2
3if __name__ == "__main__":
4    user = create_user("Alice", "alice@example.com")
5    print(f"Created user: {user.name}")

✅ 点击运行（▶️），应输出：

1Created user: Alice

⚠️ 如果报错 ModuleNotFoundError，请确保：

• 项目根目录（my_app）被标记为 Sources Root（见下一步）

---

第六步：标记 Sources Root（关键！）

PyCharm 需要知道从哪里开始解析模块路径。

1. 在项目视图中，右键点击 my_app 根目录。
2. 选择 Mark Directory as → Sources Root。

你会看到目录图标变成蓝色（PyCharm 的 Sources Root 标识）。

✅ 这样 from user import ... 才能被正确识别。

---

第七步：继续添加更多模块目录

重复第三步，创建其他功能模块：

• payment/

• notification/

• utils/

  1my_app/
  2├── main.py
  3├── user/
  4│ ├── init.py
  5│ ├── models.py
  6│ └── service.py
  7├── payment/
  8│ ├── init.py
  9│ └── stripe_client.py
  10└── utils/
  11 ├── init.py
  12 └── logger.py

每个目录都是一个独立模块，彼此解耦，易于维护和测试。

---

第八步（进阶）：重构已有 .py 文件为目录

如果你已有 old_module.py，想改成目录形式：

1. 右键 old_module.py → Refactor → Convert to Python Package
2. PyCharm 自动：
   • 创建 old_module/ 目录
   • 将原文件内容移入 old_module/__init__.py
   • 更新所有引用（如果启用自动重构）

✅ 安全、高效，适合项目演进。

---

二、如何高效重构？（技巧）

方法一：使用 PyCharm 的 "Extract Class to File"

1. 在编辑器中选中某个类（如 FixWidget）
2. 右键 → Refactor → Extract → Move Class to New File
3. 输入新文件名（如 fix_widget.py）
4. PyCharm 会自动创建文件并移动代码！

💡 注意：这个功能在某些版本中叫"Move Class to New File"，位置在 Refactor → Move Class

方法二：批量重命名 + 移动

• 先用快捷键 Ctrl+Alt+Shift+T → Refactor → Move，把类移到新文件。
• 或者手动复制粘贴 + 删除旧代码。

---

🎯 最终目标结构示例（理想情况）

1box5/
2├── __init__.py
3├── fix_widget.py
4├── fix_helper.py
5├── muti_tab_box.py
6├── paint_event.py
7└── utils.py

每个文件只包含一个主要类或一组相关函数。

最佳实践总结

建议	说明
✅ 每个功能 = 一个包（目录）	如 auth/, database/, api/
✅ 使用 __init__.py 控制导出	避免 from xxx import * 污染命名空间
✅ 标记根目录为 Sources Root	防止导入错误
✅ 避免循环导入	合理设计模块依赖关系
✅ 用相对导入（from .models import User）	在包内部使用

---

优点：

• 清晰的层次结构
• 良好的可维护性
• 易于团队协作
• 符合 Python 官方推荐的模块化设计

🎯 记住：在 Python 中，"目录 + __init__.py = 模块"。PyCharm 让这一过程变得极其简单！

---

三、Structure（结构视图）

PyCharm 的 Structure 工具窗口 （结构视图）是 Python 开发中最强大的代码导航工具之一 。它不仅能列出当前文件中的所有类、函数、方法（即 class 和 def），还支持丰富的右键操作，极大提升开发效率。

下面详细介绍它的核心功能，特别是 右键菜单能做什么：

---

🔍 一、Structure 是什么？

• 位置 ：通常在 PyCharm 右侧或底部（可拖动），也可通过 View → Tool Windows → Structure 打开
• 快捷键 ：Alt + 7 （Windows/Linux） / Cmd + 7（macOS）
• 作用 ：以树形结构展示当前 .py 文件中的所有 符号（Symbols） ，包括：
  • 类（class）
  • 函数/方法（def）
  • 全局变量（可选）
  • 属性（@property）
  • 导入语句（可选）

✅ 默认只显示 class 和 def，干净清晰。

---

🖱️ 二、右键菜单功能详解（重点！）

在 Structure 面板中，右键点击任意一个 def 或 class，会弹出强大菜单：

1. Go to → Declaration or Usages

• 作用：跳转到该方法的定义处（其实点击本身就能跳转，这个是冗余的）
• 快捷方式：直接单击即可跳转

---

2. Find Usages（查找引用）

• 快捷键 ：Alt + F7
• 作用 ：在整个项目中搜索哪里调用了这个方法
• 场景 ：你想知道 on_toggle_click 被谁调用？点它就知道！

✅ 结果会显示在 "Find" 工具窗口，支持双击跳转。

---

3. Rename...（重命名）

• 快捷键 ：Shift + F6
• 作用 ：安全重命名方法名，并自动更新所有调用处
• 示例 ：
  • 原方法：update_collapsed_state
  • 改为：toggle_collapse
  • 所有 self.update_collapsed_state() 自动变成 self.toggle_collapse()

⚠️ 这是重构的核心功能，避免手动查找替换出错。

---

4. Refactor → Move...

• 作用 ：将当前方法移动到另一个类或模块
• 注意 ：仅适用于独立函数 或可提取的方法
• 如果方法强依赖 self，PyCharm 会提示无法移动

---

5. Refactor → Extract Method...

• 作用 ：如果你在一个大方法里选中一段代码，再右键 → Extract Method，可以把这段代码提取成新方法
• 虽然通常在编辑器里操作，但 Structure 也提供入口

---

6. Show in Explorer / Reveal in Finder

• 作用 ：在文件系统中定位当前 .py 文件（不是方法本身）
• 一般用不到

---

7. Pin Tab / Unpin Tab

• 作用：固定 Structure 面板，防止被其他工具窗口覆盖

---

🎛️ 三、顶部工具栏功能

Structure 窗口顶部有几个小图标，也很有用：

图标	功能
🔍 搜索框	输入方法名（如 drag），实时过滤列表
📋 Sort by Name	按字母排序（默认按代码顺序）
🧩 Show Inherited Members	显示父类继承来的方法（对 Qt 开发很有用！）
📦 Show Fields	显示实例变量（如 self.path = ...）
🔄 Refresh	手动刷新（通常自动更新）

💡 建议保持 "按代码顺序"（不点 Sort by Name），方便理解执行流程。

---

🖼️ 四、实际使用场景举例

场景 1：快速跳转到某个方法

• 打开 file_dock.py
• 按 Alt + 7
• 在 Structure 中点击 dropEvent → 立即跳转

场景 2：查看一个方法被谁调用

• 右键 delete_permanently → Find Usages
• 发现只有 on_delete_clicked 调用了它 → 安全修改

场景 3：重命名方法

• 右键 update_collapsed_state → Rename
• 改为 set_collapsed
• 所有调用自动更新，包括信号连接（如果用了字符串形式需注意）

---

⚙️ 五、如何优化 Structure 显示？

如果你觉得太杂，可以自定义：

1. 打开 Structure 窗口右上角 齿轮图标 ⚙️
2. 取消勾选：
   • Show Modules
   • Show Variables（除非你需要看全局变量）
3. 保留：
   • Show Classes
   • Show Functions

这样就只显示 class 和 def，干净清爽！

---

✅ 总结：Structure 是你的"代码地图"

功能	价值
一键跳转	比滚动快 10 倍
查找引用	安全修改代码的前提
重命名	避免手动替换出错
继承成员显示	看清 Qt 类的完整能力

💡 每天按 Alt + 7，玩转strutrue;

👌拓展：快速替换def

1. 连按 两次 Ctrl + W（选中整个函数）
2. Ctrl + V 粘贴新代码
3. （可选）Ctrl + Alt + L 格式化

✅ 完成！缩进完美，无残留。