将SwiftPlantUML集成进你的Swift项目Framework API调用完全指南【免费下载链接】SwiftPlantUMLA command-line tool and Swift Package for generating class diagrams powered by PlantUML项目地址: https://gitcode.com/gh_mirrors/sw/SwiftPlantUMLSwiftPlantUML是一款基于 PlantUML 的命令行工具与 Swift Package只需一行调用就能把 Swift 源码自动转换成清晰的 UML 类图。本文面向新手带你快速完成 SwiftPlantUML Framework 的集成学会用ClassDiagramGenerator和Configuration两个核心 API 在 Swift 项目中生成类图几乎不需要手写任何 PlantUML 脚本。一、SwiftPlantUML 是什么为什么需要它简单来说SwiftPlantUML 帮你自动读取 Swift 源码识别其中的class、struct、protocol、enum、extension连同成员变量、函数以及继承、实现关系一起画成一张类图。它的两个使用形态形态说明CLI 命令行一条命令生成并在浏览器打开类图适合日常快速查看Swift PackageFramework以库的形式集成进你的项目用 API 精确控制生成过程适合自动化、CI 和自定义工具本文聚焦后者——Framework API 集成。它依赖 Apple 的 SourceKit 做语法解析能准确理解类型推断例如var hasBasket false会被识别为Bool需传入 SDK 路径。二、三步把 SwiftPlantUML 加入你的项目添加依赖在项目的Package.swift中加入对SwiftPlantUML包的依赖声明方式可参考 Package.swift。产品名为库SwiftPlantUMLFramework注意该项目尚未到达 1.0 大版本建议用.upToNextMinor或.exact锁定版本以防 API 变动。声明 target 依赖在需要生成类图的 target 中引用SwiftPlantUMLFramework这个 product。import 即可使用import SwiftPlantUMLFramework核心入口ClassDiagramGenerator立刻可用。 平台要求macOS 10.11 及以上。三、核心入口ClassDiagramGenerator整个 Framework 围绕 ClassDiagramGenerator.swift 展开它提供两条主路径// 方式1从磁盘上的 Swift 文件支持目录递归 generator.generate(for: paths, with: configuration, presentedBy: presenter, sdkPath: sdkPath) // 方式2直接传入 Swift 代码字符串 generator.generate(from: swiftCodeString, with: configuration, presentedBy: presenter)几个新手最常问的参数paths文件/目录路径数组目录会递归查找 Swift 文件configuration控制画什么、怎么画默认.default即可出图presenter决定结果输出到哪里默认在浏览器中打开sdkPathmacOS SDK 路径如xcrun --show-sdk-path -sdk macosx传了它类型推断的变量才能显示准确类型。内部流程其实很透明FileCollector收集文件 →SyntaxStructure解析语法树 → PlantUMLScript.swift 组装出startuml ... enduml脚本文本 → 交给 presenter 展示。四、控制图表长相Configuration 配置指南所有配置项都集中在 Configuration.swift且与配置文件.swiftplantuml.yml的选项一一对应——命令行时代积累的配置知识可以直接迁移到 API 调用上。4.1 过滤文件FileOptionsvar config Configuration( files: FileOptions(include: [Sources/**/*.swift], exclude: [Tests/**/*.swift]) )FileOptions.swift 支持通配符exclude优先于include。4.2 过滤元素ElementOptionsElementOptions.swift 让你精确到类成员级别选项作用典型场景havingAccessLevel只显示指定访问级别的类型只画public/open的对外 APIshowMembersWithAccessLevel只显示指定级别的成员隐藏内部实现细节showExtensions隐藏 / 合并 / 完整展示扩展合并后图更干净且不丢信息exclude按名称通配排除元素用*Test*隐藏测试类showGenerics是否显示泛型约束快速概览时关闭 小建议给外部用户看 API 文档图时havingAccessLevel: [.open, .public]是一张非常干净的图。4.3 样式与主题skinparamCommands透传任意 PlantUML skinparam 指令改颜色、字体theme一键套用主题更多主题示例见 THEMING.mdrelationships、stereotypes控制关系线样式与类型标记如«class»、«protocol»。五、结果去哪了两种 Presenter 输出方式输出由 PlantUMLPresenting.swift 协议定义项目内置两个现成实现PlantUMLBrowserPresenter默认把脚本编码后在浏览器打开支持.png、.svg或可编辑脚本图格式见 PlantUMLBrowserPresenter.swiftPlantUMLConsolePresenter把 PlantUML 脚本文本打印到控制台适合在工具或 CI 里收集脚本见 PlantUMLConsolePresenter.swift。更妙的是拿到PlantUMLScript后你可以直接调用script.text拿到完整脚本或encodeText()得到压缩编码——协议是开放的你也可以自己实现一个 Presenter比如写入文件、发送到 IM。六、完整调用示例从代码到类图把上面串起来一个最小可用的集成示例import SwiftPlantUMLFramework let generator ClassDiagramGenerator() let config Configuration( files: FileOptions(include: [Sources/**/*.swift]), elements: ElementOptions(havingAccessLevel: [.open, .public]) ) generator.generate( for: [Sources], with: config, presentedBy: PlantUMLBrowserPresenter() )运行后浏览器即打开一张只含公开 API 的 Swift 类图效果类似文首的示例图。七、新手常见坑位速查问题解决办法报错sourcekitd.framework加载失败检查xcode-select -p指向的 Xcode 是否含 Swift 工具链变量类型显示缺失传入sdkPath参数启用类型推断解析图太乱配置showExtensions: .merged、排除*Test*、只保留public级别升级后 API 变动项目未达 1.0依赖请锁定小版本八、总结SwiftPlantUML Framework 的集成路径非常直白加依赖 →ClassDiagramGenerator生成 →Configuration定制 →Presenter输出。配合对 SourceKit 的深度利用它几乎能零成本地为你的 Swift 项目持续产出结构清晰的 UML 类图非常适合写文档、做架构评审或搭建 CI 文档流水线。更多配置示例可参考 Configuration/Examples 目录配置项定义参见 Configuration/Schema/json-schema-swiftplantuml.json。【免费下载链接】SwiftPlantUMLA command-line tool and Swift Package for generating class diagrams powered by PlantUML项目地址: https://gitcode.com/gh_mirrors/sw/SwiftPlantUML创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考