Archify 开源项目深度解析：从代码到架构图，一键生成可视化文档

一、项目简介

Archify 是一个开源的架构文档自动生成工具，能够从代码库中自动提取项目结构、模块依赖关系，并生成清晰的可视化架构图。它解决了开发团队在项目迭代过程中文档滞后、架构图手工绘制耗时且容易过时的问题。通过 Archify，开发者可以将代码仓库直接转化为易于阅读的架构文档，让新成员快速上手、让团队对系统全貌保持一致的认知。

项目地址：GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence,>pip install archify

方式二：从源码安装

git clone https://github.com/tt-a1i/archify.git cd archify pip install -e .

安装完成后，验证是否安装成功：

archify --version

如果输出版本号，说明安装成功。

四、快速上手

4.1 基本用法

进入你的项目根目录，执行以下命令即可生成架构图：

cd /path/to/your/project archify scan --output architecture.md

执行后，会在当前目录生成architecture.md文件，其中包含 Mermaid 格式的架构图，可以直接在 GitHub、GitLab 或支持 Mermaid 的编辑器中渲染查看。

4.2 指定输出格式

Archify 支持多种输出格式，通过--format参数指定：

# 导出为 Mermaid 格式（默认） archify scan --format mermaid --output arch.md 导出为 Graphviz DOT 格式 archify scan --format dot --output arch.dot 导出为 PNG 图片（需要安装 Graphviz） archify scan --format png --output arch.png

4.3 自定义扫描范围

通过--include和--exclude参数控制扫描范围：

# 只扫描 src 和 lib 目录，排除测试和文档目录 archify scan --include src,lib --exclude tests,docs,node_modules

五、配置文件详解

在项目根目录创建archify.yaml配置文件，可以实现更精细的控制：

# archify.yaml project: name: "MyProject" language: "python" # 可选：python, javascript, java, go 等 scan: include: - "src/" - "lib/" exclude: - "tests/" - "node_modules/" - "vendor/" - "*.pyc" output: format: "mermaid" # mermaid, dot, plantuml, png, svg path: "./docs/architecture.md" max_depth: 5 # 依赖图最大深度 rules: max_cycle_depth: 3 # 循环依赖检测阈值 highlight_utils: true # 是否高亮工具类/通用模块

使用配置文件执行扫描：

archify scan --config archify.yaml

六、编程式 API 使用

除了命令行，Archify 也提供了 Python API，方便集成到自动化脚本或 CI/CD 流水线中：

from archify import Scanner, Exporter 初始化扫描器 scanner = Scanner( project_path="./my-project", include=["src/", "lib/"], exclude=["tests/", "node_modules/"] ) 执行扫描，获取架构数据 architecture = scanner.scan() 打印模块依赖关系 print(f"发现 {len(architecture.modules)} 个模块") print(f"发现 {len(architecture.dependencies)} 条依赖关系") 导出为 Mermaid 格式 exporter = Exporter(architecture) mermaid_code = exporter.to_mermaid() with open("architecture.md", "w") as f: f.write("mermaid\n") f.write(mermaid_code) f.write("\n") 导出为 PNG 图片 exporter.to_png("architecture.png")

七、实战案例：一个典型 Web 项目的架构分析

7.1 项目背景

假设我们有一个基于 Flask 的电子商务后端项目，目录结构如下：

ecommerce/ ├── app/ │ ├── __init__.py │ ├── models/ │ │ ├── user.py │ │ ├── product.py │ │ └── order.py │ ├── services/ │ │ ├── user_service.py │ │ ├── product_service.py │ │ └── order_service.py │ ├── api/ │ │ ├── user_api.py │ │ ├── product_api.py │ │ └── order_api.py │ └── utils/ │ ├── validators.py │ └── helpers.py ├── config/ │ └── settings.py ├── tests/ │ └── test_services.py └── requirements.txt

7.2 生成架构图

在项目根目录执行：

archify scan --include app --exclude tests --format mermaid --output docs/architecture.md

7.3 生成的架构图示例

Archify 会自动分析各模块之间的 import 关系，生成如下 Mermaid 架构图：

graph TD api_user["api/user_api.py"] --> srv_user["services/user_service.py"] api_user --> utils_val["utils/validators.py"] api_product["api/product_api.py"] --> srv_product["services/product_service.py"] api_order["api/order_api.py"] --> srv_order["services/order_service.py"] srv_user --> model_user["models/user.py"] srv_product --> model_product["models/product.py"] srv_order --> model_order["models/order.py"] srv_order --> model_user srv_order --> model_product srv_user --> utils_val srv_product --> utils_val srv_order --> utils_val model_user --> utils_help["utils/helpers.py"] model_product --> utils_help model_order --> utils_help

7.4 架构分析结果

从生成的架构图中，我们可以清晰看到：

• 分层清晰：API 层 → 服务层 → 模型层，依赖方向符合分层架构原则。
• 工具类复用良好：validators和helpers被多个模块引用，适合作为通用工具库。
• order 模块耦合度较高：order_service同时依赖了user和product两个模型，这在业务上是合理的，但需要关注后续是否会产生循环依赖。

八、集成到 CI/CD 流水线

8.1 GitHub Actions 集成示例

将 Archify 集成到 CI 流程中，在每次 Pull Request 时自动生成架构图，确保架构变更可追溯：

# .github/workflows/archify.yml name: Generate Architecture Diagram on: pull_request: branches: [main] jobs: archify: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: "3.10" - name: Install Archify run: pip install archify - name: Generate Architecture Diagram run: archify scan --format png --output docs/architecture.png - name: Upload Architecture Diagram uses: actions/upload-artifact@v3 with: name: architecture-diagram path: docs/architecture.png

8.2 GitLab CI 集成示例

# .gitlab-ci.yml archify: stage: build image: python:3.10 before_script: - apt-get update && apt-get install -y graphviz - pip install archify script: - archify scan --format png --output docs/architecture.png artifacts: paths: - docs/architecture.png

九、常见问题与排错

9.1 扫描不到任何模块

确认--include参数指向的目录存在且包含源代码文件。如果使用了配置文件，检查scan.include路径是否正确。

9.2 PNG 导出失败

PNG 导出依赖 Graphviz，请确保系统已安装：

# macOS brew install graphviz Ubuntu/Debian sudo apt-get install graphviz Windows 下载安装包：https://graphviz.org/download/

9.3 生成架构图过于复杂

可以通过--max-depth参数限制依赖图深度，或通过--exclude排除工具类、第三方库等非核心模块，使架构图更加聚焦。

9.4 循环依赖误报

有时候__init__.py中的导入会被误判为循环依赖。可以在配置文件中调整rules.max_cycle_depth阈值，或在exclude中排除__init__.py文件。

十、总结与展望

Archify 是一个轻量但实用的架构文档自动化工具，能够有效降低团队维护架构文档的成本。它支持多种输出格式，既可以作为命令行工具手动使用，也可以无缝集成到 CI/CD 流水线中实现自动化。对于追求代码质量和文档规范的中大型项目来说，Archify 是一个值得尝试的开源方案。

未来，Archify 社区计划支持更多语言（如 Rust、Kotlin）、更智能的模块分类算法，以及更丰富的可视化样式定制。如果你对该项目感兴趣，欢迎前往 GitHub 仓库点个 Star，参与贡献或提出你的需求。

项目地址：GitHub - tt-a1i/archify: Agent skill for beautiful, verifiable architecture, workflow, sequence, data-flow, and lifecycle diagrams—self-contained HTML with motion and crisp export. · GitHub