作者：了哥

演示目的

1. 演示靈碼對于整個復雜軟件工程項目的架構分析能力，輸出項目的軟件系統架構圖。

2. 演示文檔接口生成能力。

演示準備

1. 克隆工程地址到本地（需提前安裝好 git 工具， 建議本地配置 brew）：

git clone https://github.com/duffqiu/bookinfo.git

（為了體現不是模型已有的知識，所以有些更改。）

2. 安裝最新的 VS Code：https://code.visualstudio.com/

3. 在 VS Code 的插件市場安裝最新的靈碼插件

備注：也可以直接使用靈碼 IDE（https://lingma.aliyun.com/download）

4. 在 VS Code 的插件市場安裝最新的 plantuml 插件（需要配置更新最新的 plantuml 的 jar 包，這個配置自行搜索，這里不做過多介紹）。或者直接使用 plantuml 的 web 頁面：https://www.plantuml.com/plantuml/

演示步驟

1. 在 VS Code 里打開工程的目錄

2. 打開靈碼，使用 agent 模式，模型選擇“qwen3-code”

3. 開始分析工程

輸入 prompt：

“請詳細分析下工程，并用plantuml給出系統架構圖的描述”

得到一個分析后的架構描述的 plantuml 文件：

4. 打開文件，然后用 plantuml 插件展示圖

最后得到一個工程的架構視圖：新版的 Qwen3 Coder 模型。

5. 調整架構圖，輸入 prompt

“請只保留微服務和數據層”

然后得到新的 plantuml 文件，并通過插件展示得到：最新 Qwen3 coder 的模型效果。

6. 再深度分析微服務間的交互

Prompt：

請用plantuml畫出各個微服務交互的時序圖，輸出到文件action.uml

這個時候可能沒有分析出 reviews 這個微服務不同的版本的情況，所以再深入和模型交互。

Prompt：

需要增加描述不同的reviews版本的處理過程

最后得到微服務的時序交互圖。

7. 分析具體的 API

打開工程里的 java 文件：

選擇這個文件作為上下文。

Prompt：

請給這個文件創建接口文檔

這樣模型會輸出一個類似下面的文檔：

REVIEWS_API.md：

# Reviews服務API文檔
Reviews服務是Bookinfo應用程序中的一個微服務，用于提供圖書評論。它有多個版本（v1、v2、v3），這些版本在評分顯示方式上有所不同。
## 基礎URL

http://reviews:9080

