在文档中嵌入正确的UML图表
代理经常被要求为文档“添加图表” —— 但它们常常在建模上出现细微错误(无效多重性、箭头反向、继承方向错误),或是返回一个从未渲染成图片的代码块。此技能可生成正确的类图和真正的可嵌入图像。
范围
- 仅限类图 —— 目前支持类、属性、关联、多重性、继承。其他UML图类型(状态机、对象、序列、活动等)不在此技能范围内。
- 始终通过BESSER B-UML实现。 每个图表都首先构建为B-UML
DomainModel,然后再交付。通过模型构建才能确保图表正确且可作为代码重用。
可以从哪里开始
- 一段描述 —— 用户解释领域;代理编写模型。
- 现有代码 —— 代理读取源代码并根据其结构构建B-UML模型。(没有自动代码扫描器;代理根据读取的内容进行建模 —— 它不是一键导入器。)
- 受支持的转换为B-UML的路径 —— PlantUML、Draw.io或UI原型。
两种交付方式
一次建模,然后作为嵌入式B-UML代码(交付A)或渲染图像(交付B)交付 —— 两者基于同一个模型,因此永远不会不一致。根据上下文选择(应保持可运行的设计文档 → 代码;应显示图片的README → 图像),或两者都提供。详情见下方交付章节。
图表放置位置。 如果用户指定了目标文档(README、设计文档),则嵌入到该文件中。如果未指定 —— 或要求为仓库/系统生成独立图表 —— 则默认交付一个新的自包含的.md(例如 docs/<model>.md):包含渲染图像(交付B)和/或B-UML代码(交付A),以及一两行解释图表内容的说明。这样可以将“绘制我的仓库图表”这样的需求转化为一个可提交的文档,而不是一个松散的SVG。当创建新文件时,告知放置位置(并主动提供替代方案 —— 改为嵌入到现有文档中 —— 如果这可能是用户想要的)。
工作流程
1. 构建B-UML模型 —— 从描述、代理读取的现有代码,或通过受支持的转换为B-UML的路径(PlantUML / Draw.io / 原型)
2. model.validate() → 确认模型结构正确
然后交付其一(或两者):
A) 嵌入代码: 将DomainModel Python代码放入.md的围栏代码块中
B) 嵌入图像: 将模型POST到BESSER的无头SVG端点(一次HTTP调用 —— 无需浏览器),
保存返回的SVG(例如 docs/img/data-model.svg),
嵌入 
3. 当模型变更时,更新模型并重新交付 —— 单一真理之源
1. 构建模型
正确的图表始于正确的模型。最小示例如下:
from besser.BUML.metamodel.structural import (
DomainModel, Class, Property, Multiplicity,
BinaryAssociation, Generalization, StringType, IntegerType,
)
publication = Class(name="Publication", attributes={Property(name="title", type=StringType)})
book = Class(name="Book", attributes={Property(name="pages", type=IntegerType)})
author = Class(name="Author", attributes={Property(name="name", type=StringType)})
book_is_a = Generalization(general=publication, specific=book) # Book is a Publication
# A Book is written by 1..* Authors; an Author writes 0..* Books
written_by = Property(name="writtenBy", type=author, multiplicity=Multiplicity(1, "*"))
writes = Property(name="writes", type=book, multiplicity=Multiplicity(0, "*"))
book_author = BinaryAssociation(name="book_author", ends={written_by, writes})
model = DomainModel(
name="Library",
types={publication, book, author},
associations={book_author},
generalizations={book_is_a},
)
assert model.validate()["success"]
命名:无空格,无连字符。对于超出此最小形状的所有内容 —— 枚举、所有多重性/组合模式、关联类、泛化集、方法、验证细节 —— 请阅读**references/class-diagram.md**(随此技能捆绑)。对于非类模型类型(对象、特征、部署、OCL等),请参阅BESSER平台的besser-user技能。
可导入形式 —— 两种交付路径均必需。 将每个
Class(...)、BinaryAssociation(...)和Generalization(...)编写为显式的顶级赋值语句,完全如上所示。BESSER的导入器(由SVG端点和编辑器导入功能使用)读取文件的结构 —— 它不会执行文件 —— 因此在辅助函数或循环中构建的关系是不可见的:类会被导入但关联会无声消失。每个关系使用一个字面语句。由于导入器从不运行文件,
model.validate()在渲染路径上不会被执行 —— 您无需安装BESSER即可通过端点渲染。在您确实本地安装了BESSER时(以及在生成代码之前)保留validate()调用;对于端点而言它是空操作,而不是要求。
模型来源:
- 从描述构建 —— 按如上方式编写。
- 从现有代码构建 —— 读取源代码并将其结构(类、字段、关系、继承)转换为B-UML模型。代理负责建模;没有自动代码扫描器。
- 从PlantUML / Draw.io / UI原型 —— 使用匹配的转换为B-UML的转换(可通过BESSER平台获得),然后继续。
现在以两种方式之一交付。
交付A —— 在文档中嵌入B-UML代码
将模型直接放入.md文件的围栏```python代码块中。它是正确的、经过validate()检查的、可重新运行的,并且可导入到编辑器中。最适合文档本身需要携带模型的情况(设计文档、规范):
## 数据模型
```python
# (上面的DomainModel)
```
此B-UML模型是该领域的真理之源 —— 经过`validate()`检查,并且是任何BESSER生成器的输入。
交付B —— 嵌入渲染图像
模型通过BESSER的渲染器变成真正的图片,因此图像始终与模型匹配。两种方式 —— 根据您是希望自动完成还是手动调整来选择。
B1. 自动渲染(默认)—— 一次HTTP调用,无需浏览器
BESSER暴露了一个无头的B-UML → SVG端点。代理POST模型的.py文件并获取SVG返回 —— 无需编辑器、无需手动操作、用户无需点击任何东西:
curl -X POST https://editor.besser-pearl.org/besser_api/get-svg \
-F "[email protected];type=text/x-python" \
-o docs/img/data-model.svg
端点解析B-UML,自动布局,并返回image/svg+xml。将其保存到仓库并嵌入:

- 模型文件必须是可导入形式(参见§1中的说明)—— 即编辑器导入的相同形式。仅限类图。
- 布局是自动的。当布局位置很重要时,使用B2手动调整。
- 将
.py保存为无BOM的UTF-8 —— 前导字节顺序标记会使端点拒绝文件(HTTP 400)。 - 在您在此渲染的模型中省略枚举字面量
default_value=...—— 端点当前会因此失败(HTTP 500)。它对于代码生成是没问题的;将普通枚举用作属性类型可以正常渲染。 - 非200响应是小的JSON错误,而不是SVG(
{ "detail": ... })—— 在保存前检查状态。
B2. 从编辑器手动调整导出(当布局重要时)
打开 https://editor.besser-pearl.org ,导入.py(选择B-UML格式),拖拽框和路由线以达到理想效果,然后导出并选择格式:
- SVG —— 在任何尺寸下都清晰;最适合文档和Web。
- PNG —— 透明背景。
- PNG(白色背景) —— 适用于需要不透明图像的表面。
保存到仓库并以相同方式嵌入。(编辑器还可以将模型导出为B-UML或JSON —— 这些是模型本身,而非图像。)
无论哪种方式,SVG和PNG在所有支持Markdown图像的地方都能渲染 —— GitHub、GitLab、文档站点、Wiki、幻灯片 —— 无需插件。
防止漂移
无论选择哪种模式,模型都是真理之源。当需求变更时,更新模型并重新交付(重新粘贴代码,或重新导出图像)—— 切勿手动编辑导出的SVG/PNG,它是生成的。
超越图片的价值
由于图表是真正的B-UML模型,同一件制品可以生成可工作的代码 —— Python类、SQL、FastAPI后端、Django、React等。为解释系统而绘制的图表可以变成系统本身。要从中生成代码,请参考besser-generators技能。
何时使用相关技能
- 深入构建模型(枚举、继承、方法、OCL、对象/特征/部署/神经网络/量子模型)→ besser-user技能。
- 从模型生成代码 → besser-generators技能。
- 错误(导入/验证/编辑器问题)→ besser-troubleshooting技能。