灵码产品演示：软件工程架构分析

作者：了哥

演示目的

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环境变量决定。

依赖项

• 评分服务（启用时）- 用于检索图书评分

• 各种追踪系统（可选）- 用于分布式追踪

用户可以设置一个自己的模版，然后作为上下文给大模型按照这个模版进行推理。