## 端點
### 1. 健康檢查
#### GET `/health`
返回服務的健康狀態。
**響應:**
```json
{
  "status": "Reviews is healthy"
}

響應碼:

• 200 OK - 服務健康

2. 獲取圖書評論

GET /reviews/{productId}

返回特定產品的評論以及評分（如果啟用）。
路徑參數:

• productId (整數) - 要獲取評論的產品ID
  請求頭:
  該服務傳播多個用于分布式追蹤的請求頭:
• x-request-id
• x-b3-traceid
• x-b3-spanid
• x-b3-parentspanid
• x-b3-sampled
• x-b3-flags
• 以及其他追蹤請求頭（Datadog、Lightstep等）
  響應:

{
  "id": "0",
  "podname": "reviews-v1-7b4f5bd5c-2xk9m",
  "clustername": "cluster-1",
  "reviews": [
    {
      "reviewer": "Reviewer1",
      "text": "An extremely entertaining play by Shakespeare. The slapstick humour is refreshing!",
      "rating": {
        "stars": 5,
        "color": "black"
      }
    },
    {
      "reviewer": "Reviewer2",
      "text": "Absolutely fun and entertaining. The play lacks thematic depth when compared to other plays by Shakespeare.",
      "rating": {
        "stars": 4,
        "color": "black"
      }
    }
  ]
}

說明:

• 當評分為禁用狀態時，響應中將不包含rating對象
• 當評分服務不可用時，評分對象將包含一個錯誤：

  "rating": {
    "error": "Ratings service is currently unavailable"
  }
  

• 星星的顏色因版本而異：
  • v1: 不顯示評分
  • v2: 黑色星星
  • v3: 紅色星星
    響應碼:
• 200 OK - 成功獲取評論
• 500 Internal Server Error - 獲取評分或其他內部錯誤

方法說明

1. getJsonResponse方法

功能: 生成圖書評論的JSON響應字符串
參數:

• productId (String) - 產品ID
• starsReviewer1 (int) - 評論者1的星級評分，-1表示無評分
• starsReviewer2 (int) - 評論者2的星級評分，-1表示無評分
  返回值:
• String - 包含評論信息的JSON字符串
  說明:
  此方法根據傳入的參數構造JSON格式的響應，包含產品ID、Pod名稱、集群名稱以及兩個預設評論。根據評分是否啟用以及評分值是否有效，決定是否在響應中包含評分信息。

2. getRatings方法

功能: 從Ratings服務獲取指定產品的評分信息
參數:

• productId (String) - 產品ID
• requestHeaders (HttpHeaders) - 來自原始請求的HTTP頭信息
  返回值:
• JsonObject - 包含評分信息的JSON對象，如果出現錯誤則返回null
  說明:
  此方法使用JAX-RS客戶端調用Ratings服務的API。它會傳播分布式追蹤相關的HTTP頭以維持調用鏈。根據環境變量配置，設置適當的超時時間（黑色星星為10秒，其他為2.5秒）。

3. health方法

功能: 提供健康檢查端點
參數:
無
返回值:

• Response - 包含健康狀態信息的HTTP響應
  說明:
  這是一個簡單的健康檢查端點，始終返回200狀態碼和健康狀態信息。

4. bookReviewsById方法

功能: 根據產品ID獲取圖書評論
參數:

• productId (int) - 產品ID
• requestHeaders (HttpHeaders) - 來自原始請求的HTTP頭信息
  返回值:
• Response - 包含產品評論的HTTP響應
  說明:
  這是主要的業務方法，負責處理獲取圖書評論的請求。如果啟用了評分功能，它會調用getRatings方法獲取評分信息，并使用getJsonResponse方法構造最終的響應。

環境變量

• ENABLE_RATINGS - 布爾值，用于啟用/禁用評分功能
• STAR_COLOR - 評分星星的顏色（默認："black"）
• SERVICES_DOMAIN - 服務發現的域
• RATINGS_HOSTNAME - 評分服務的主機名（默認："ratings"）
• RATINGS_SERVICE_PORT - 評分服務的端口（默認："9080"）
• HOSTNAME - Pod主機名
• CLUSTER_NAME - 集群名稱

版本

該服務有三個版本，它們在評分顯示上有所不同：

1. v1 - 返回不帶評分的評論
2. v2 - 返回帶黑色星星評分的評論
3. v3 - 返回帶紅色星星評分的評論

v3版本實現細節

Reviews v3版本與其他版本共享相同的代碼庫，但通過環境變量進行配置：

1. STAR_COLOR 設置為 "red" 以顯示紅色星星
2. ENABLE_RATINGS 設置為 "true" 以啟用評分顯示
3. SERVICE_VERSION 設置為 "v3"
   在Kubernetes部署配置中，reviews-v3部署使用以下配置：

• 鏡像: docker.io/istio/examples-bookinfo-reviews-v3:1.18.0
• 環境變量:
  • STAR_COLOR="red"
  • ENABLE_RATINGS="true"
  • LOG_DIR="/tmp/logs"
    v3版本的主要特點是在評論中顯示紅色星星評分，這通過STAR_COLOR環境變量控制。當ENABLE_RATINGS設置為true時，服務會調用Ratings服務獲取評分數據，并在響應中包含評分信息，其中星星顏色由STAR_COLOR環境變量決定。

依賴項

• 評分服務（啟用時）- 用于檢索圖書評分
• 各種追蹤系統（可選）- 用于分布式追蹤

用戶可以設置一個自己的模版，然后作為上下文給大模型按照這個模版進行推理。