home / skills / tencentblueking / bk-ci / microservice-infrastructure

microservice-infrastructure skill

safe

This skill helps you implement microservice infrastructure foundations including conditional config, event-driven architecture, inter-service communication,

npx playbooks add skill tencentblueking/bk-ci --skill microservice-infrastructure

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

11.0 KB

---
name: microservice-infrastructure
description: 微服务基础设施指南，涵盖条件配置、事件驱动架构、服务间通信、国际化与日志等微服务架构的核心基础设施。当用户实现服务间调用、配置多环境、实现异步通信、处理国际化或规范日志输出时使用。
core_files:
  - "src/backend/ci/core/common/common-event/"
  - "src/backend/ci/core/common/common-client/src/main/kotlin/com/tencent/devops/common/client/Client.kt"
  - "support-files/i18n/"
related_skills:
  - backend-microservice-development
  - common-technical-practices
token_estimate: 6000
---

# 微服务基础设施指南

## Skill 概述

本 Skill 涵盖了 BK-CI 微服务架构中的 **4 大核心基础设施**，这些是构建分布式系统的基石，与 Spring Cloud/Spring Boot 框架深度集成。

### 核心主题

| 主题 | 说明 | 文档 |
|------|------|------|
| **条件配置** | Profile 配置、特性开关、环境隔离 | [1-conditional-config.md] |
| **事件驱动** | MQ 消息队列、发布订阅、异步处理 | [2-event-driven.md] |
| **服务间通信** | Feign 客户端、服务发现、熔断降级 | [3-service-communication.md] |
| **国际化与日志** | i18n 多语言、日志规范、敏感信息脱敏 | [4-i18n-logging.md] |

---

## 微服务基础设施架构

### 架构视图

```
┌─────────────────────────────────────────────────────────────────┐
│                    BK-CI 微服务集群                              │
│  Process / Project / Store / Auth / Repository / Dispatch...   │
└─────────────────────────────────────────────────────────────────┘
                             ↓
        ┌────────────────────┼────────────────────┐
        │                    │                    │
   ┌────▼────┐         ┌────▼────┐         ┌────▼────┐
   │ Feign   │         │  MQ     │         │ Config  │
   │ 服务调用 │         │ 事件驱动 │         │ 配置中心 │
   └─────────┘         └─────────┘         └─────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                    微服务基础设施层                              │
├─────────────────────────────────────────────────────────────────┤
│  • 条件配置（多环境隔离）                                        │
│  • 事件驱动（异步解耦）                                          │
│  • 服务间通信（负载均衡、熔断）                                   │
│  • 国际化与日志（可观测性）                                      │
└─────────────────────────────────────────────────────────────────┘
```

---

## 使用指南

### 场景 1：配置多环境（开发/测试/生产）

**需求**: 不同环境使用不同配置、特性开关

**步骤**:
1. 查阅 [reference/1-conditional-config.md](./reference/1-conditional-config.md)
2. 使用 `@Profile` 注解或 `@Conditional`
3. 配置 `application-{profile}.yml`
4. 实现特性开关逻辑

**典型问题**:
- 如何动态切换环境配置？
- 特性开关如何实现？
- 配置优先级如何确定？

---

### 场景 2：实现事件驱动架构

**需求**: 异步处理、模块解耦、事件溯源

**步骤**:
1. 查阅 [reference/2-event-driven.md](./reference/2-event-driven.md)
2. 定义事件类（实现 `IEvent` 接口）
3. 发布事件到 MQ
4. 订阅并处理事件

**典型问题**:
- 如何发布事件？
- 如何订阅消息队列？
- 事件丢失如何处理？

---

### 场景 3：服务间调用

**需求**: 跨服务通信、负载均衡、熔断降级

**步骤**:
1. 查阅 [reference/3-service-communication.md](./reference/3-service-communication.md)
2. 定义 Feign 客户端接口
3. 配置服务发现（Consul）
4. 实现熔断降级逻辑

**典型问题**:
- Feign 客户端如何定义？
- 超时时间如何配置？
- 服务降级如何实现？

---

### 场景 4：实现国际化与日志规范

**需求**: 多语言支持、统一日志格式、敏感信息脱敏

**步骤**:
1. 查阅 [reference/4-i18n-logging.md](./reference/4-i18n-logging.md)
2. 配置 i18n 消息文件（`messages_zh_CN.properties`）
3. 规范日志输出（使用 SLF4J）
4. 实现敏感信息脱敏

