14 KiB
14 KiB
App Configuration - 应用配置管理模块
模块概述
app_configuration 是 OneApp 的车辆配置管理模块，专注于车辆配置选择和管理功能。该模块提供了完整的车辆配置解决方案，包括车型选择、外观配置、内饰配置、选装配置等功能。
核心功能
1. 车辆配置管理
- 车型配置页面：提供完整的车辆配置选择界面
- 配置选项管理：支持各种车辆配置选项
- 3D模型展示：集成3D车辆模型展示功能
- 配置验证：配置有效性验证机制
2. 模块导出组件
基于真实项目代码的主要导出：
library app_configuration;
// 车辆配置页面
export 'src/app_modules/car_configuration/pages/car_configuration_page.dart';
// 车辆配置状态管理
export 'src/app_modules/car_configuration/blocs/car_configuration_bloc.dart';
// 配置相关组件
export 'src/app_modules/car_configuration/widgets/car_rights_dialog_widget.dart';
export 'src/app_modules/car_configuration/widgets/car_order_count_exception_dialog.dart';
// 路由导出
export 'src/route_export.dart';
// 配置常量
export 'src/app_modules/car_configuration/configuration_constant.dart';
3. 车辆配置页面 (CarConfigurationPage)
核心配置页面实现：
/// 车辆配置页面
class CarConfigurationPage extends StatefulWidget with RouteObjProvider {
CarConfigurationPage({
Key? key,
this.carModelCode,
this.smallPreOrderNum,
this.carOrderNum,
this.needDepositAmount,
this.pageFrom = PageFrom.pageNone,
}) : super(key: key);
/// 已选车型配置代码
final String? carModelCode;
/// 小订订单号，创建大定时可以关联小订
final String? smallPreOrderNum;
/// 大定修改订单原始订单号
final String? carOrderNum;
/// 大定修改，大定定金金额
final double? needDepositAmount;
/// 页面来源类型
PageFrom? pageFrom = PageFrom.pageNone;
@override
State<CarConfigurationPage> createState() => _CarConfigurationPageState();
}
4. 模块架构组件
实际项目包含的配置组件：
- car_3D_model_webview.dart: 3D车辆模型WebView组件
- car_exterior_config.dart: 车辆外观配置组件
- car_interior_config.dart: 车辆内饰配置组件
- car_model_config_new.dart: 新版车型配置组件
- car_option_config.dart: 车辆选装配置组件
- config_bottom_bar_widget.dart: 配置底部栏组件
- configuration_tab.dart: 配置选项卡组件
技术架构
模块注册
/// App配置模块
class AppConfigurationModule extends Module with RouteObjProvider {
@override
List<Module> get imports => [];
@override
List<Bind> get binds => [];
@override
List<ModularRoute> get routes {
final r1 = RouteCenterAPI.routeMetaBy(
AppConfigurationRouteExport.keyAppConfiguration
);
return [
ChildRoute(
r1.path,
child: (_, args) => r1.provider(args).as(),
guards: loginGuardList,
),
];
}
}
目录结构
基于实际项目结构：
lib/
├── app_configuration.dart # 主导出文件
├── generated/ # 生成的国际化文件
├── l10n/ # 国际化资源文件
└── src/ # 源代码目录
├── app_modules/ # 应用模块
│ └── car_configuration/ # 车辆配置模块
│ ├── blocs/ # BLoC状态管理
│ ├── model/ # 数据模型
│ ├── pages/ # 页面组件
│ ├── widgets/ # 配置组件
│ └── configuration_constant.dart # 配置常量
├── app_defines/ # 应用定义
└── route_export.dart # 路由导出
核心组件
1. 配置管理器 (ConfigurationManager)
class ConfigurationManager {
// 初始化配置管理器
Future<bool> initialize(ConfigurationConfig config);
// 获取配置值
T? getValue<T>(String key, {T? defaultValue});
// 设置配置值
Future<bool> setValue<T>(String key, T value);
// 删除配置
Future<bool> removeValue(String key);
// 获取所有配置
Map<String, dynamic> getAllConfigurations();
}
2. 远程配置服务 (RemoteConfigService)
class RemoteConfigService {
// 从服务端获取配置
Future<ConfigurationResult> fetchRemoteConfig();
// 检查配置更新
Future<bool> checkForUpdates();
// 应用远程配置
Future<bool> applyRemoteConfig(Map<String, dynamic> config);
// 获取配置版本信息
Future<ConfigVersion> getConfigVersion();
}
3. 本地缓存管理器 (LocalCacheManager)
class LocalCacheManager {
// 缓存配置到本地
Future<bool> cacheConfiguration(String key, dynamic value);
// 从缓存获取配置
T? getCachedConfiguration<T>(String key);
// 清除缓存
Future<bool> clearCache([String? key]);
// 获取缓存大小
Future<int> getCacheSize();
// 压缩缓存数据
Future<bool> compressCache();
}
4. 环境管理器 (EnvironmentManager)
class EnvironmentManager {
// 设置当前环境
Future<bool> setCurrentEnvironment(Environment environment);
// 获取当前环境
Environment getCurrentEnvironment();
// 获取环境配置
Map<String, dynamic> getEnvironmentConfig(Environment environment);
// 验证环境配置
Future<bool> validateEnvironmentConfig(Environment environment);
}
数据模型
配置模型
class Configuration {
final String key;
final dynamic value;
final ConfigurationType type;
final DateTime createdAt;
final DateTime updatedAt;
final String version;
final Map<String, dynamic> metadata;
final bool isRemote;
final bool isEncrypted;
}
enum ConfigurationType {
string,
integer,
double,
boolean,
json,
list
}
环境模型
enum Environment {
development,
testing,
staging,
production
}
class EnvironmentConfig {
final Environment environment;
final String baseUrl;
final String apiKey;
final Map<String, String> headers;
final int timeout;
final bool enableLogging;
final Map<String, dynamic> features;
}
配置版本模型
class ConfigVersion {
final String version;
final DateTime publishTime;
final String description;
final List<String> changedKeys;
final Map<String, dynamic> changeset;
final bool isForced;
final DateTime expireTime;
}
API 接口
配置管理接口
abstract class ConfigurationService {
// 初始化配置服务
Future<ApiResponse<bool>> initialize(InitConfigRequest request);
// 获取配置
Future<ApiResponse<ConfigurationResult>> getConfiguration(GetConfigRequest request);
// 批量获取配置
Future<ApiResponse<Map<String, dynamic>>> getBatchConfiguration(BatchConfigRequest request);
// 更新配置
Future<ApiResponse<bool>> updateConfiguration(UpdateConfigRequest request);
}
远程配置接口
abstract class RemoteConfigurationService {
// 获取远程配置
Future<ApiResponse<Map<String, dynamic>>> fetchRemoteConfiguration(FetchConfigRequest request);
// 检查配置更新
Future<ApiResponse<UpdateCheckResult>> checkConfigurationUpdate(CheckUpdateRequest request);
// 上报配置使用情况
Future<ApiResponse<bool>> reportConfigurationUsage(UsageReportRequest request);
}
配置管理
默认配置
class DefaultConfiguration {
static const Map<String, dynamic> defaultConfig = {
'app': {
'name': 'OneApp',
'version': '1.0.0',
'debug': false,
},
'network': {
'timeout': 30000,
'retryCount': 3,
'enableCache': true,
},
'ui': {
'theme': 'auto',
'language': 'auto',
'animations': true,
},
'features': {
'enableAnalytics': true,
'enablePush': true,
'enableLocation': false,
},
};
}
环境配置
class EnvironmentConfiguration {
static const Map<Environment, EnvironmentConfig> environments = {
Environment.development: EnvironmentConfig(
environment: Environment.development,
baseUrl: 'https://dev-api.oneapp.com',
apiKey: 'dev_api_key',
enableLogging: true,
),
Environment.production: EnvironmentConfig(
environment: Environment.production,
baseUrl: 'https://api.oneapp.com',
apiKey: 'prod_api_key',
enableLogging: false,
),
};
}
使用示例
基本配置管理
// 初始化配置管理器
final configManager = ConfigurationManager.instance;
await configManager.initialize(ConfigurationConfig.defaultConfig);
// 获取配置值
final appName = configManager.getValue<String>('app.name', defaultValue: 'OneApp');
final timeout = configManager.getValue<int>('network.timeout', defaultValue: 30000);
final enableAnalytics = configManager.getValue<bool>('features.enableAnalytics', defaultValue: true);
// 设置配置值
await configManager.setValue('ui.theme', 'dark');
await configManager.setValue('features.enablePush', false);
// 监听配置变化
configManager.onConfigurationChanged.listen((change) {
print('配置变更: ${change.key} = ${change.newValue}');
});
远程配置更新
// 检查远程配置更新
final remoteConfigService = RemoteConfigService.instance;
final hasUpdate = await remoteConfigService.checkForUpdates();
if (hasUpdate) {
// 获取远程配置
final remoteConfig = await remoteConfigService.fetchRemoteConfig();
if (remoteConfig.isSuccess) {
// 应用远程配置
await remoteConfigService.applyRemoteConfig(remoteConfig.data);
print('远程配置已更新');
}
}
// 监听远程配置更新
remoteConfigService.onRemoteConfigUpdated.listen((config) {
print('收到远程配置更新');
// 处理配置更新逻辑
});
环境配置切换
// 获取当前环境
final currentEnv = EnvironmentManager.instance.getCurrentEnvironment();
print('当前环境: $currentEnv');
// 切换到测试环境
await EnvironmentManager.instance.setCurrentEnvironment(Environment.testing);
// 获取环境配置
final envConfig = EnvironmentManager.instance.getEnvironmentConfig(Environment.testing);
print('测试环境配置: $envConfig');
// 验证环境配置
final isValid = await EnvironmentManager.instance.validateEnvironmentConfig(Environment.testing);
if (!isValid) {
print('环境配置验证失败');
}
配置缓存管理
// 缓存配置
final cacheManager = LocalCacheManager.instance;
await cacheManager.cacheConfiguration('user_preferences', userPreferences);
// 获取缓存配置
final cachedPreferences = cacheManager.getCachedConfiguration<Map<String, dynamic>>('user_preferences');
// 获取缓存大小
final cacheSize = await cacheManager.getCacheSize();
print('缓存大小: ${cacheSize}KB');
// 清理缓存
if (cacheSize > 1024 * 1024) { // 超过1MB
await cacheManager.compressCache();
}
测试策略
单元测试
group('ConfigurationManager Tests', () {
test('should get and set configuration values', () async {
// Given
final configManager = ConfigurationManager();
await configManager.initialize(ConfigurationConfig.defaultConfig);
// When
await configManager.setValue('test.key', 'test_value');
final value = configManager.getValue<String>('test.key');
// Then
expect(value, 'test_value');
});
test('should return default value when key not found', () {
// Given
final configManager = ConfigurationManager();
// When
final value = configManager.getValue<String>('nonexistent.key', defaultValue: 'default');
// Then
expect(value, 'default');
});
});
集成测试
group('Configuration Integration Tests', () {
testWidgets('configuration update flow', (tester) async {
// 1. 初始化配置
await ConfigurationManager.instance.initialize(ConfigurationConfig.defaultConfig);
// 2. 模拟远程配置更新
final mockRemoteConfig = {'feature.newFeature': true};
await RemoteConfigService.instance.applyRemoteConfig(mockRemoteConfig);
// 3. 验证配置已更新
final newFeatureEnabled = ConfigurationManager.instance.getValue<bool>('feature.newFeature');
expect(newFeatureEnabled, true);
});
});
性能优化
缓存策略
- 内存缓存：热点配置内存缓存
- 磁盘缓存：所有配置磁盘持久化
- 缓存过期：配置缓存过期机制
- 预加载：应用启动时预加载关键配置
网络优化
- 增量同步：只同步变化的配置项
- 压缩传输：配置数据压缩传输
- 批量操作：批量获取和更新配置
- 连接池：网络连接池优化
安全考虑
数据安全
- 配置加密：敏感配置加密存储
- 传输加密：配置传输使用HTTPS
- 签名验证：配置数据签名验证
- 访问控制：配置访问权限控制
隐私保护
- 数据最小化：只收集必要的配置数据
- 匿名化：用户相关配置匿名化
- 数据清理：定期清理过期配置
- 透明度：配置使用透明化
监控和诊断
性能监控
- 配置使用统计：统计配置项使用频率
- 更新性能：监控配置更新性能
- 缓存命中率：监控缓存命中率
- 网络性能：监控配置网络请求性能
故障诊断
- 配置验证：配置数据有效性验证
- 更新失败恢复：配置更新失败自动恢复
- 异常监控：配置相关异常监控
- 健康检查：配置服务健康检查
版本历史
v0.2.6+8 (当前版本)
- 新增配置热更新功能
- 优化缓存性能
- 支持配置分组管理
- 修复环境切换问题
v0.2.5
- 支持远程配置灰度发布
- 新增配置使用统计
- 优化配置同步机制
- 改进错误处理
依赖关系
内部依赖
clr_configuration: 配置服务SDKbasic_storage: 本地存储服务basic_network: 网络请求服务basic_error: 错误处理框架
外部依赖
shared_preferences: 本地配置存储dio: HTTP客户端encrypt: 数据加密rxdart: 响应式编程
总结
app_configuration 作为应用配置管理的核心模块，提供了完整的配置管理解决方案。通过远程配置、本地缓存、热更新和环境切换等功能，为 OneApp 提供了灵活、可靠、高效的配置管理能力，确保应用能够快速响应业务需求变化，同时保证用户体验的一致性和稳定性。