在 Python 中，**获取“本模块的所有属性”是反射机制与信息架构设计中最基础也最容易被忽视的一环**。无论是调试、自动文档生成、插件系统，还是做配置扫描、依赖注入，都离不开对模块自身属性的系统性获取与理解。Python 提供了多种内建机制来完成这件事，但不同方式在“完整性、可控性、语义准确性”上差异显著。**如果不了解这些差异，往往会导致遗漏关键对象或引入不必要的内部属性**。

## 一、为什么要获取本模块的所有属性

在 Python 应用与库开发中，“获取本模块属性”并不是一个单纯的语法问题，而是信息组织和运行时可观测性的问题。一个模块在运行时往往不仅包含函数和类，还包括常量、配置变量、导入对象、魔术属性等。**准确识别哪些属性属于模块“对外语义”，哪些只是运行时噪音，是高质量代码的基础**。

例如在插件系统中，主程序往往需要扫描模块，找出所有符合特定约定的函数或类；在自动化测试或文档工具中，也需要遍历模块属性来生成结构化信息。如果只是简单地“拿到一个列表”，而不理解属性的来源和性质，就容易把 `_` 开头的内部对象、导入的第三方对象一并当成业务对象处理，导致逻辑混乱。因此，在讨论如何获取模块属性之前，**先理解“模块在 Python 中是什么”尤为重要**。

## 二、Python 模块对象的本质与属性来源

从语言层面看，Python 中的模块本身就是一个对象，类型为 `module`。当解释器加载一个 `.py` 文件时，会创建一个模块对象，并将该文件中的所有顶级定义绑定为该模块对象的属性。这些属性主要来源于三类：**模块自身定义的符号、从其他模块导入的符号、解释器自动注入的内建属性**。

自动注入的属性包括 `__name__`、`__file__`、`__package__`、`__doc__` 等，它们用于描述模块的元信息。模块自身定义的属性则是你在文件中直接写下的函数、类和变量。导入属性则来自 `import` 或 `from ... import ...` 语句。**这三类属性在技术上并无区别，但在语义上却完全不同**，因此获取模块所有属性时，必须考虑是否需要区分它们。

## 三、使用 dir() 获取模块的属性列表

最常见、也是初学者最先接触的方法是 `dir()`。在模块内部，直接调用 `dir()` 或 `dir(sys.modules[__name__])`，即可得到当前模块的属性名列表。`dir()` 的优点是简单直观，不需要额外导入或复杂语法，**非常适合交互式探索和调试场景**。

但需要注意的是，`dir()` 返回的是一个“经过排序和过滤的名称列表”，并不保证包含所有真实存在的属性。官方文档明确指出，`dir()` 更偏向“为开发者提供一个有用的属性视图”，而非严格的反射 API。因此，**当你需要完整、可控、可预测的模块属性集合时，仅依赖 dir() 并不稳妥**。

| 方法 | 是否完整 | 是否包含魔术属性 | 适用场景 |
|----|----|----|----|
| dir() | 否 | 部分 | 调试、探索 |
| vars() | 是 | 是 | 程序化处理 |
| __dict__ | 是 | 是 | 底层反射 |

## 四、使用 vars() 精确获取本模块属性

相比 `dir()`，`vars()` 是更严肃、更适合程序逻辑的方法。在模块内部调用 `vars()`，等价于访问当前模块对象的 `__dict__`，返回一个字典，键是属性名，值是属性本身。**这是 Python 官方推荐的反射方式之一**，在语义和行为上都更加明确。

通过 `vars()`，你可以准确区分属性类型，例如筛选出所有函数、类或常量。更重要的是，`vars()` 不会对属性做任何“人为美化”，它反映的是模块对象真实持有的属性集合。因此，在构建插件扫描器、规则引擎或自动注册机制时，**vars() 几乎是事实标准**。

例如，你可以基于 `vars()` 的结果，结合 `callable()`、`isinstance()` 等内建函数，对模块内容进行精细化分类，而不会遗漏动态注入的属性。

## 五、直接访问 __dict__ 的底层方式

`__dict__` 是模块对象存储属性的底层结构，本质上就是一个普通的 Python 字典。访问 `globals()` 或 `sys.modules[__name__].__dict__`，效果与 `vars()` 基本一致。**区别在于可读性和语义表达**：`vars()` 明确表达“我在做反射”，而直接用 `__dict__` 更偏向底层实现细节。

在一些对性能或行为可控性要求极高的框架中，直接操作 `__dict__` 可以避免额外封装带来的不确定性。但对于绝大多数应用来说，**推荐优先使用 vars()，而不是直接依赖 __dict__**，以保持代码的可维护性和可读性。

## 六、结合 inspect 模块进行属性筛选

