Azure App Configuration Java SDK

Azure App Configuration Java SDK

Azure App Configuration 的客户端库，这是一个用于集中管理应用程序配置的托管服务。

安装

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-data-appconfiguration</artifactId>
    <version>1.8.0</version>
</dependency>

或者使用 Azure SDK BOM：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-data-appconfiguration</artifactId>
    </dependency>
</dependencies>

前置条件

• Azure App Configuration 存储实例

• 连接字符串或 Entra ID 凭据

环境变量

AZURE_APPCONFIG_CONNECTION_STRING=Endpoint=https://<store>.azconfig.io;Id=<id>;Secret=<secret>
AZURE_APPCONFIG_ENDPOINT=https://<store>.azconfig.io

客户端创建

使用连接字符串

import com.azure.data.appconfiguration.ConfigurationClient;
import com.azure.data.appconfiguration.ConfigurationClientBuilder;
ConfigurationClient configClient = new ConfigurationClientBuilder()
    .connectionString(System.getenv("AZURE_APPCONFIG_CONNECTION_STRING"))
    .buildClient();

异步客户端

import com.azure.data.appconfiguration.ConfigurationAsyncClient;
ConfigurationAsyncClient asyncClient = new ConfigurationClientBuilder()
    .connectionString(connectionString)
    .buildAsyncClient();

使用 Entra ID（推荐）

import com.azure.identity.DefaultAzureCredentialBuilder;
ConfigurationClient configClient = new ConfigurationClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint(System.getenv("AZURE_APPCONFIG_ENDPOINT"))
    .buildClient();

核心概念

| 概念 | 描述 |
|---------|-------------|
| 配置设置 (Configuration Setting) | 带有可选标签的键值对 |
| 标签 (Label) | 用于区分设置的维度（例如：环境） |
| 功能标志 (Feature Flag) | 用于功能管理的特殊设置 |
| 机密引用 (Secret Reference) | 指向 Key Vault 机密的设置 |
| 快照 (Snapshot) | 设置在特定时间点的不可变视图 |

配置设置操作

创建设置 (Add)

仅在设置不存在时创建：

import com.azure.data.appconfiguration.models.ConfigurationSetting;
ConfigurationSetting setting = configClient.addConfigurationSetting(
    "app/database/connection", 
    "Production", 
    "Server=prod.db.com;Database=myapp"
);

创建或更新设置 (Set)

创建或覆盖：

ConfigurationSetting setting = configClient.setConfigurationSetting(
    "app/cache/enabled", 
    "Production", 
    "true"
);

获取设置

ConfigurationSetting setting = configClient.getConfigurationSetting(
    "app/database/connection", 
    "Production"
);
System.out.println("Value: " + setting.getValue());
System.out.println("Content-Type: " + setting.getContentType());
System.out.println("Last Modi");

### 条件获取（如果已更改）

Response<ConfigurationSetting> response = configClient.getConfigurationSettingWithResponse(
setting, // 带有 ETag 的设置
null, // 接受日期时间
true, // ifChanged - 仅在已修改时获取
Context.NONE
);

if (response.getStatusCode() == 304) {
System.out.println("设置未修改");
} else {
ConfigurationSetting updated = response.getValue();
}

### 更新设置

### 条件更新（如果未更改）

### 删除设置

### 条件删除

## 列出并筛选设置

按键模式列出

SettingSelector selector = new SettingSelector()
.setKeyFilter("app/*");

PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);
for (ConfigurationSetting s : settings) {
System.out.println(s.getKey() + " = " + s.getValue());
}

### 按标签列出

PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);

### 按多个键列出

PagedIterable<ConfigurationSetting> settings = configClient.listConfigurationSettings(selector);

### 列出修订版本

PagedIterable<ConfigurationSetting> revisions = configClient.listRevisions(selector);
for (ConfigurationSetting revision : revisions) {
System.out.println("Value: " + revision.getValue() + ", Modified: " + revision.getLastModified());
}

## 功能标志 (Feature Flags)

创建功能标志

FeatureFlagFilter percentageFilter = new FeatureFlagFilter("Microsoft.Percentage")
.addParameter("Value", 50);

FeatureFlagConfigurationSetting featureFlag = new FeatureFlagConfigurationSetting("beta-feature", true)
.setDescription("Beta feature rollout")
.setClientFilters(Arrays.asList(percentageFilter));

