agileconfig-jclient

August 2, 2026 · View on GitHub

A java client for AgileConfig.

AgileConfig 的 Java 客户端。通过 HTTP 拉取配置，通过 WebSocket 接收服务端推送的变更通知，支持本地缓存、断线重连、多节点容灾。

特性

从 AgileConfig 服务端拉取配置，支持多节点（随机选择 + 失败切换）
WebSocket 长连接，服务端配置发布后自动重新加载
心跳保活（30 秒）与断线自动重连
配置本地文件缓存，所有节点不可用时可从本地缓存恢复
本地缓存文件可选 AES 加密
配置重载事件监听
Spring Boot Starter 开箱即用

环境要求

JDK 8+
Maven 3.x
AgileConfig 服务端

模块说明

模块	artifactId	说明
client	`agileconfig-client`	核心客户端，无 Spring 依赖，可独立使用
starter	`agileconfig-boot-starter`	Spring Boot 自动装配

安装

当前版本为 1.0-SNAPSHOT，请先在项目根目录安装到本地仓库：

mvn clean install -DskipTests

原生 Java 项目只需引用 client：

<dependency>
    <groupId>com.github.kklldog.agileconfig</groupId>
    <artifactId>agileconfig-client</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Spring Boot 项目引用 starter：

<dependency>
    <groupId>com.github.kklldog.agileconfig</groupId>
    <artifactId>agileconfig-boot-starter</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

快速开始

1. 原生 Java 使用

import com.github.kklldog.agileconfig.ConfigClient;
import com.github.kklldog.agileconfig.IConfigClient;
import com.github.kklldog.agileconfig.Options;

public class Demo {
    public static void main(String[] args) {
        // nodes 支持多个节点，用英文逗号分隔
        Options options = new Options(
                "http://localhost:5000,http://localhost:5001",
                "app_id",
                "app_secret",
                "DEV");
        options.setName("my-java-app");
        options.setTag("order");

        IConfigClient client = new ConfigClient(options);

        // 连接服务端并拉取配置，内部会启动心跳与重连线程
        client.connect();

        String value = client.get("db:connection");
        System.out.println(value);

        // 应用退出时断开
        Runtime.getRuntime().addShutdownHook(new Thread(client::disconnect));
    }
}

2. Spring Boot 使用

在 application.yml 中配置：

agile:
  config:
    node: http://localhost:5000,http://localhost:5001
    appId: app_id
    secret: app_secret
    env: DEV
    name: my-spring-app
    tag: order
    httpTimeout: 100
    reconnectInterval: 5
    cache:
      enabled: true
      directory: ./config-cache
      configEncrypt: false

starter 会自动注册一个 IConfigClient Bean。注意：Bean 创建后不会自动连接，需要自行触发 connect()，例如：

import com.github.kklldog.agileconfig.IConfigClient;
import org.springframework.boot.ApplicationRunner;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class AgileConfigInitializer {

    @Bean
    public ApplicationRunner agileConfigRunner(IConfigClient configClient) {
        return args -> configClient.connect();
    }
}

然后在任意 Bean 中注入使用：

@Service
public class OrderService {

    private final IConfigClient configClient;

    public OrderService(IConfigClient configClient) {
        this.configClient = configClient;
    }

    public String dbConnection() {
        return configClient.get("db:connection");
    }
}

如果需要自定义客户端，只要自己声明一个名为 agileConfigClient 的 Bean，自动装配就会退让（@ConditionalOnMissingBean(name = "agileConfigClient")）。

读取配置

配置项的 key 规则：

无分组：直接使用 key
有分组：group:key

key 的比较忽略大小写。

// 单个配置，不存在时返回空字符串 ""
String val = client.get("db:connection");

// 全部配置
Map<String, String> all = client.getConfigs();

// 按分组取
List<ConfigItem> dbItems = client.getGroup("db");

监听配置变更

服务端发布配置后，客户端会自动重新拉取并触发监听器：

client.addReloadedListener(args -> {
    Map<String, String> oldConfigs = args.getOldConfigs();
    Map<String, String> newConfigs = args.getNewConfigs();
    newConfigs.forEach((k, v) -> {
        if (!v.equals(oldConfigs.get(k))) {
            System.out.println("changed: " + k + " = " + v);
        }
    });
});

// 不再需要时移除
// client.removeReloadedListener(listener);

配置项（Options）

属性	Spring 配置项	默认值	说明
nodes	`agile.config.node`	无（必填）	服务端地址，多个用逗号分隔
appId	`agile.config.appId`	`""`	应用 ID
secret	`agile.config.secret`	`""`	应用密钥
env	`agile.config.env`	`dev`	环境标识，内部会转成大写
name	`agile.config.name`	`""`	客户端名称，上报给服务端展示
tag	`agile.config.tag`	`""`	客户端标签，上报给服务端展示
httpTimeout	`agile.config.httpTimeout`	`100`	HTTP 请求超时时间（秒）
reconnectInterval	`agile.config.reconnectInterval`	`5`	断线重连间隔（秒）
cacheEnabled	`agile.config.cache.enabled`	`true`	是否把配置缓存到本地文件
cacheDirectory	`agile.config.cache.directory`	`""`（当前工作目录）	本地缓存目录
configCacheEncrypt	`agile.config.cache.configEncrypt`	`false`	是否用 secret 对缓存文件做 AES 加密
reloadFromLocal	无	`true`	所有节点都拉取失败时是否从本地缓存恢复

本地缓存文件名为 {appId}.agileconfig.client.configs.cache。

客户端状态

ConnectStatus status = client.getStatus();      // Disconnected / Connecting / Connected
boolean fromLocal = client.isLoadFromLocal();   // 当前配置是否来自本地缓存
Date lastLoaded = client.getLastLoadedTimeFromServer(); // 最后一次成功从服务端拉取的时间
String version = client.localVersion();         // 与服务端比较的版本号
String md5 = client.md5Version();               // 当前配置数据的 md5

构建与测试

# 编译并安装
mvn clean install

# 只跑测试
mvn test

License

见 LICENSE.md。