灵码产品演示：软件工程架构分析
作者：了哥
演示目的
-
演示灵码对于整个复杂软件工程项目的架构分析能力，输出项目的软件系统架构图。
-
演示文档接口生成能力。
演示准备
- 克隆工程地址到本地（需提前安装好 git 工具， 建议本地配置 brew）：
git clone https://github.com/duffqiu/bookinfo.git
（为了体现不是模型已有的知识，所以有些更改。）
-
安装最新的 VS Code：https://code.visualstudio.com/
-
在 VS Code 的插件市场安装最新的灵码插件
备注：也可以直接使用灵码 IDE（https://lingma.aliyun.com/download）
- 在 VS Code 的插件市场安装最新的 plantuml 插件（需要配置更新最新的 plantuml 的 jar 包，这个配置自行搜索，这里不做过多介绍）。或者直接使用 plantuml 的 web 页面：https://www.plantuml.com/plantuml/
演示步骤
- 在 VS Code 里打开工程的目录
- 打开灵码，使用 agent 模式，模型选择“qwen3-code”
- 开始分析工程
输入 prompt：
“请详细分析下工程，并用plantuml给出系统架构图的描述”
得到一个分析后的架构描述的 plantuml 文件：
- 打开文件，然后用 plantuml 插件展示图
最后得到一个工程的架构视图：新版的 Qwen3 Coder 模型。
- 调整架构图，输入 prompt
“请只保留微服务和数据层”
然后得到新的 plantuml 文件，并通过插件展示得到：最新 Qwen3 coder 的模型效果。
- 再深度分析微服务间的交互
Prompt：
请用plantuml画出各个微服务交互的时序图，输出到文件action.uml
这个时候可能没有分析出 reviews 这个微服务不同的版本的情况，所以再深入和模型交互。
Prompt：
需要增加描述不同的reviews版本的处理过程
最后得到微服务的时序交互图。
- 分析具体的 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-idx-b3-traceidx-b3-spanidx-b3-parentspanidx-b3-sampledx-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) - 产品IDstarsReviewer1(int) - 评论者1的星级评分，-1表示无评分starsReviewer2(int) - 评论者2的星级评分，-1表示无评分
返回值:- String - 包含评论信息的JSON字符串
说明:
此方法根据传入的参数构造JSON格式的响应，包含产品ID、Pod名称、集群名称以及两个预设评论。根据评分是否启用以及评分值是否有效，决定是否在响应中包含评分信息。
2. getRatings方法
功能: 从Ratings服务获取指定产品的评分信息
参数:
productId(String) - 产品IDrequestHeaders(HttpHeaders) - 来自原始请求的HTTP头信息
返回值:- JsonObject - 包含评分信息的JSON对象，如果出现错误则返回null
说明:
此方法使用JAX-RS客户端调用Ratings服务的API。它会传播分布式追踪相关的HTTP头以维持调用链。根据环境变量配置，设置适当的超时时间（黑色星星为10秒，其他为2.5秒）。
3. health方法
功能: 提供健康检查端点
参数:
无
返回值:
- Response - 包含健康状态信息的HTTP响应
说明:
这是一个简单的健康检查端点，始终返回200状态码和健康状态信息。
4. bookReviewsById方法
功能: 根据产品ID获取图书评论
参数:
productId(int) - 产品IDrequestHeaders(HttpHeaders) - 来自原始请求的HTTP头信息
返回值:- Response - 包含产品评论的HTTP响应
说明:
这是主要的业务方法，负责处理获取图书评论的请求。如果启用了评分功能，它会调用getRatings方法获取评分信息，并使用getJsonResponse方法构造最终的响应。
环境变量
ENABLE_RATINGS- 布尔值，用于启用/禁用评分功能STAR_COLOR- 评分星星的颜色（默认：“black”）SERVICES_DOMAIN- 服务发现的域RATINGS_HOSTNAME- 评分服务的主机名（默认：“ratings”）RATINGS_SERVICE_PORT- 评分服务的端口（默认：“9080”）HOSTNAME- Pod主机名CLUSTER_NAME- 集群名称
版本
该服务有三个版本，它们在评分显示上有所不同：
- v1 - 返回不带评分的评论
- v2 - 返回带黑色星星评分的评论
- v3 - 返回带红色星星评分的评论
v3版本实现细节
Reviews v3版本与其他版本共享相同的代码库，但通过环境变量进行配置：
- STAR_COLOR 设置为 “red” 以显示红色星星
- ENABLE_RATINGS 设置为 “true” 以启用评分显示
- 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环境变量决定。
依赖项
- 评分服务（启用时）- 用于检索图书评分
- 各种追踪系统（可选）- 用于分布式追踪
用户可以设置一个自己的模版，然后作为上下文给大模型按照这个模版进行推理。