microservice-infrastructure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

微服务基础设施指南

Microservice Infrastructure Guide

Skill 概述

Skill Overview

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

This Skill covers 4 core infrastructure components in the BK-CI microservice architecture, which are the cornerstones of building distributed systems and deeply integrated with the Spring Cloud/Spring Boot framework.

核心主题

Core Topics

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

Topic	Description	Document
Conditional Configuration	Profile configuration, feature flags, environment isolation	[1-conditional-config.md]
Event-Driven	MQ message queue, publish-subscribe, asynchronous processing	[2-event-driven.md]
Inter-Service Communication	Feign client, service discovery, circuit breaking and degradation	[3-service-communication.md]
Internationalization & Logging	i18n multi-language, logging specifications, sensitive information desensitization	[4-i18n-logging.md]

微服务基础设施架构

Microservice Infrastructure Architecture

架构视图

Architecture View

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

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

使用指南

Usage Guide

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

Scenario 1: Configure Multi-Environments (Development/Testing/Production)

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

步骤:

查阅 reference/1-conditional-config.md
使用
```
@Profile
```
注解或
```
@Conditional
```
配置
```
application-{profile}.yml
```
实现特性开关逻辑

典型问题:

如何动态切换环境配置？
特性开关如何实现？
配置优先级如何确定？

Requirement: Use different configurations and feature flags for different environments

Steps:

Refer to reference/1-conditional-config.md
Use
```
@Profile
```
annotation or
```
@Conditional
```
Configure
```
application-{profile}.yml
```
Implement feature flag logic

Typical Questions:

How to dynamically switch environment configurations?
How to implement feature flags?
How to determine configuration priority?

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

Scenario 2: Implement Event-Driven Architecture

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

步骤:

查阅 reference/2-event-driven.md
定义事件类（实现
```
IEvent
```
接口）
发布事件到 MQ
订阅并处理事件

典型问题:

如何发布事件？
如何订阅消息队列？
事件丢失如何处理？

Requirement: Asynchronous processing, module decoupling, event sourcing

Steps:

Refer to reference/2-event-driven.md
Define event class (implement
```
IEvent
```
interface)
Publish events to MQ
Subscribe to and process events

Typical Questions:

How to publish events?
How to subscribe to message queues?
How to handle event loss?

场景 3：服务间调用

Scenario 3: Inter-Service Calls

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

步骤:

查阅 reference/3-service-communication.md
定义 Feign 客户端接口
配置服务发现（Consul）
实现熔断降级逻辑

典型问题:

Feign 客户端如何定义？
超时时间如何配置？
服务降级如何实现？

Requirement: Cross-service communication, load balancing, circuit breaking and degradation

Steps:

Refer to reference/3-service-communication.md
Define Feign client interface
Configure service discovery (Consul)
Implement circuit breaking and degradation logic

Typical Questions:

How to define Feign clients?
How to configure timeout settings?
How to implement service degradation?

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

Scenario 4: Implement Internationalization & Logging Specifications

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

步骤:

查阅 reference/4-i18n-logging.md
配置 i18n 消息文件（
```
messages_zh_CN.properties
```
）
规范日志输出（使用 SLF4J）
实现敏感信息脱敏

典型问题:

如何添加新语言？
日志级别如何设置？
密码等敏感信息如何脱敏？

Requirement: Multi-language support, unified log format, sensitive information desensitization

Steps:

Refer to reference/4-i18n-logging.md
Configure i18n message files (
```
messages_zh_CN.properties
```
)
Standardize log output (use SLF4J)
Implement sensitive information desensitization

Typical Questions:

How to add new languages?
How to set log levels?
How to desensitize sensitive information like passwords?

核心类与文件速查

Quick Reference for Core Classes & Files

条件配置

Conditional Configuration

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

Class/File	Path	Description
`@Profile`	Built-in in Spring Boot	Environment configuration annotation
`@Conditional`	Built-in in Spring Boot	Conditional Bean loading
`application-*.yml`	`src/main/resources/`	Multi-environment configuration files

事件驱动

Event-Driven

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

Class/File	Path	Description
`IEvent`	`common-event/pojo/IEvent.kt`	Event interface
`EventDispatcher`	`common-event/dispatcher/`	Event dispatcher
`EventListener`	`common-event/listener/`	Event listener

服务间通信

Inter-Service Communication

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

Class/File	Path	Description
`Client`	`common-client/Client.kt`	Feign client base class
`ServiceXXXResource`	`api-*/api/`	Service interface definition

国际化与日志

Internationalization & Logging

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

Directory/File	Path	Description
`i18n/`	`support-files/i18n/`	Internationalization message files
`messages_*.properties`	`support-files/i18n/`	Multi-language configuration

开发规范

Development Specifications

1. 条件配置规范

1. Conditional Configuration Specifications

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

✅ Use
```
@Profile
```
annotation for environment-related configurations
✅ Use
```
@ConditionalOnProperty
```
for feature flags
✅ Encrypt and store sensitive configurations (passwords, keys)
✅ Separate configuration files by environment (
```
application-dev.yml
```
)

2. 事件驱动规范

2. Event-Driven Specifications

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

✅ Event classes must implement the
```
IEvent
```
interface
✅ Event naming:
```
{Module}{Action}Event
```
(e.g.,
```
PipelineStartEvent
```
)
✅ Use
```
EventDispatcher
```
to publish events
✅ Event listener processing must be idempotent
✅ Avoid synchronous waiting for event processing results

3. 服务间通信规范

3. Inter-Service Communication Specifications

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

