TTMusic/配置系统使用说明.md

应用配置系统使用说明

概述

本应用实现了一个基于远程API的配置管理系统，可以在应用启动时从 https://pay.ss5.xyz/switches/lists 获取配置参数，并将这些参数保存到AppStorage中供全应用使用。

功能特性

1. 自动初始化：应用启动时自动从API获取配置
2. 类型支持：支持 json、boolean、number、string 四种数据类型
3. 全局访问：配置保存在AppStorage中，可在任意页面访问
4. 实时更新：支持手动刷新配置
5. 错误处理：网络异常时使用默认值，不影响应用正常运行

API接口格式

{
  "code": 0,
  "msg": "请求成功",
  "data": [
    {
      "name": "test_json",
      "description": "test_json",
      "value": "{\n \"test_json\": \"test_json\"\n}",
      "type": "json"
    },
    {
      "name": "show_update_log",
      "description": "是否显示日志更新弹窗",
      "value": false,
      "type": "boolean"
    },
    {
      "name": "test_number",
      "description": "test_number",
      "value": 123456,
      "type": "number"
    },
    {
      "name": "test_string",
      "description": "test_string",
      "value": "test_string",
      "type": "string"
    }
  ]
}

核心文件

1. ConfigManager.ets

配置管理器，负责：

• 从API获取配置数据
• 解析不同类型的配置值
• 保存配置到AppStorage
• 提供配置读取和更新接口

2. ConfigDisplayView.ets

配置展示组件，用于：

• 在设置页面展示当前配置
• 提供配置刷新功能
• 实时监听配置变化

使用方法

1. 初始化配置（已在SplashIndex中实现）

import { ConfigManager } from '../common/util/ConfigManager';

// 在应用启动时初始化配置
const success = await ConfigManager.initConfig();

2. 读取配置

import { ConfigManager, ConfigValue } from '../common/util/ConfigManager';

// 方法1：使用ConfigManager（推荐，类型安全）
const showUpdateLog: boolean = ConfigManager.getConfig('show_update_log', false);
const testNumber: number = ConfigManager.getConfig('test_number', 0);
const testString: string = ConfigManager.getConfig('test_string', '');
const testJson: ESObject = ConfigManager.getConfig('test_json', {});

// 方法2：直接从AppStorage读取
const showUpdateLog = AppStorage.get('show_update_log') as boolean ?? false;

3. 在组件中监听配置变化

@Component
export struct MyComponent {
  // 使用@StorageLink监听配置变化，确保类型安全
  @StorageLink('show_update_log') showUpdateLog: boolean = false;
  @StorageLink('test_number') testNumber: number = 0;
  @StorageLink('test_string') testString: string = '';
  @StorageLink('test_json') testJson: ESObject = {};

  build() {
    Column() {
      Text(`显示更新日志: ${this.showUpdateLog}`)
      Text(`测试数字: ${this.testNumber}`)
      Text(`测试字符串: ${this.testString}`)
      Text(`JSON配置: ${JSON.stringify(this.testJson)}`)
    }
  }
}

4. 更新配置

import { ConfigValue } from '../common/util/ConfigManager';

// 设置单个配置（类型安全）
ConfigManager.setConfig('show_update_log', true as ConfigValue);
ConfigManager.setConfig('test_number', 123 as ConfigValue);
ConfigManager.setConfig('test_string', 'new value' as ConfigValue);

// 刷新所有配置
const success: boolean = await ConfigManager.refreshConfig();

实际应用示例

UpdateLogManager中的使用

// 从API配置中获取是否显示更新日志的设置
const showUpdateLog = ConfigManager.getConfig('show_update_log', false);
if (!showUpdateLog) {
  Logger.info(UpdateLogManager.TAG, '更新日志功能已通过API配置禁用');
  return false;
}

错误处理

1. 网络异常：使用默认值，记录错误日志
2. JSON解析失败：保持原始字符串值
3. 类型转换失败：使用默认值

注意事项

1. 配置初始化是异步操作，确保在使用配置前完成初始化
2. 配置键名要与API返回的name字段保持一致
3. 为每个配置提供合理的默认值
4. 配置变化会自动触发使用@StorageLink的组件重新渲染

扩展建议

1. 可以添加配置缓存机制，减少网络请求
2. 可以添加配置版本控制，支持增量更新
3. 可以添加配置验证机制，确保配置值的有效性
4. 可以添加配置分组功能，支持不同模块的配置管理