**典型问题**:
- 如何添加新语言？
- 日志级别如何设置？
- 密码等敏感信息如何脱敏？

---

## 核心类与文件速查

### 条件配置

| 类/文件 | 路径 | 说明 |
|---------|------|------|
| `@Profile` | Spring Boot 内置 | 环境配置注解 |
| `@Conditional` | Spring Boot 内置 | 条件化 Bean 加载 |
| `application-*.yml` | `src/main/resources/` | 多环境配置文件 |

### 事件驱动

| 类/文件 | 路径 | 说明 |
|---------|------|------|
| `IEvent` | `common-event/pojo/IEvent.kt` | 事件接口 |
| `EventDispatcher` | `common-event/dispatcher/` | 事件分发器 |
| `EventListener` | `common-event/listener/` | 事件监听器 |

### 服务间通信

| 类/文件 | 路径 | 说明 |
|---------|------|------|
| `Client` | `common-client/Client.kt` | Feign 客户端基类 |
| `ServiceXXXResource` | `api-*/api/` | 服务接口定义 |

### 国际化与日志

| 目录/文件 | 路径 | 说明 |
|----------|------|------|
| `i18n/` | `support-files/i18n/` | 国际化消息文件 |
| `messages_*.properties` | `support-files/i18n/` | 多语言配置 |

---

## 开发规范

### 1. 条件配置规范

- ✅ 环境相关配置使用 `@Profile` 注解
- ✅ 特性开关使用 `@ConditionalOnProperty`
- ✅ 敏感配置（密码、密钥）加密存储
- ✅ 配置文件按环境分离（`application-dev.yml`）

### 2. 事件驱动规范

- ✅ 事件类实现 `IEvent` 接口
- ✅ 事件命名：`{Module}{Action}Event`（如 `PipelineStartEvent`）
- ✅ 事件发布使用 `EventDispatcher`
- ✅ 事件监听器处理要幂等
- ✅ 避免同步等待事件处理结果

### 3. 服务间通信规范

- ✅ Feign 接口定义在 `api-*` 模块
- ✅ 设置合理的超时时间（连接超时 5s，读超时 30s）
- ✅ 实现服务降级（返回默认值或缓存数据）
- ✅ 避免服务间循环调用
- ✅ 关键调用添加链路追踪

### 4. 国际化与日志规范

- ✅ 用户可见文案必须国际化
- ✅ 至少支持中文和英文
- ✅ 日志使用 SLF4J（不使用 `println`）
- ✅ 日志级别：ERROR（错误）、WARN（警告）、INFO（关键流程）、DEBUG（调试）
- ✅ 敏感信息（密码、Token）必须脱敏

---

## 与其他 Skill 的关系

```
microservice-infrastructure (本 Skill)
    ↓ 依赖
backend-microservice-development     # 微服务开发基础
common-technical-practices           # 通用技术实践
    ↓ 被依赖
process-module-architecture          # Process 模块使用这些基础设施
auth-module-architecture             # Auth 模块使用这些基础设施
...                                  # 其他业务模块
```

**前置知识**:
- `backend-microservice-development` - 了解 Spring Boot/Spring Cloud 基础

**相关 Skill**:
- `common-technical-practices` - 通用技术实践（AOP、锁、重试）
- `process-module-architecture` - Process 模块架构（事件驱动应用）

---

## 详细文档导航

| 文档 | 内容 | 行数 | 典型问题 |
|------|------|------|----------|
| [1-conditional-config.md](./reference/1-conditional-config.md) | 条件配置 | 59 | 如何配置多环境？特性开关如何实现？ |
| [2-event-driven.md](./reference/2-event-driven.md) | 事件驱动架构 | 88 | 如何发布事件？事件丢失如何处理？ |
| [3-service-communication.md](./reference/3-service-communication.md) | 服务间通信 | 104 | Feign 如何配置？超时如何处理？ |
| [4-i18n-logging.md](./reference/4-i18n-logging.md) | 国际化与日志 | 67 | 如何添加新语言？敏感信息如何脱敏？ |

---

## 常见问题 FAQ

### Q1: 如何根据环境切换配置？
**A**: 
1. 创建 `application-{profile}.yml`（如 `application-dev.yml`）
2. 启动时指定：`--spring.profiles.active=dev`
3. 或使用 `@Profile("dev")` 注解

### Q2: 事件发布后如何保证消费？
**A**:
1. 使用 **持久化队列**（RabbitMQ）
2. 消费失败后 **自动重试**
3. 最终失败进入 **死信队列**
4. 监控死信队列并告警

