21、微服务追踪与API可视化全解析

最新推荐文章于 2025-10-08 03:25:10 发布

z2a3b4c5d

最新推荐文章于 2025-10-08 03:25:10 发布

阅读量47

点赞数

CC 4.0 BY-SA版权

分类专栏： Quarkus微服务实战文章标签：微服务追踪 API可视化 OpenAPI

本文链接：https://blog.youkuaiyun.com/z2a3b4c5d/article/details/152502521

Quarkus微服务实战专栏收录该内容

25 篇文章 ¥499.90

订阅专栏¥69.90

会员秒杀 ¥9.9 重磅福利

超级会员免费看

微服务追踪与API可视化全解析

1. 应用追踪定制

在应用开发中，定制追踪功能能够帮助我们更精准地监控和分析系统的运行状态。下面将详细介绍如何通过注入追踪器、追踪数据库调用以及追踪Kafka消息来实现应用追踪的定制。

1.1 注入追踪器

为了进一步定制追踪功能，我们可以注入 Tracer 实例，通过API与追踪和跨度进行交互。以下是修改 AccountResource.withdrawal 方法以注入追踪器的示例代码：

public class AccountResource {
  @Inject
  Tracer tracer;        
  public CompletionStage<Account> withdrawal(@PathParam("accountNumber") Long accountNumber, String amount) {
    ...
    tracer.activeSpan().setTag("accountNumber", accountNumber);       
    tracer.activeSpan().setBaggageItem("withdrawalAmount", amount);   
    ...
  }
}

操作步骤如下：
1. 修改代码：按照上述代码示例修改 AccountResource.withdrawal 方法。
2. 重新部署：重新部署 Account 服务。
3. 发起请求：使用以下命令从账户中取款：

curl -H "Content-Type: application/json" -X PUT -d "950.00" ${TRANSACTION_URL}/transactions/87878787/withdrawal

查看追踪信息：在浏览器中重新加载Jaeger控制台，搜索 account-service 追踪，并选择最新的追踪以查看详细信息。

1.2 追踪数据库调用

了解特定方法的执行时间对于诊断性能问题很重要，但当方法与其他方法或服务（如数据库）交互时，仅仅知道执行时间是不够的。为了追踪数据库交互，我们需要进行以下修改：
1. 添加依赖：在 pom.xml 中添加以下依赖：

<dependency>
  <groupId>io.opentracing.contrib</groupId>
  <artifactId>opentracing-jdbc</artifactId>
</dependency>

修改配置：在 application.properties 中进行以下配置：

%prod.quarkus.datasource.db-kind=postgresql
%prod.quarkus.datasource.username=quarkus_banking
%prod.quarkus.datasource.password=quarkus_banking
%prod.quarkus.datasource.jdbc.url=jdbc:tracing:postgresql://postgres.default:5432/quarkus_banking   
%prod.quarkus.datasource.jdbc.driver=io.opentracing.contrib.jdbc.TracingDriver
%prod.quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQL10Dialect

重新部署：重新部署服务。
发起请求：使用以下命令从账户中取款：

curl -H "Content-Type: application/json" -X PUT -d "900.00" ${TRANSACTION_URL}/transactions/987654321/withdrawal

查看追踪信息：在浏览器中返回Jaeger控制台，搜索 account-service ，将看到一个新的追踪，其中 account-service 的跨度数量从1增加到3。

1.3 追踪Kafka消息

目前，JAX - RS资源方法和数据库调用有一些跨度，但Kafka消息的生产和消费没有追踪信息。为了追踪Kafka消息，我们需要进行以下操作：
1. 添加依赖：在 pom.xml 中为 Account 服务和 Overdraft 服务添加以下依赖：

<dependency>
  <groupId>io.opentracing.contrib</groupId>
  <artifactId>opentracing-kafka-client</artifactId>
  <version>0.1.15</version>
</dependency>