当“获取本模块所有属性”不仅仅是拿到一个集合，而是要进行**语义级别的分类**时，`inspect` 模块就变得非常重要。`inspect` 是 Python 标准库中用于检查对象类型、来源和结构的权威工具，广泛应用于测试框架和文档生成器中。

通过 `inspect.isfunction()`、`inspect.isclass()` 等方法，你可以从 `vars()` 得到的属性字典中筛选出特定类型的对象。例如，只获取当前模块中定义的函数，而排除从其他模块导入的函数。这在设计公共 API 时尤为关键，因为**导入对象往往不应该被当成本模块的核心能力**。

| 筛选目标 | 推荐方法 | 说明 |
|----|----|----|
| 本模块函数 | inspect.isfunction + __module__ 判断 | 排除外部导入 |
| 本模块类 | inspect.isclass | 构建对象注册表 |
| 常量 | 非 callable 且非模块 | 配置扫描 |

## 七、如何排除不属于本模块的属性

在真实项目中，一个模块往往会导入大量第三方库或其他内部模块。如果直接使用 `vars()`，这些导入对象都会出现在结果中。为了获取“真正属于本模块”的属性，**通常需要结合 `__module__` 属性进行过滤**。

每一个函数和类对象，都有一个 `__module__` 属性，表示其定义所在的模块名。通过判断该值是否等于当前模块的 `__name__`，即可有效排除外部定义的对象。这种方式在语义上非常清晰，也被多个成熟开源项目采用。根据 Python 官方文档（Python Software Foundation，2023），这是识别对象来源的推荐方式之一。

## 八、动态属性与运行时修改的影响

需要特别注意的是，Python 模块的属性是可以在运行时被动态修改的。无论是通过赋值、`setattr()`，还是元编程机制，模块属性都不是静态不变的。**这意味着“获取本模块所有属性”本质上是一个时间点行为，而不是编译期事实**。

在长生命周期进程（如 Web 服务、任务调度器）中，不同时间获取模块属性，结果可能不同。因此，如果你依赖模块属性进行初始化或注册操作，建议在明确的生命周期节点执行，并避免在运行中反复扫描，以减少不可预测性。

## 九、最佳实践总结与未来趋势

综合来看，**获取 Python 本模块所有属性的最佳实践，是以 vars() 为基础，结合 inspect 和 __module__ 进行语义过滤**。`dir()` 适合探索，`__dict__` 适合底层控制，而真正可维护、可扩展的方案，必须建立在对模块对象本质的理解之上。

随着 Python 在大型系统和 AI 工程中的应用不断扩大，模块反射不再只是“高级技巧”，而是基础能力。未来，围绕模块元数据、自动注册和自描述机制的需求只会更多，而不是更少。**理解并正确使用模块属性获取方式，将直接影响系统的可演进性和可观测性**。

参考与资料来源  
Python Software Foundation. Python Documentation – Built-in Functions & inspect module, 2023  
PEP 562 – Module __getattr__ and __dir__, Python Enhancement Proposals, 2019

可以使用内置的`dir()`函数传入`__name__`模块对象，或直接在模块代码中调用`dir()`来获取该模块中所有定义的属性列表，包括变量、函数和类。

使用`dir()`函数查看模块属性

我想知道当前Python模块包含了哪些变量、函数和类，有没有简单的方法可以列出这些属性？

如何查看当前Python模块中定义的所有属性？

模块的很多属性以双下划线`__`开头结尾，这些通常是Python内置的。通过过滤掉这些系统属性，可以更清晰看到自己定义的变量和函数。

过滤内置属性以获取自定义内容

获取模块所有属性时，如何判断哪些是Python自动添加的内置属性，哪些是我定义的变量或函数？

Python中如何区分模块的内置属性和自定义属性？

`globals()`函数返回一个字典，包含当前模块的全局符号表。通过遍历这个字典，可以动态访问和处理模块中所有定义的函数、变量和类。

利用`globals()`轻松获取当前模块内容

有没有办法用Python代码动态地获取当前模块中定义的函数和变量，而不需要手动枚举？

可以通过编程方法动态获取本模块所有函数和变量吗？

PingCodeDocs

本文系统讲解了 Python 中获取本模块所有属性的原理与实践方式，从模块对象的本质出发，详细对比了 dir()、vars() 与 __dict__ 在完整性和语义上的差异，并说明了为什么 vars() 更适合程序化处理。文章进一步结合 inspect 模块，解释了如何筛选真正属于本模块的函数和类，避免将导入对象误判为核心属性。同时强调了模块属性在运行时可变这一特性，对初始化和架构设计的影响。整体给出了可维护、可扩展的最佳实践思路。

python获取本模块的所以属性