java2staruml 0.1.0

Parse Java sources: PlantUML class diagrams and StarUML (.mdj) export

java2staruml

将 Java 源码解析为 PlantUML 类图文本，并可选导出 StarUML .mdj 模型（依赖 javalang 做语法解析）。安装后提供命令 java2plantuml 与 java2staruml。

环境要求

• Python：3.11 及以上（含 3.12、更新版本）。pyproject.toml 中为 requires-python = ">=3.11"，3.12 在支持范围内，与本项目所用语法及依赖无已知冲突。
• 仅需解析 .java 源码，不解析 .class 字节码。

安装

从源码目录安装（开发推荐）

在项目根目录（含 pyproject.toml）执行：

pip install -e .

会安装本包，并自动安装依赖（如 javalang）。

从打好的 wheel 安装

pip install dist\java2staruml-0.1.0-py3-none-any.whl

（若你修改了版本号，请把文件名换成 dist 目录里实际的 .whl 名称。）

使用

命令行

安装后可直接使用入口命令（输出完整 PlantUML，含 @startuml / @enduml）：

java2plantuml <路径>

<路径> 可以是单个 .java 文件，或包含多个 .java 的目录（会递归扫描）。

StarUML（.mdj）

java2staruml <路径> [输出.mdj]

详见 java2staruml/README.md。

在代码中调用

from java2plantuml import JavaAnalyzer, JavaProjectAnalyZer, JavaProjectAnalyzer

# 方式一：自行遍历文件
analyzer = JavaAnalyzer()
analyzer.analyze_file(r"C:\path\to\Some.java")
analyzer.analyze_relations()
print(analyzer.pakcages_plantuml)   # 类声明片段
print(analyzer.relations_plantuml)  # 关系（需先 analyze_relations）

# 方式二：分析整个目录
proj = JavaProjectAnalyZer()  # JavaProjectAnalyzer 为同一类的推荐拼写别名
proj.analyze_directory(r"C:\path\to\java\sources")
proj.analyze_relations()
print(proj.pakcages_plantuml)
print(proj.relations_plantuml)

说明：pakcages_plantuml 为历史拼写，与类图里的 packages 同义。

打包发布（生成 wheel / sdist）

在项目根目录执行：

1. 安装构建工具（仅需一次，或每次新环境装一次）：

   pip install build
   

2. 生成发行包（在根目录生成 dist\）：

   python -m build
   

3. 完成后在 dist\ 中会得到：

   • *.whl：可直接 pip install 的轮子包；
   • *.tar.gz：源码发行包（sdist）。

4. 本地验证安装（可选）：

   pip install dist\java2staruml-0.1.0-py3-none-any.whl
   java2plantuml C:\some\java\folder
   

   CLI 需传入恰好一个参数（文件或目录路径）；参数不对时会打印用法说明。

功能与限制

• 支持多文件、简单 package / class / interface / enum / method / field。
• 未来计划：更完善的内部类（inner class）等。

内部结构（PlantUML）

@startuml

' 基本类结构
class BaseJavaClass {
    # name: str
    # modifiers: set[str]
    # fields: list[JavaField]
    # constructors: list[JavaConstructor]
    # methods: list[JavaMethod]
    # extends: str | list[str]
    # implements: list[str]
    # relations: list[str]
    + __init__(declaration: ClassDeclaration, context: JavaClassContext)
    + _parse_fields()
    + _parse_constructors()
    + _parse_methods()
    + parse_relationships()
}

class JavaClass {
    + __str__()
}
JavaClass --|> BaseJavaClass

class JavaInterface {
    + __str__()
}
JavaInterface --|> BaseJavaClass

class JavaEnum {
    - constants: list[str]
    + __str__()
}
JavaEnum --|> BaseJavaClass

' 辅助工具类
class Java2PlantUMLTool {
    {static} _VISIT_MODIFIERS_SYMBOL: dict
    {static} _OTHER_MODIFIERS_SYMBOL: dict
    {static} print_modifiers(modifiers: set[str] | str)
}

enum UMLRelationship {
    INNER = "-+"
    DEPEND = ".>"
    ASSOCIATE = "->"
    IMPLEMENT = ".|>"
    EXTEND = "-|>"
}

' 字段和方法相关
class JavaField {
    - name: str
    - type: str
    - modifiers: set[str]
    - documentation: str
    + __str__()
    {static} resolve_fields(declaration: FieldDeclaration)
}

class JavaFormalParameter {
    - name: str
    - type: str
    - varargs: bool
    + __str__()
}

class BaseJavaMethod {
    - name: str
    - modifiers: set[str]
    - return_type: str
    - parameters: list[JavaFormalParameter]
    + __str__()
    - _strategy_parse_dependencies(context: JavaClassContext)
}

class JavaMethod {
    + parse_dependencies()
    + __str__()
}
JavaMethod --|> BaseJavaMethod

class JavaConstructor {
    + parse_dependencies()
    + __str__()
}
JavaConstructor --|> BaseJavaMethod

' 包和上下文管理
class JavaPackage {
    - name: str
    - classes: dict[str, JavaClass | JavaInterface | JavaEnum]
    + parse(declarations: list)
    + parse_relations()
}

class JavaClassContext {
    - class_package_dict: dict[str, str]
    + get_full_class_path(class_name: str)
}

' 核心分析器
class JavaAnalyzer {
    - __packages: dict[str, JavaPackage]
    + analyze_file(filepath: str)
    + analyze_relations()
    + print_packages()
}

' 类型处理
class JavaType {
    {static} resolve_type(type_node)
}

' 依赖关系
JavaAnalyzer -> JavaPackage
JavaPackage "1" *--> "0..*" JavaClass
JavaPackage "1" *--> "0..*" JavaInterface
JavaPackage "1" *--> "0..*" JavaEnum

BaseJavaClass o--> JavaField
BaseJavaClass o--> JavaMethod
BaseJavaClass o--> JavaConstructor
BaseJavaClass o--> JavaClassContext

JavaMethod o--> JavaFormalParameter
JavaConstructor o--> JavaFormalParameter

JavaMethod ..> JavaType : uses
JavaField ..> JavaType : uses
JavaFormalParameter .left.> JavaType : uses

BaseJavaClass .left.> Java2PlantUMLTool : uses
JavaMethod .up.> Java2PlantUMLTool : uses
JavaConstructor .up.> Java2PlantUMLTool : uses
JavaField .up.> Java2PlantUMLTool : uses
JavaFormalParameter .up.> Java2PlantUMLTool : uses

BaseJavaClass .left.> UMLRelationship : uses
JavaMethod .> UMLRelationship : uses
JavaConstructor .> UMLRelationship : uses

@enduml