修改配置：在 application.properties 中为 Account 服务和 Overdraft 服务进行以下配置：

# Account服务配置
mp.messaging.outgoing.account-overdrawn.interceptor.classes=io.opentracing.contrib.kafka.TracingProducerInterceptor    
mp.messaging.incoming.overdraft-update.interceptor.classes=io.opentracing.contrib.kafka.TracingConsumerInterceptor   

# Overdraft服务配置
mp.messaging.incoming.account-overdrawn.interceptor.classes=io.opentracing.contrib.kafka.TracingConsumerInterceptor
mp.messaging.outgoing.overdraft-fee.interceptor.classes=io.opentracing.contrib.kafka.TracingProducerInterceptor
mp.messaging.outgoing.overdraft-update.interceptor.classes=io.opentracing.contrib.kafka.TracingProducerInterceptor

重新部署：使用以下命令重新部署 Account 服务和 Overdraft 服务：

/chapter11/account-service> mvn verify -Dquarkus.kubernetes.deploy=true
/chapter11/overdraft-service> mvn verify -Dquarkus.kubernetes.deploy=true

验证部署：使用 kubectl get pods 验证每个服务都有一个Pod正在运行。
发起请求：使用以下命令从账户中取款：

curl -H "Content-Type: application/json" -X PUT -d "400.00" ${TRANSACTION_URL}/transactions/5465/withdrawal

查看追踪信息：在浏览器中打开Jaeger控制台并刷新页面，选择 Service 下拉菜单，现在可以看到 overdraft-service 的条目。搜索 account-service 的追踪，将看到新的追踪信息。

2. 追踪信息的连续性

目前，追踪信息存在不连续的问题，主要是在从JAX - RS到Kafka以及接收和发送Kafka消息之间。为了解决这个问题，我们需要进行以下修改：

2.1 从JAX - RS到Kafka传播追踪信息

在 AccountResource 中，我们需要将追踪信息添加到Kafka消息中，示例代码如下：

