imjuliengaupin/umlement

## 为何选择 UMLement? 当你接手一个 Python 代码库时，其类结构通常比代码本身更难理解。UMLement 使首次架构性阅读变得更快速。 它的设计目标是： - **快速逆向工程** - 无需复杂配置，即可从 Python 文件或文件夹生成 UML 图 - **可读的图表输出** - 生成 PlantUML 以及可实际用于文档和交接说明的渲染后 SVG 或 PNG 制品 - **实用的本地工具** - 可通过命令行界面或轻量级本地 Web UI 使用 - **刻意保持精简范围** - 专注于核心有用功能，避免功能臃肿

(返回顶部)

## :gear: 功能特性 - [x] **基于 AST 的类发现**：比简单文本解析更可靠地逆向工程 Python 源代码 - [x] **关系提取**：生成继承、组合（`has-a`）和使用关系边 - [x] **导入感知的本地扫描**：自动包含本地导入引用的同级模块 - [x] **紧凑的默认 UML**：通过隐藏 getter/setter 噪音（除非明确请求）生成更清晰的类图 - [x] **自定义 PlantUML 样式**：输出比默认 PlantUML 更简洁 - [x] **SVG 或 PNG 渲染**：生成 PlantUML 模型和一个渲染后的图像制品 - [x] **递归项目扫描**：遍历文件夹以获得更广泛的架构覆盖 - [x] **本地查看器 UI**：预览图表、缩放、适应宽度、拖动平移并打开生成的制品 - [x] **仅模型模式**：当您只需要源模型时，生成 `.puml` 而不渲染图像 - [x] **进度报告**：命令行界面和本地 UI 均显示有用的运行进度

(返回顶部)

## :bulb: 使用场景 **架构发现** - 检查陌生 Python 项目的类结构 - 快速理解继承和对象组合 - 在进行更深层次的重构前创建轻量级架构笔记 **文档与交接** - 为内部文档生成 UML 制品 - 通过结构化视图而非仅文本描述来支持项目交接 - 为 README、文档或作品集讲解捕获有用的图表 **开发者工具工作流** - 递归扫描整个文件夹以获得更广泛的项目上下文 - 仅关注代码库子集时，针对特定文件进行扫描 - 需要进一步手动编辑时，生成 PlantUML 源文件

(返回顶部)

## :rocket: 快速开始 ### 前置条件 - Python 3.10+ - Java - `resources/` 目录中的 PlantUML jar 文件 ### 安装 ``` # 克隆 repo git clone https://github.com/imjuliengaupin/umlement.git cd umlement # 创建虚拟环境并安装依赖项 make setup ``` 将一个 PlantUML jar 文件添加到 `resources/` 目录中，例如： ``` resources/plantuml-mit-1.2023.13.jar ``` 您可以从官方发布页面下载 PlantUML jar 文件： - ### 最快运行 ``` make demo ``` 这将生成： - `models/umlement.puml` - `models/umlement.svg` ### 本地 UI ``` make ui ``` 然后打开： - 对于标准的 README 截图工作流： ``` make ui-demo-image ``` 这将使用一个在干净的本地端口上运行的专用捕获流程，并刷新： - `demo/images/ui-demo.png`

(返回顶部)

## 🏗️ 工作原理 UMLement 遵循一个简单的流程： 1. **验证输入路径** - 接受 Python 文件或文件夹 2. **使用 AST 解析发现类** - 提取类、属性、方法、基类和关系 3. **构建 PlantUML 模型** - 生成所发现结构的 `.puml` 描述 4. **渲染图表** - 使用配置的 PlantUML jar 生成 SVG 或 PNG 5. **本地预览** - 使用 Flask UI 交互式检查生成的制品 ### 输出模型行为 当前默认输出是刻意保持紧凑的： - dunder 方法被隐藏 - getter/setter 方法默认隐藏 - 当需要更完整的成员细节时，可以通过显式选项恢复 getter/setter 方法 这使得默认图表更具可读性，同时保留了返回更详细输出的路径。

