15 KiB
15 KiB
CLR Configuration - 配置服务SDK
模块概述
clr_configuration 是 OneApp 配置服务的核心 SDK，为应用配置管理提供底层的 API 封装和数据处理能力。该 SDK 封装了配置服务的网络接口、数据模型、同步机制和变更通知等功能，为上层的配置管理模块提供稳定可靠的服务支撑。
核心功能
1. 配置 API 封装
- RESTful API：配置服务 REST API 封装
- GraphQL API：配置查询 GraphQL 接口
- WebSocket API：实时配置更新接口
- 批量操作：配置批量读写操作
2. 配置数据模型
- 数据结构：标准化的配置数据结构
- 类型系统：强类型配置值系统
- 序列化：配置数据序列化和反序列化
- 验证机制：配置数据有效性验证
3. 配置同步机制
- 增量同步：配置变更增量同步
- 冲突解决：配置冲突解决策略
- 版本控制：配置版本管理机制
- 事务支持：配置操作事务保证
4. 配置变更通知
- 事件驱动：基于事件的变更通知
- 订阅机制：配置变更订阅管理
- 推送通知：实时推送配置变更
- 回调处理：配置变更回调处理
技术架构
架构设计
┌─────────────────────────────────────┐
│ 配置管理应用层 │
│ (app_configuration) │
├─────────────────────────────────────┤
│ CLR Configuration │
│ ┌──────────┬──────────┬──────────┐ │
│ │ API封装 │ 数据模型 │ 同步引擎 │ │
│ ├──────────┼──────────┼──────────┤ │
│ │ 事件系统 │ 缓存层 │ 安全模块 │ │
│ └──────────┴──────────┴──────────┘ │
├─────────────────────────────────────┤
│ 网络通信层 │
│ (HTTP/WebSocket/GraphQL) │
├─────────────────────────────────────┤
│ 配置服务后端 │
│ (Configuration Server) │
└─────────────────────────────────────┘
核心组件
1. API 客户端 (ApiClient)
class ConfigurationApiClient {
// 获取配置
Future<ApiResponse<ConfigData>> getConfiguration(GetConfigRequest request);
// 设置配置
Future<ApiResponse<bool>> setConfiguration(SetConfigRequest request);
// 批量获取配置
Future<ApiResponse<Map<String, ConfigData>>> getBatchConfiguration(BatchGetRequest request);
// 订阅配置变更
Stream<ConfigurationChange> subscribeConfigurationChanges(String key);
}
2. 数据模型管理器 (DataModelManager)
class ConfigurationDataModel {
// 序列化配置数据
Map<String, dynamic> serialize(ConfigData data);
// 反序列化配置数据
ConfigData deserialize(Map<String, dynamic> json);
// 验证配置数据
ValidationResult validate(ConfigData data);
// 转换配置数据类型
T convertValue<T>(dynamic value, ConfigType targetType);
}
3. 同步引擎 (SyncEngine)
class ConfigurationSyncEngine {
// 开始同步
Future<SyncResult> startSync(SyncOptions options);
// 增量同步
Future<SyncResult> incrementalSync(String lastSyncVersion);
// 解决冲突
Future<ConflictResolution> resolveConflict(ConfigurationConflict conflict);
// 回滚配置
Future<bool> rollbackConfiguration(String version);
}
4. 事件系统 (EventSystem)
class ConfigurationEventSystem {
// 发布事件
void publishEvent(ConfigurationEvent event);
// 订阅事件
StreamSubscription<T> subscribe<T extends ConfigurationEvent>(EventHandler<T> handler);
// 取消订阅
void unsubscribe(StreamSubscription subscription);
// 清理事件
void clearEvents([String? eventType]);
}
数据模型
配置数据模型
class ConfigData {
final String key;
final dynamic value;
final ConfigType type;
final String version;
final DateTime timestamp;
final Map<String, String> metadata;
final List<String> tags;
final ConfigScope scope;
final bool isEncrypted;
final String? description;
}
enum ConfigType {
string,
integer,
double,
boolean,
json,
array,
binary
}
enum ConfigScope {
global,
user,
device,
session
}
配置变更模型
class ConfigurationChange {
final String key;
final dynamic oldValue;
final dynamic newValue;
final ChangeType changeType;
final String version;
final DateTime timestamp;
final String? userId;
final String? source;
final Map<String, dynamic> context;
}
enum ChangeType {
created,
updated,
deleted,
restored
}
API 请求模型
class GetConfigRequest {
final String key;
final ConfigScope? scope;
final String? version;
final bool includeMetadata;
final List<String>? tags;
}
class SetConfigRequest {
final String key;
final dynamic value;
final ConfigType type;
final ConfigScope scope;
final Map<String, String>? metadata;
final List<String>? tags;
final bool encrypt;
}
API 接口
配置操作接口
abstract class ConfigurationApi {
// 获取单个配置
Future<ApiResponse<ConfigData>> getConfig(String key, {ConfigScope? scope});
// 设置单个配置
Future<ApiResponse<bool>> setConfig(String key, dynamic value, {ConfigType? type, ConfigScope? scope});
// 删除配置
Future<ApiResponse<bool>> deleteConfig(String key, {ConfigScope? scope});
// 检查配置是否存在
Future<ApiResponse<bool>> hasConfig(String key, {ConfigScope? scope});
}
批量操作接口
abstract class BatchConfigurationApi {
// 批量获取配置
Future<ApiResponse<Map<String, ConfigData>>> getBatchConfigs(List<String> keys);
// 批量设置配置
Future<ApiResponse<BatchResult>> setBatchConfigs(Map<String, dynamic> configs);
// 批量删除配置
Future<ApiResponse<BatchResult>> deleteBatchConfigs(List<String> keys);
}
同步接口
abstract class ConfigurationSyncApi {
// 获取配置版本
Future<ApiResponse<ConfigVersion>> getConfigVersion();
// 同步配置
Future<ApiResponse<SyncResult>> syncConfigurations(SyncRequest request);
// 获取配置变更历史
Future<ApiResponse<List<ConfigurationChange>>> getChangeHistory(ChangeHistoryRequest request);
}
配置管理
SDK 配置
class ConfigurationSdkConfig {
final String serverUrl;
final String apiKey;
final String clientId;
final Duration timeout;
final int maxRetries;
final bool enableCache;
final bool enableEncryption;
final LogLevel logLevel;
static const ConfigurationSdkConfig defaultConfig = ConfigurationSdkConfig(
serverUrl: 'https://config-api.oneapp.com',
timeout: Duration(seconds: 30),
maxRetries: 3,
enableCache: true,
enableEncryption: true,
logLevel: LogLevel.info,
);
}
缓存配置
class CacheConfig {
final Duration ttl;
final int maxSize;
final bool enableCompression;
final CacheEvictionPolicy evictionPolicy;
static const CacheConfig defaultCacheConfig = CacheConfig(
ttl: Duration(minutes: 30),
maxSize: 1000,
enableCompression: true,
evictionPolicy: CacheEvictionPolicy.lru,
);
}
使用示例
基本配置操作
// 初始化 SDK
final configSdk = ConfigurationSdk.instance;
await configSdk.initialize(ConfigurationSdkConfig.defaultConfig);
// 获取配置
try {
final config = await configSdk.getConfig('app.theme');
print('当前主题: ${config.value}');
} catch (e) {
print('获取配置失败: $e');
}
// 设置配置
await configSdk.setConfig(
'user.language',
'zh-CN',
type: ConfigType.string,
scope: ConfigScope.user,
);
// 删除配置
await configSdk.deleteConfig('temp.data');
批量配置操作
// 批量获取配置
final keys = ['app.theme', 'app.language', 'app.version'];
final batchResult = await configSdk.getBatchConfigs(keys);
for (final entry in batchResult.entries) {
print('${entry.key}: ${entry.value.value}');
}
// 批量设置配置
final batchConfigs = {
'ui.showTips': true,
'ui.animationSpeed': 1.0,
'ui.darkMode': false,
};
await configSdk.setBatchConfigs(batchConfigs);
配置变更监听
// 监听特定配置变更
configSdk.subscribeConfigurationChanges('app.theme').listen((change) {
print('主题配置变更: ${change.oldValue} -> ${change.newValue}');
// 应用新的主题配置
applyThemeConfig(change.newValue);
});
// 监听所有配置变更
configSdk.onConfigurationChanged.listen((change) {
print('配置变更: ${change.key}');
logConfigurationChange(change);
});
配置同步
// 检查是否有配置更新
final currentVersion = await configSdk.getConfigVersion();
final hasUpdate = await configSdk.checkForUpdates(currentVersion.version);
if (hasUpdate) {
// 执行增量同步
final syncResult = await configSdk.incrementalSync(currentVersion.version);
if (syncResult.isSuccess) {
print('配置同步成功，更新了 ${syncResult.updatedCount} 个配置');
} else {
print('配置同步失败: ${syncResult.error}');
}
}
测试策略
单元测试
group('ConfigurationSdk Tests', () {
test('should get configuration successfully', () async {
// Given
final sdk = ConfigurationSdk();
await sdk.initialize(ConfigurationSdkConfig.defaultConfig);
// When
final result = await sdk.getConfig('test.key');
// Then
expect(result.key, 'test.key');
expect(result.value, isNotNull);
});
test('should handle configuration not found', () async {
// Given
final sdk = ConfigurationSdk();
// When & Then
expect(
() => sdk.getConfig('nonexistent.key'),
throwsA(isA<ConfigurationNotFoundException>()),
);
});
});
集成测试
group('Configuration Integration Tests', () {
testWidgets('configuration sync flow', (tester) async {
// 1. 初始化 SDK
await ConfigurationSdk.instance.initialize(testConfig);
// 2. 设置配置
await ConfigurationSdk.instance.setConfig('test.sync', 'value1');
// 3. 模拟远程配置变更
await simulateRemoteConfigChange('test.sync', 'value2');
// 4. 执行同步
final syncResult = await ConfigurationSdk.instance.sync();
// 5. 验证同步结果
expect(syncResult.isSuccess, true);
final updatedConfig = await ConfigurationSdk.instance.getConfig('test.sync');
expect(updatedConfig.value, 'value2');
});
});
性能优化
缓存策略
- 多级缓存：内存 + 磁盘多级缓存
- 智能预加载：预测性配置预加载
- 缓存压缩：配置数据压缩存储
- 缓存更新：增量缓存更新机制
网络优化
- 连接复用：HTTP 连接池复用
- 请求合并：相关配置请求合并
- 数据压缩：传输数据 gzip 压缩
- 离线模式：离线配置访问支持
错误处理
错误类型
abstract class ConfigurationException implements Exception {
final String message;
final String? errorCode;
final Map<String, dynamic>? details;
const ConfigurationException(this.message, [this.errorCode, this.details]);
}
class ConfigurationNotFoundException extends ConfigurationException {
const ConfigurationNotFoundException(String key)
: super('Configuration not found: $key', 'CONFIG_NOT_FOUND');
}
class ConfigurationValidationException extends ConfigurationException {
const ConfigurationValidationException(String message, Map<String, dynamic> details)
: super(message, 'VALIDATION_ERROR', details);
}
class ConfigurationSyncException extends ConfigurationException {
const ConfigurationSyncException(String message)
: super(message, 'SYNC_ERROR');
}
重试机制
class RetryConfig {
final int maxRetries;
final Duration initialDelay;
final double backoffMultiplier;
final Duration maxDelay;
static const RetryConfig defaultRetryConfig = RetryConfig(
maxRetries: 3,
initialDelay: Duration(seconds: 1),
backoffMultiplier: 2.0,
maxDelay: Duration(seconds: 30),
);
}
安全机制
数据加密
class ConfigurationEncryption {
// 加密配置值
String encryptValue(String value, String key);
// 解密配置值
String decryptValue(String encryptedValue, String key);
// 生成加密密钥
String generateEncryptionKey();
// 验证数据完整性
bool verifyIntegrity(String data, String signature);
}
访问控制
class ConfigurationAccessControl {
// 检查读权限
bool hasReadPermission(String key, String userId);
// 检查写权限
bool hasWritePermission(String key, String userId);
// 检查删除权限
bool hasDeletePermission(String key, String userId);
// 获取用户权限
List<Permission> getUserPermissions(String userId);
}
监控和诊断
性能监控
- API 响应时间：配置 API 响应时间监控
- 缓存命中率：配置缓存命中率统计
- 错误率：配置操作错误率监控
- 同步性能：配置同步性能指标
使用统计
- 配置访问频率：统计配置项访问频率
- 热点配置：识别热点配置项
- 用户行为：分析用户配置使用模式
- 性能瓶颈：识别性能瓶颈点
版本历史
v0.2.8+5 (当前版本)
- 新增 GraphQL 查询支持
- 优化配置同步性能
- 支持配置数据压缩
- 修复并发访问问题
v0.2.7
- 支持配置数据加密
- 新增批量操作接口
- 优化缓存机制
- 改进错误处理
依赖关系
内部依赖
basic_network: 网络请求基础库basic_storage: 本地存储服务basic_error: 错误处理框架basic_logger: 日志记录服务
外部依赖
dio: HTTP 客户端json_annotation: JSON 序列化encrypt: 数据加密库rxdart: 响应式编程支持
总结
clr_configuration 作为配置服务的核心 SDK，为 OneApp 的配置管理提供了强大的底层支撑。通过标准化的 API 接口、完善的数据模型、可靠的同步机制和实时的变更通知，该 SDK 确保了配置服务的高性能、高可用和高安全性，为上层应用提供了稳定可靠的配置管理能力。