### Q3: Feign 调用超时如何处理？
**A**:
1. 配置合理的超时时间（连接 5s，读 30s）
2. 实现 **服务降级** 返回默认值
3. 添加 **重试机制**（幂等操作）
4. 使用 **熔断器** 快速失败

### Q4: 服务间循环调用如何避免？
**A**:
1. **禁止双向依赖**（A 调 B，B 不能调 A）
2. 使用 **事件驱动** 解耦
3. 引入 **中间服务** 打破循环
4. 代码 Review 时检查依赖关系

### Q5: 如何添加新的语言支持？
**A**:
1. 在 `support-files/i18n/` 下创建 `messages_{locale}.properties`
2. 如添加日文：`messages_ja_JP.properties`
3. 翻译所有 key 的内容
4. 重启服务生效

### Q6: 日志打印过多影响性能？
**A**:
1. 生产环境使用 **INFO** 级别（不用 DEBUG）
2. 避免在循环中打印日志
3. 使用 **异步日志**（Logback AsyncAppender）
4. 定期清理旧日志

### Q7: 敏感信息如何脱敏？
**A**:
```kotlin
// 密码脱敏
logger.info("User login: username={}, password={}", username, "******")

// Token 脱敏（显示前4后4）
logger.info("Token: {}...{}", token.take(4), token.takeLast(4))

// 手机号脱敏（显示前3后4）
logger.info("Phone: {}****{}", phone.take(3), phone.takeLast(4))
```

---

## 总结

本 Skill 涵盖了 BK-CI 微服务架构的 4 大核心基础设施，这些是构建分布式系统的基石。

**学习路径**:
1. 先了解微服务基础（`backend-microservice-development`）
2. 按需深入具体技术（配置/事件/通信/日志）
3. 在实际开发中应用并总结经验

**最佳实践**:
- ✅ 多环境隔离使用条件配置
- ✅ 模块解耦使用事件驱动
- ✅ 服务间调用实现熔断降级
- ✅ 用户文案必须国际化
- ✅ 敏感信息必须脱敏

掌握这些基础设施，让你的微服务架构更加健壮和可维护！🚀

Overview

This skill documents core microservice infrastructure patterns used in a Kotlin-based CI platform. It focuses on conditional configuration, event-driven design, inter-service communication, and internationalization plus logging. The guidance is practical, framework-aligned (Spring Boot / Spring Cloud) and aimed at making distributed services robust and maintainable.

How this skill works

The content inspects configuration strategies (profiles, conditional beans, feature toggles), event dispatch and subscription patterns using message queues, and Feign-based service calls with discovery and circuit breakers. It also prescribes internationalization message files, SLF4J logging conventions, and sensitive-data masking. Each topic includes conventions, typical problems, and concrete implementation pointers for Kotlin/Spring ecosystems.

When to use it

When you need separate environment configs and runtime feature toggles
When components must be decoupled using asynchronous events or MQs
When services call each other and require discovery, timeouts, and fallback strategies
When user-facing text must support multiple locales
When you must standardize logs and mask sensitive data for compliance and observability

Best practices

Use @Profile and environment-specific application-{profile}.yml for environment isolation
Apply @ConditionalOnProperty for feature toggles and keep secrets encrypted
Design events implementing an IEvent interface and keep listeners idempotent
Define Feign clients in api-* modules, set sensible timeouts (connect 5s, read 30s) and add circuit breakers
Internationalize all user-visible strings and maintain messages_*.properties under support-files/i18n
Use SLF4J for logs, adhere to log levels, and mask passwords/tokens before logging

Example use cases

Switch configs between dev/test/prod using Spring profiles and conditional beans
Publish domain events to a durable MQ and process them asynchronously with retry and DLQ handling
Call downstream services with Feign, apply service discovery and implement graceful fallbacks
Add a new locale by creating messages_{locale}.properties and validating translations
Standardize logs across services and implement token/password masking before emitting logs

FAQ

How do I switch environment configurations at runtime?

Create application-{profile}.yml and start with --spring.profiles.active or annotate beans with @Profile to load environment-specific beans.

How can I ensure events are not lost?

Use a persistent MQ, enable retries on consumption, route final failures to a dead-letter queue, and monitor DLQs with alerts.

What if a Feign call times out?

Set reasonable connect/read timeouts, implement circuit breakers and fallback handlers, and make retries only for idempotent operations.