FeatureFlagConfigurationSetting created = (FeatureFlagConfigurationSetting)
configClient.addConfigurationSetting(featureFlag);

### 获取功能标志

System.out.println("Feature: " + flag.getFeatureId());
System.out.println("Enabled: " + flag.isEnabled());
System.out.println("Filters: " + flag.getClientFilters());

### 更新功能标志 (Feature Flag)

## 机密引用 (Secret References)

创建机密引用

SecretReferenceConfigurationSetting secretRef = new SecretReferenceConfigurationSetting(
"app/secrets/api-key",
"https://myvault.vault.azure.net/secrets/api-key"
);

SecretReferenceConfigurationSetting created = (SecretReferenceConfigurationSetting)
configClient.addConfigurationSetting(secretRef);

### 获取机密引用

System.out.println("Secret URI: " + ref.getSecretId());

## 只读设置 (Read-Only Settings)

设置为只读

### 取消只读

## 快照 (Snapshots)
创建快照

List<ConfigurationSettingsFilter> filters = new ArrayList<>();
filters.add(new ConfigurationSettingsFilter("app/*"));

SyncPoller<PollOperationDetails, ConfigurationSnapshot> poller = configClient.beginCreateSnapshot(
"release-v1.0",
new ConfigurationSnapshot(filters),
Context.NONE
);
poller.setPollInterval(Duration.ofSeconds(10));
poller.waitForCompletion();

ConfigurationSnapshot snapshot = poller.getFinalResult();
System.out.println("Snapshot: " + snapshot.getName() + ", Status: " + snapshot.getStatus());

### 获取快照

### 列出快照中的设置

for (ConfigurationSetting setting : settings) {
System.out.println(setting.getKey() + " = " + setting.getValue());
}

### 归档快照

### 恢复快照

### 列出所有快照

SnapshotSelector selector = new SnapshotSelector().setNameFilter("release-*");
PagedIterable<ConfigurationSnapshot> snapshots = configClient.listSnapshots(selector);

for (ConfigurationSnapshot snap : snapshots) {
System.out.println(snap.getName() + " - " + snap.getStatus());
}

## 标签

列出标签

configClient.listLabels(new SettingLabelSelector().setNameFilter("*"))
.forEach(label -> System.out.println("Label: " + label.getName()));

## 异步操作

// 使用响应式流进行异步列出
asyncClient.listConfigurationSettings(new SettingSelector().setLabelFilter("Production"))
.subscribe(
setting -> System.out.println(setting.getKey() + " = " + setting.getValue()),
error -> System.err.println("Error: " + error.getMessage()),
() -> System.out.println("Completed")
);

## 错误处理

try {
configClient.getConfigurationSetting("nonexistent", null);
} catch (HttpResponseException e) {
if (e.getResponse().getStatusCode() == 404) {
System.err.println("Setting not found");
} else {
System.err.println("Error: " + e.getMessage());
}
}
```

最佳实践

1. 使用标签 — 按环境（开发、测试、生产）区分配置
2. 使用快照 — 为发布创建不可变的快照
3. 功能标志 (Feature flags) — 用于渐进式发布和 A/B 测试
4. 机密引用 — 将敏感值存储在 Key Vault 中
5. 条件请求 — 使用 ETag 实现乐观并发控制
6. 只读保护 — 锁定关键的生产设置
7. 使用 Entra ID — 优先于连接字符串
8. 异步客户端 — 适用于高吞吐量场景

参考链接

| 资源 | URL |
|----------|-----|
| Maven 包 | https://central.sonatype.com/artifact/com.azure/azure-data-appconfiguration |
| GitHub | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-data-appconfiguration |
| API 文档 | https://aka.ms/java-docs |
| 产品文档 | https://learn.microsoft.com/azure/azure-app-configuration |
| 示例代码 | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/appconfiguration/azure-data-appconfiguration/src/samples |
| 故障排除 | https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/appconfiguration/azure-data-appconfiguration/TROUBLESHOOTING.md |

适用场景

局限性

• 仅在任务与上述范围明确匹配时使用此技能。

• 不要将输出视为针对特定环境的验证、测试或专家评审的替代方案。

• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。