(返回顶部)

## 🧪 使用方法 ### 扫描一个或多个文件 ``` python umlement.py file1.py file2.py ``` ### 扫描文件夹 ``` python umlement.py demo/sample_project ``` ### 递归扫描 ``` python umlement.py demo/sample_project --recursive ``` ### 生成 SVG 而非 PNG ``` python umlement.py demo/sample_project --recursive --format svg ``` ### 仅生成 PlantUML 模型 ``` python umlement.py demo/sample_project --recursive --model-only ``` ### 在 UML 模型中显示 getter/setter 方法 ``` python umlement.py demo/sample_project --recursive --show-accessors ``` ### 运行时显示进度 ``` python umlement.py demo/sample_project --recursive --format svg --progress ``` ### 本地 UI 行为说明 浏览器 UI 专为本地运行设计，但有一个浏览器限制值得注意： - **输入路径** 字段是权威的可运行输入 - 文件/文件夹选择器仅预加载名称，因为浏览器无法可靠地暴露真实的绝对本地路径 - 路径仍需手动完成才能开始运行 当前 UI 选项包括： - **递归文件夹扫描**（仅适用于面向文件夹的运行） - **仅模型（跳过图像渲染）** - **显示 getter/setter 方法** - 内置 **图表/模型** 查看器标签页 - 图表缩放和适应控制 - 明暗主题切换 当启用 **仅模型** 时，UI 会自动锁定 **显示 getter/setter 方法** 为开启状态，以使生成的 PlantUML 模型包含访问器行。 一些交互规则也是有意为之的： - **加载演示项目** 会禁用选择器助手直到重置，以便应用程序一次只处于一种输入模式 - 仅文件的助手选择会禁用 **递归文件夹扫描**，因为递归仅适用于文件夹 - 仅模型运行在无图表制品时会自动将查看器切换到 **模型** 标签页

(返回顶部)

## 🎬 演示 ### 本地查看器 UI 本地 UI 最好通过清晰的静态图像展示，因为截图比 GIF 能更好地保持界面质量。  ### 终端工作流 命令行界面演示最好通过动态展示，因为进度输出是产品体验的一部分。 

(返回顶部)

## 💪🏼 质量与可靠性 - **基于 AST 的扫描**：对于 Python 类发现，比仅使用正则表达式的逆向工程更健壮 - **带类型的回归覆盖**：Pytest 和 mypy 是常规验证流程的一部分 - **可复现的演示工作流**：专用的截图捕获保持了 UI/演示资产的一致性 - **务实的范围**：小表面领域、明确的权衡、没有不必要的功能蔓延 有用的开发命令： ``` make setup make test make lint make typecheck make verify make demo make ui make ui-demo-image ``` ### 项目结构 ``` . ├── demo/ # sample project + demo assets ├── models/ # generated PlantUML and rendered artifacts ├── resources/ # PlantUML jar location ├── scripts/ # local demo/screenshot helpers ├── templates/ # Flask UI template ├── tests/ # regression tests ├── ui_app.py # local Flask viewer ├── uml_ast.py # AST-based Python structure extraction ├── uml_generator.py # PlantUML model + diagram generation ├── umlement.py # CLI entrypoint └── umlement_runner.py # reusable programmatic runner ```

(返回顶部)

## :pencil: 许可证 基于 MIT 许可证分发。详情请参阅 `LICENSE` 文件。

(返回顶部)

标签：CLI, JS文件枚举, PlantUML, Python, SOC Prime, TCP SYN 扫描, UML建模, Web UI, WiFi技术, 云安全监控, 云资产清单, 代码分析, 代码可视化, 代码文档, 凭证管理, 域环境探测, 开发工具, 数据管道, 无后门, 本地工具, 架构分析, 浏览器UI, 源代码解析, 类图生成, 自动化payload嵌入, 设计模式, 软件工程, 逆向工具, 逆向工程, 静态分析