public class AccountResource {
  @Inject
  Tracer tracer;
  public CompletionStage<Account> withdrawal(@PathParam("accountNumber") Long accountNumber, String amount) {
    ...
      RecordHeaders headers = new RecordHeaders();    
      TracingKafkaUtils.inject(tracer.activeSpan().context(), headers, tracer); 
      OutgoingKafkaRecordMetadata<Object> kafkaMetadata = 
        OutgoingKafkaRecordMetadata.builder()
          .withHeaders(headers)
          .build();                                           
      CompletableFuture<Account> future = new CompletableFuture<>();
      emitter.send(Message.of(payload, Metadata.of(kafkaMetadata),   
          ... ack handler,
          ... nack handler
      );
      return future;
    ...
  }
}

2.2 在Overdraft服务中提取跨度信息

在 OverdraftResource 中，我们需要从Kafka头中提取跨度信息并创建子跨度，示例代码如下：

public class OverdraftResource {
    @Inject
    Tracer tracer;
    public Message<Overdrawn> overdraftNotification(Message<Overdrawn> message) {
        ...
        RecordHeaders headers = new RecordHeaders();
        if (message.getMetadata(IncomingKafkaRecordMetadata.class).isPresent()) {
            Span span = tracer.buildSpan("process-overdraft-fee")  
                .asChildOf(                     
                    TracingKafkaUtils.extractSpanContext(   
                    message.getMetadata(IncomingKafkaRecordMetadata
                      .class).get().getHeaders(),
                        tracer))
                .start();
            try (Scope scope = tracer.activateSpan(span)) {      
                TracingKafkaUtils.inject(span.context(), headers, tracer);  
            } finally {
                span.finish();
            }
        }
        OutgoingKafkaRecordMetadata<Object> kafkaMetadata =
          OutgoingKafkaRecordMetadata.builder()
            .withHeaders(headers)
            .build();
        return message.addMetadata(customerOverdraft).addMetadata(kafkaMetadata);
    }
}

2.3 重新部署并测试

重新部署 Account 服务和 Overdraft 服务：

/chapter11/account-service> mvn verify -Dquarkus.kubernetes.deploy=true
/chapter11/overdraft-service> mvn verify -Dquarkus.kubernetes.deploy=true

使用以下命令从账户中取款：

curl -H "Content-Type: application/json" -X PUT -d "500.00" ${TRANSACTION_URL}/transactions/78790/withdrawal

在浏览器中打开Jaeger控制台，刷新页面，选择 transaction-service ，点击 Find Traces ，将看到包含九个跨度的追踪信息。

3. 总结

通过以上操作，我们可以实现以下功能：
- 包含 quarkus-smallrye-opentracing 依赖和Jaeger配置，即可在JAX - RS资源中实现追踪。
- 通过添加 @Traced 到方法，可以自定义跨度名称或不追踪该方法。
- 向应用代码中注入 Tracer ，可以为跨度添加自定义标签或向行李中添加对象以传播到后续服务。
- 类似于开箱即用的追踪，通过添加依赖和Hibernate配置更改，可以追踪数据库事务。
- 使用Kafka拦截器处理Kafka消息的生产和消费时的跨度。

4. API可视化

API可视化能够帮助开发者更好地理解和使用API。下面将介绍如何生成OpenAPI规范并使用Swagger UI进行可视化。

4.1 OpenAPI规范概述

OpenAPI规范最初于2010年开发，用于定义描述RESTful服务的机器可读接口。2016年，Swagger规范在Linux基金会赞助的新OpenAPI倡议下更名为OpenAPI规范。OpenAPI规范的好处包括：
- 创建服务的交互式文档
- 基于规范自动化测试用例
- 生成与规范对齐的客户端或服务

4.2 查看OpenAPI文档

为了查看OpenAPI文档，我们需要进行以下操作：

4.2.1 启用OpenAPI

添加依赖：在 pom.xml 中添加以下依赖：

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

或者使用Quarkus Maven插件添加依赖：

mvn quarkus:add-extension -Dextensions="quarkus-smallrye-openapi"

启动服务：使用以下命令在实时编码模式下启动服务：

mvn quarkus:dev

访问OpenAPI文档：使用浏览器或 curl 访问 http://localhost:8080/q/openapi ，默认格式为YAML。也可以通过 http://localhost:8080/q/openapi?format=json 访问JSON格式的文档，或者使用 Accept HTTP请求头指定所需的格式。

以下是生成的OpenAPI文档示例：

openapi: 3.0.3              
info:                    
  title: Generated API
  version: "1.0"
paths:                 
  /accounts:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetAccount'
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
      responses:
        "200":
          description: OK
  /accounts/{accountNumber}:
    get:
      parameters:
      - name: accountNumber
        in: path
        required: true
        schema:
          format: int64
          type: integer
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
    delete:
      parameters:
      - name: accountNumber
        in: path
        required: true
        schema:
          format: int64
          type: integer
      responses:
        "200":
          description: OK
....
components:
  schemas:              
    SetAccount:
      uniqueItems: true
      type: array
      items:
        $ref: '#/components/schemas/Account'
    Account:
      type: object
      properties:
        accountNumber:
          format: int64
          type: integer
        accountStatus:
          $ref: '#/components/schemas/AccountStatus'
        balance:
          type: number
        customerName:
          type: string
        customerNumber:
          format: int64
          type: integer
        status:
          $ref: '#/components/schemas/AccountStatus'
    AccountStatus:
      enum:
      - CLOSED
      - OPEN
      - OVERDRAWN
      type: string

通过以上步骤，我们可以实现应用追踪的定制和API的可视化，从而更好地监控和使用系统。

以下是一个简单的mermaid流程图，展示了应用追踪和API可视化的主要步骤：

graph LR
    A[应用追踪定制] --> B[注入追踪器]
    A --> C[追踪数据库调用]
    A --> D[追踪Kafka消息]
    D --> E[解决追踪连续性问题]
    F[API可视化] --> G[启用OpenAPI]
    G --> H[查看OpenAPI文档]

表格总结操作步骤：
| 操作类型 | 步骤 |
| ---- | ---- |
| 注入追踪器 | 1. 修改代码；2. 重新部署；3. 发起请求；4. 查看追踪信息 |
| 追踪数据库调用 | 1. 添加依赖；2. 修改配置；3. 重新部署；4. 发起请求；5. 查看追踪信息 |
| 追踪Kafka消息 | 1. 添加依赖；2. 修改配置；3. 重新部署；4. 验证部署；5. 发起请求；6. 查看追踪信息 |
| 解决追踪连续性问题 | 1. 传播追踪信息；2. 提取跨度信息；3. 重新部署并测试 |
| 启用OpenAPI | 1. 添加依赖；2. 启动服务；3. 访问OpenAPI文档 |

微服务追踪与API可视化全解析

5. Swagger UI的使用与优势

Swagger UI是一个强大的工具，它为开发者提供了一个直观的界面来测试和理解API。在已经生成OpenAPI文档的基础上，使用Swagger UI可以让我们更方便地与API进行交互。

5.1 访问Swagger UI

在启用OpenAPI后，我们可以很方便地访问Swagger UI。只需在浏览器中输入 http://localhost:8080/q/swagger-ui ，即可打开Swagger UI界面。这个界面会自动加载之前生成的OpenAPI文档，并将API的各个端点以可视化的方式展示出来。

5.2 Swagger UI的功能展示

Swagger UI提供了丰富的功能，以下是一些主要功能的介绍：
- 交互式文档 ：Swagger UI会将API的各个端点、请求参数、响应格式等信息以清晰的方式展示出来。开发者可以直接在界面上查看每个端点的详细信息，包括请求方法（如GET、POST等）、请求路径、请求体格式以及可能的响应状态码和响应内容。
- API测试 ：在Swagger UI中，开发者可以直接对API进行测试。只需点击每个端点旁边的“Try it out”按钮，就可以输入请求参数并发送请求。Swagger UI会自动处理请求的发送和响应的接收，并将响应结果展示在界面上。这大大方便了开发者对API的调试和验证。

下面是一个简单的表格，总结了Swagger UI的主要功能：
| 功能 | 描述 |
| ---- | ---- |
| 交互式文档 | 清晰展示API端点、请求参数、响应格式等信息 |
| API测试 | 直接在界面上输入请求参数并发送请求，查看响应结果 |

6. 设计优先的API开发方法

设计优先的API开发方法是一种先设计API接口，再进行代码实现的开发方式。这种方法有很多优点，下面我们来详细介绍。

6.1 设计优先的优势

提高沟通效率 ：在项目开始阶段，通过设计API接口，可以让开发团队、测试团队、产品团队等各方人员对API的功能和使用方式有一个清晰的认识。这有助于减少沟通成本，避免在开发过程中出现误解和错误。
保证API质量 ：在设计阶段，可以对API的接口规范、请求参数、响应格式等进行详细的规划和设计。这样可以确保API的质量和一致性，提高API的可维护性和可扩展性。
便于测试和验证 ：在设计好API接口后，可以提前编写测试用例。在代码实现过程中，可以根据测试用例对API进行验证，确保API的功能符合设计要求。

6.2 设计优先的实施步骤

以下是设计优先的API开发方法的基本实施步骤：
1. 定义API需求 ：与相关团队（如产品团队、业务团队等）沟通，明确API的功能需求、使用场景和性能要求。
2. 设计API接口 ：根据需求，设计API的接口规范，包括请求方法、请求路径、请求参数、响应格式等。可以使用工具（如Swagger Editor）来辅助设计API接口。
3. 生成OpenAPI文档 ：将设计好的API接口转换为OpenAPI文档。可以手动编写OpenAPI文档，也可以使用工具自动生成。
4. 代码实现 ：根据OpenAPI文档，开发团队进行代码实现。在实现过程中，要确保代码与设计的API接口一致。
5. 测试和验证 ：使用编写好的测试用例对API进行测试和验证，确保API的功能符合设计要求。

下面是一个mermaid流程图，展示了设计优先的API开发方法的主要步骤：

graph LR
    A[定义API需求] --> B[设计API接口]
    B --> C[生成OpenAPI文档]
    C --> D[代码实现]
    D --> E[测试和验证]

7. 实际应用案例分析

为了更好地理解应用追踪和API可视化的实际应用，下面我们通过一个简单的案例来进行分析。

假设我们有一个银行系统，包含交易服务、账户服务和透支服务三个微服务。在这个系统中，我们可以使用前面介绍的方法来实现应用追踪和API可视化。

7.1 应用追踪的应用

注入追踪器 ：在账户服务的 AccountResource 类中注入 Tracer 实例，为每个取款操作添加自定义标签和行李项。这样可以在追踪信息中清晰地看到每个操作的账户号码和取款金额。
追踪数据库调用 ：通过添加JDBC追踪依赖和修改配置，我们可以追踪账户服务与数据库的交互。在Jaeger控制台中，我们可以看到每个数据库查询和更新操作的详细信息，包括执行时间、SQL语句等。
追踪Kafka消息 ：为账户服务和透支服务添加Kafka拦截器，处理Kafka消息的生产和消费时的跨度。这样可以在Jaeger控制台中看到消息在不同服务之间的传递过程，解决了追踪信息不连续的问题。

7.2 API可视化的应用

生成OpenAPI文档 ：为账户服务添加 quarkus-smallrye-openapi 依赖，生成OpenAPI文档。通过访问 http://localhost:8080/q/openapi ，我们可以查看账户服务的API规范。
使用Swagger UI ：在浏览器中访问 http://localhost:8080/q/swagger-ui ，使用Swagger UI对账户服务的API进行测试和验证。可以直接在界面上输入请求参数并发送请求，查看响应结果。

通过这个案例，我们可以看到应用追踪和API可视化在实际项目中的重要作用。它们可以帮助我们更好地监控系统的运行状态，提高开发效率，减少调试时间。

8. 总结与展望

通过前面的介绍，我们详细了解了应用追踪的定制方法，包括注入追踪器、追踪数据库调用、追踪Kafka消息以及解决追踪连续性问题。同时，我们也学习了如何生成OpenAPI规范并使用Swagger UI进行API可视化。这些技术可以帮助我们更好地监控和使用系统，提高开发效率和系统的可维护性。

在未来的开发中，随着微服务架构的不断发展和应用的不断扩大，应用追踪和API可视化的重要性将会越来越凸显。我们可以进一步探索如何将这些技术与其他工具和框架相结合，以实现更高效、更智能的系统监控和管理。例如，可以将应用追踪信息与日志分析工具相结合，更好地定位系统中的问题；可以使用API可视化工具生成自动化测试脚本，提高测试效率。

总之，应用追踪和API可视化是现代软件开发中不可或缺的技术，掌握这些技术可以让我们在开发过程中更加得心应手。希望本文的介绍能够对大家有所帮助。

表格总结应用追踪和API可视化的关键技术和作用：
| 技术领域 | 关键技术 | 作用 |
| ---- | ---- | ---- |
| 应用追踪 | 注入追踪器、追踪数据库调用、追踪Kafka消息、解决追踪连续性问题 | 监控系统运行状态，定位问题，提高系统性能 |
| API可视化 | 生成OpenAPI文档、使用Swagger UI | 方便开发者理解和使用API，提高开发效率 |