odboy
182765e4a0
- 新增 kenaito-conf-springboot3-client，支持配置拉取、增量同步、@Value/@ConfigurationProperties 动态刷新和本地缓存 - 新增 kenaito-conf-springboot3-client-demo（端口 8084）及 Dockerfile.springboot3 - 完善中英文 README、Docker 部署文档，修正 Spring Boot 2 客户端配置键名与 demo 端口说明 - 修复增量同步将服务端 code=0 成功响应误判为错误的问题
179 lines
5.1 KiB
Markdown
179 lines
5.1 KiB
Markdown
# Kenaito Config Center Spring Boot 2 Client
|
||
|
||
[English](README_EN.md) | 中文
|
||
|
||
适用于 Spring Boot 2.x 应用的配置中心客户端，支持配置自动刷新和 `@Value` 注解动态更新。
|
||
|
||
## 功能特性
|
||
|
||
- 从配置中心拉取应用配置
|
||
- 定时同步配置变更
|
||
- 支持 `@Value` 注解动态刷新
|
||
- 本地文件缓存（配置中心不可用时降级）
|
||
|
||
## 安装
|
||
|
||
### Maven 依赖
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>cn.odboy</groupId>
|
||
<artifactId>kenaito-conf-springboot2-client</artifactId>
|
||
<version>1.0.3</version>
|
||
</dependency>
|
||
```
|
||
|
||
### 本地安装（开发调试）
|
||
|
||
```bash
|
||
cd kenaito-conf-springboot2-client
|
||
mvn clean install
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置文件
|
||
|
||
在 `application.properties` 中添加配置中心连接参数：
|
||
|
||
```properties
|
||
# 配置中心地址
|
||
kenaito.config.baseUrl=http://localhost:8080
|
||
|
||
# 应用名称（必填）
|
||
kenaito.config.appName=my-app
|
||
|
||
# 环境（dev/daily/prod）
|
||
kenaito.config.profile=daily
|
||
|
||
# 配置版本
|
||
kenaito.config.version=latest
|
||
|
||
# 认证令牌（可选）
|
||
kenaito.config.token=your-token
|
||
|
||
# 是否启用远程配置（默认 true）
|
||
kenaito.config.enabled=true
|
||
|
||
# 同步间隔（秒，默认 60）
|
||
kenaito.config.sync-interval-seconds=10
|
||
|
||
# 是否忽略业务组全局配置（默认 false）
|
||
kenaito.config.global-ignore=false
|
||
```
|
||
|
||
### 2. 使用 @Value 注入配置
|
||
|
||
```java
|
||
import org.springframework.beans.factory.annotation.Value;
|
||
import org.springframework.web.bind.annotation.RestController;
|
||
import org.springframework.web.bind.annotation.GetMapping;
|
||
|
||
@RestController
|
||
public class ConfigController {
|
||
|
||
@Value("${database.host:localhost}")
|
||
private String databaseHost;
|
||
|
||
@Value("${database.port:3306}")
|
||
private Integer databasePort;
|
||
|
||
@Value("${kenaito.feature.enabled:false}")
|
||
private Boolean featureEnabled;
|
||
|
||
@GetMapping("/config")
|
||
public Map<String, Object> getConfig() {
|
||
Map<String, Object> config = new HashMap<>();
|
||
config.put("databaseHost", databaseHost);
|
||
config.put("databasePort", databasePort);
|
||
config.put("featureEnabled", featureEnabled);
|
||
return config;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 配置自动刷新
|
||
|
||
当配置中心的配置发生变更时，客户端会自动刷新 `@Value` 注解的字段值，无需重启应用。
|
||
|
||
**配置变更监听日志：**
|
||
```
|
||
[RefreshScope] Refreshed @Value field: ConfigController.databaseHost | old='localhost' | new='192.168.1.100' | converted='192.168.1.100' | verify='192.168.1.100' | success=true
|
||
```
|
||
|
||
### 4. 使用 @ConfigurationProperties
|
||
|
||
```java
|
||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||
import org.springframework.stereotype.Component;
|
||
|
||
@Component
|
||
@ConfigurationProperties(prefix = "database")
|
||
public class DatabaseProperties {
|
||
|
||
private String host;
|
||
private Integer port;
|
||
private String username;
|
||
private String password;
|
||
|
||
// getters and setters
|
||
}
|
||
```
|
||
|
||
## 配置项说明
|
||
|
||
| 配置项 | 说明 | 默认值 | 必填 |
|
||
|--------|------|--------|------|
|
||
| `kenaito.config.baseUrl` | 配置中心地址 | - | 是 |
|
||
| `kenaito.config.appName` | 应用名称 | `spring.application.name` | 是 |
|
||
| `kenaito.config.profile` | 环境标识 | `dev` | 否 |
|
||
| `kenaito.config.version` | 配置版本 | `latest` | 否 |
|
||
| `kenaito.config.token` | 认证令牌 | 空 | 否 |
|
||
| `kenaito.config.enabled` | 是否启用 | `true` | 否 |
|
||
| `kenaito.config.sync-interval-seconds` | 同步间隔（秒） | `60` | 否 |
|
||
| `kenaito.config.global-ignore` | 忽略业务组全局配置 | `false` | 否 |
|
||
| `kenaito.configcenter.local-storage-dir` | 本地缓存目录 | 应用工作目录 | 否 |
|
||
|
||
> Spring Boot 2 客户端读取的是驼峰形式的 `baseUrl` / `appName`；敏感键固定为 `password`、`passwd`、`key`、`secret`、`token`、`credentials`，暂不支持自定义。
|
||
|
||
## 自动配置说明
|
||
|
||
客户端通过 Spring Boot 自动配置机制工作：
|
||
|
||
- **KenaitoEnvironmentInitializer**：初始化配置中心连接
|
||
- **KenaitoRefreshAutoConfiguration**：注册配置刷新监听器
|
||
|
||
无需手动配置任何 Bean，引入依赖并配置参数即可使用。
|
||
|
||
## Demo
|
||
|
||
运行示例项目：
|
||
|
||
```bash
|
||
cd kenaito-conf-springboot2-client-demo
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
Demo 默认配置：
|
||
- 端口：8081
|
||
- 应用名称：`kenaito-springboot-demo`
|
||
- 环境：`daily`
|
||
- 配置中心地址：`http://localhost:8080`
|
||
|
||
访问 `http://localhost:8081/` 或 `http://localhost:8081/configprops` 查看当前配置。
|
||
|
||
## 注意事项
|
||
|
||
1. **@Value 刷新限制**：仅支持基本类型（String、Integer、Boolean、Long、Double 等）和它们的包装类
|
||
2. **配置优先级**：远程配置 > 本地配置 > 默认值
|
||
3. **日志脱敏**：包含敏感键的配置在日志中会自动脱敏（显示前一半 + `****`）
|
||
4. **网络异常**：同步失败时会记录错误日志，不影响应用正常运行
|
||
5. **本地容灾**：客户端会在本地缓存目录下创建 `config-cache.log` 文件，当配置中心不可用时自动从缓存加载配置
|
||
|
||
## 版本历史
|
||
|
||
- **1.0.3** - 简化配置刷新逻辑，移除 EnvironmentChangeEvent 包装
|
||
- **1.0.2** - 添加敏感配置脱敏支持
|
||
- **1.0.1** - 添加配置同步间隔配置
|
||
- **1.0.0** - 初始版本
|