在你的文件中嵌入正確的 UML 圖表
代理人經常被要求為文件「新增圖表」——但是他們經常會在不經意間把模型弄錯(無效的多重性、箭頭方向相反、繼承關係倒置),或是只提供一個永遠無法渲染成圖片的程式碼區塊。這項技能能產出正確的類別圖以及一個真正可嵌入的圖檔。
範圍
- 僅限類別圖,目前如此——包含類別、屬性、關聯、多重性、繼承。其他 UML 圖表類型(狀態機、物件圖、序列圖、活動圖……)不在本技能範圍內。
- 一律透過 BESSER B-UML。 每個圖表都先被建立成一個 B-UML
DomainModel,然後再進行交付。透過模型來建立,才能確保圖表正確且可以重複利用為程式碼。
可以從哪裡開始
- 一段描述——使用者解釋領域知識;代理人編寫模型。
- 現有程式碼——代理人讀取原始碼並根據其結構建立 B-UML 模型。(沒有自動程式碼掃描器;代理人是透過讀取到的內容來建立模型——它並非一鍵匯入工具。)
- 一個受支援的轉換路徑——PlantUML、Draw.io 或 UI 原型。
兩種交付方式
建立模型一次,然後交付為嵌入的 B-UML 程式碼(交付方式 A)或渲染後的圖片(交付方式 B)——兩者都基於同一個模型,因此它們的內容永遠不會不一致。根據情境選擇(一份設計文件應該保持可執行性 → 選擇程式碼;一份 README 應該顯示圖片 → 選擇圖片),或者兩者都提供。詳情請見下方「交付方式」章節。
圖表放置位置。 如果使用者指定了目標文件(如 README、設計文件),就嵌入到該文件中。如果使用者沒有指定——或者要求為某個儲存庫/系統畫一張獨立的圖表——預設情況下交付一個新的、獨立的 .md 檔案(例如 docs/<model>.md):包含已渲染的圖片(交付方式 B)和/或 B-UML 程式碼(交付方式 A),再加上一兩行文字說明圖表內容。這能將一個單純的「為我的儲存庫畫圖」請求轉變為一個可提交的文件,而非一個鬆散的 SVG。當你建立一個新檔案時,請告知檔案位置(並提供替代方案——改為嵌入到現有文件中——如果這可能更符合使用者的需求)。
工作流程
1. 建立 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 原型——使用對應的轉換工具(可透過 BESSER 平台取得)將其轉換為 B-UML,然後繼續。
現在,用以下兩種方式之一進行交付。
交付方式 A — 在文件中嵌入 B-UML 程式碼
直接將模型放入 .md 檔案中一個以 ```python 標記的程式碼區塊中。它是正確的、經過 validate() 檢查的、可重新執行的,並且可以匯入到編輯器中。最適合當文件本身需要攜帶模型時使用(例如設計文件、規格書):
## 資料模型
```python
# (來自上方的 DomainModel)
```
這個 B-UML 模型是該領域的單一事實來源——已通過 `validate()` 檢查,並且是任何 BESSER 程式碼產生器的輸入。
交付方式 B — 嵌入已渲染的圖片
模型會透過 BESSER 的渲染器變成真正的圖片,因此圖片始終與模型一致。有兩種方式——根據你希望它是全自動的還是可以手動調整來選擇。
B1. 自動渲染(預設方式)——一次 HTTP 呼叫,無需瀏覽器
BESSER 提供了一個無頭的 B-UML → SVG 端點。代理人將模型 .py 檔案 POST 過去,然後收到一個 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——在任何尺寸下都很清晰;最適合文件和網頁。
- PNG——透明背景。
- PNG(白色背景)——用於需要不透明圖片的表面。
將其儲存到儲存庫中,並以相同的方式嵌入。(編輯器也可以將模型匯出為 B-UML 或 JSON ——這些是模型本身,而非圖片。)
無論哪種方式,SVG 和 PNG 都能在所有支援 Markdown 圖片的地方渲染——GitHub、GitLab、文件網站、維基、簡報——無需任何外掛程式。
防止模型與圖片不同步
無論你選擇哪種模式,模型都是單一事實來源。當需求變更時,請更新模型並重新交付(重新貼上程式碼,或重新匯出圖片)——永遠不要手動編輯已匯出的 SVG/PNG,因為它們是產生的。
獲得圖片之外的好處
因為該圖表是一個真正的 B-UML 模型,同一個成品可以產生可運作的程式碼——Python 類別、SQL、FastAPI 後端、Django、React 等等。你用來說明系統而畫的圖表,可以變成系統本身。若要從模型產生程式碼,請參考 besser-generators 技能。
何時使用相關技能
- 深入建立模型(列舉、繼承、方法、OCL、物件圖 / 特徵圖 / 部署圖 / 神經網路 / 量子模型)→ 使用 besser-user 技能。
- 從模型產生程式碼 → 使用 besser-generators 技能。
- 處理錯誤(匯入 / 驗證 / 編輯器問題)→ 使用 besser-troubleshooting 技能。