✅ Define Feign interfaces in
```
api-*
```
modules
✅ Set reasonable timeout values (5s connection timeout, 30s read timeout)
✅ Implement service degradation (return default values or cached data)
✅ Avoid circular calls between services
✅ Add distributed tracing for critical calls

4. 国际化与日志规范

4. Internationalization & Logging Specifications

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

✅ All user-visible text must be internationalized
✅ Support at least Chinese and English
✅ Use SLF4J for logging (do not use
```
println
```
)
✅ Log levels: ERROR (errors), WARN (warnings), INFO (critical processes), DEBUG (debugging)
✅ Sensitive information (passwords, Tokens) must be desensitized

与其他 Skill 的关系

Relationship with Other Skills

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 模块架构（事件驱动应用）

microservice-infrastructure (this Skill)
    ↓ depends on
backend-microservice-development     # Microservice Development Basics
common-technical-practices           # Common Technical Practices
    ↓ is depended by
process-module-architecture          # Process module uses these infrastructures
auth-module-architecture             # Auth module uses these infrastructures
...                                  # Other business modules

Prerequisite Knowledge:

```
backend-microservice-development
```
- Understand Spring Boot/Spring Cloud basics

Related Skills:

```
common-technical-practices
```
- Common Technical Practices (AOP, locks, retries)
```
process-module-architecture
```
- Process Module Architecture (event-driven application)

详细文档导航

Detailed Document Navigation

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

Document	Content	Line Count	Typical Questions
1-conditional-config.md	Conditional Configuration	59	How to configure multi-environments? How to implement feature flags?
2-event-driven.md	Event-Driven Architecture	88	How to publish events? How to handle event loss?
3-service-communication.md	Inter-Service Communication	104	How to configure Feign? How to handle timeouts?
4-i18n-logging.md	Internationalization & Logging	67	How to add new languages? How to desensitize sensitive information?

常见问题 FAQ

FAQ

Q1: 如何根据环境切换配置？

Q1: How to switch configurations based on environment?

创建

application-{profile}.yml

（如

application-dev.yml

）

启动时指定：
```
--spring.profiles.active=dev
```
或使用
```
@Profile("dev")
```
注解

Create

application-{profile}.yml

(e.g.,

application-dev.yml

)

Specify at startup:
```
--spring.profiles.active=dev
```
Or use the
```
@Profile("dev")
```
annotation

Q2: 事件发布后如何保证消费？

Q2: How to ensure consumption after event publishing?

使用 持久化队列（RabbitMQ）
消费失败后 自动重试
最终失败进入 死信队列
监控死信队列并告警

Use persistent queues (RabbitMQ)
Automatic retry after consumption failure
Failed messages enter the dead-letter queue eventually
Monitor the dead-letter queue and set up alerts

Q3: Feign 调用超时如何处理？

Q3: How to handle Feign call timeouts?

配置合理的超时时间（连接 5s，读 30s）
实现 服务降级 返回默认值
添加 重试机制（幂等操作）
使用 熔断器 快速失败

Configure reasonable timeout values (5s connection, 30s read)
Implement service degradation to return default values
Add retry mechanism (for idempotent operations)
Use circuit breakers for fast failure

Q4: 服务间循环调用如何避免？

Q4: How to avoid circular calls between services?

禁止双向依赖（A 调 B，B 不能调 A）
使用 事件驱动 解耦
引入 中间服务 打破循环
代码 Review 时检查依赖关系

Prohibit bidirectional dependencies (if A calls B, B cannot call A)
Use event-driven approach for decoupling
Introduce intermediate services to break the cycle
Check dependency relationships during code review

Q5: 如何添加新的语言支持？

Q5: How to add new language support?

在

support-files/i18n/

下创建

messages_{locale}.properties

如添加日文：
```
messages_ja_JP.properties
```
翻译所有 key 的内容
重启服务生效

Create

messages_{locale}.properties

under

support-files/i18n/

For example, add Japanese:
```
messages_ja_JP.properties
```
Translate the content of all keys
Restart the service to take effect

Q6: 日志打印过多影响性能？

Q6: Excessive log printing affects performance?

生产环境使用 INFO 级别（不用 DEBUG）
避免在循环中打印日志
使用 异步日志（Logback AsyncAppender）
定期清理旧日志

Use INFO level in production environment (do not use DEBUG)
Avoid printing logs in loops
Use asynchronous logging (Logback AsyncAppender)
Regularly clean up old logs

Q7: 敏感信息如何脱敏？

Q7: How to desensitize sensitive information?

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))

kotlin

// Password desensitization
logger.info("User login: username={}, password={}", username, "******")

// Token desensitization (show first 4 and last 4 characters)
logger.info("Token: {}...{}", token.take(4), token.takeLast(4))

// Phone number desensitization (show first 3 and last 4 characters)
logger.info("Phone: {}****{}", phone.take(3), phone.takeLast(4))

总结

Summary

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

学习路径:

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

最佳实践:

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

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

This Skill covers 4 core infrastructure components of the BK-CI microservice architecture, which are the cornerstones of building distributed systems.

Learning Path:

First understand microservice basics (
```
backend-microservice-development
```
)
Dive into specific technologies as needed (configuration/events/communication/logging)
Apply in actual development and summarize experience

Best Practices:

✅ Use conditional configuration for multi-environment isolation
✅ Use event-driven approach for module decoupling
✅ Implement circuit breaking and degradation for inter-service calls
✅ All user-facing text must be internationalized
✅ Sensitive information must be desensitized

Mastering these infrastructures will make your microservice architecture more robust and maintainable! 🚀