xdz-app/base-common

base-common 模块说明

📋 模块定位

base-common 是业务封装层，提供：

• 封装 base-core 的接口（BridgeManager、ConfigManager、ExecutorManager）
• MVVM 网络封装（ApiServiceFactory、ApiBaseRemoteDataSource）
• UI 基础类（BaseActivity、BaseFragment）

🎯 使用原则

• ✅ 业务层（app 模块）可以调用 base-common
• ✅ 能力层（capability 模块）也可以调用 base-common（如果需要业务封装）

---

📁 目录结构

1. bridge/ - 桥接服务封装

✅ BridgeManager.kt           - 封装 IBridge，提供 H5通信、模块间通信的便捷方法

功能：

• H5 通信：callH5Method()、onH5Call()
• 模块间通信：postEvent()、subscribeEvent()

2. config/ - 配置管理封装

✅ ConfigManager.kt           - 封装 IConfig，提供通用的配置管理
⚠️ ServerConfigManager.kt    - 特定业务场景（开发测试时的服务器配置，待移到 app 模块）

功能：

• 基础配置：getString()、getInt()、getBoolean()
• 环境切换：getEnvironment()、setEnvironment()
• 功能开关：isFeatureEnabled()、setFeatureEnabled()

3. executor/ - 执行器封装

✅ ExecutorManager.kt         - 封装 IExecutor，提供异步任务执行的便捷方法

功能：

• IO 线程执行：executeIO()
• 主线程执行：executeMain()
• 延迟执行：executeDelayed()
• 降级方案：如果 IExecutor 未注册，使用协程实现

4. network/ - MVVM 网络封装

✅ ApiServiceFactory.kt       - API 服务工厂，统一创建 API 服务实例
✅ ApiBaseRemoteDataSource.kt - 远程数据源基类，封装通用网络请求逻辑
✅ ApiBaseRepository.kt       - Repository 基类，提供通用错误处理和数据转换
✅ ApiResponseParser.kt       - 响应解析器，解析 Retrofit Response

功能：

• 统一创建 API 服务：ApiServiceFactory.create<AuthApi>()
• 统一错误处理：超时、网络异常、业务错误
• 自动线程切换：IO 线程执行请求
• 统一日志记录

5. ui/ - UI 基础类

✅ BaseActivity.kt            - Activity 基类，支持 ViewBinding、加载状态管理
✅ BaseFragment.kt            - Fragment 基类，支持 ViewBinding、加载状态管理
✅ ActivityExtensions.kt      - Activity 扩展函数，简化 StateFlow 观察
✅ FragmentExtensions.kt      - Fragment 扩展函数，简化 StateFlow 观察

功能：

• ViewBinding 支持
• 加载状态管理：showLoading()、hideLoading()
• 错误/成功消息显示：showError()、showSuccess()
• StateFlow 观察：observeStateFlow()

---

💡 核心作用

1. 封装 base-core 的接口

提供便捷的调用方式：

// 使用 BridgeManager（封装 IBridge）
BridgeManager.postEvent("user_login", userData)

// 使用 ConfigManager（封装 IConfig）
val apiUrl = ConfigManager.getString("api_url", "https://api.example.com")

// 使用 ExecutorManager（封装 IExecutor）
ExecutorManager.executeIO {
    // 执行耗时操作
}

2. MVVM 网络封装

简化网络请求：

// 创建 API 服务
val authApi = ApiServiceFactory.create<AuthApi>()

// 封装数据源
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiServiceFactory.create<AuthApi>()
    suspend fun login() = executeRequest { authApi.login() }
}

3. UI 基础类

简化 UI 开发：

class LoginActivity : BaseActivity<ActivityLoginBinding>() {
    override fun getViewBinding() = ActivityLoginBinding.inflate(layoutInflater)
    
    override fun initObserver() {
        observeStateFlow(viewModel.uiState) { state ->
            // 处理状态变化
        }
    }
}

---

📝 使用示例

业务层使用 base-common

1. 使用 BridgeManager（H5通信、模块间通信）

// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.bridge.BridgeManager

class MainActivity : AppCompatActivity() {
    fun initBridge() {
        // H5通信
        BridgeManager.callH5Method("showToast", "Hello")
        BridgeManager.onH5Call("getUserInfo") { result ->
            // 处理结果
        }
        
        // 模块间通信
        BridgeManager.postEvent("user_login", userData)
        BridgeManager.subscribeEvent("user_logout") { data ->
            // 处理事件
        }
    }
}

2. 使用 ConfigManager（配置管理）

// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.config.ConfigManager

class MainActivity : AppCompatActivity() {
    fun initConfig() {
        // 获取配置
        val apiUrl = ConfigManager.getString("api_url", "https://api.example.com")
        val isDebug = ConfigManager.getBoolean("is_debug", false)
        
        // 设置配置
        ConfigManager.setString("api_url", "https://api.example.com")
        ConfigManager.setEnvironment("prod")
        
        // 功能开关
        if (ConfigManager.isFeatureEnabled("new_feature")) {
            // 启用新功能
        }
    }
}

3. 使用 ExecutorManager（异步任务执行）

// app/src/.../MainActivity.kt
import com.narutohuo.xindazhou.common.executor.ExecutorManager

class MainActivity : AppCompatActivity() {
    fun executeTask() {
        // IO线程执行
        ExecutorManager.executeIO {
            // 执行耗时操作
            val data = fetchData()
            
            // 主线程更新UI
            ExecutorManager.executeMain {
                updateUI(data)
            }
        }
        
        // 延迟执行
        ExecutorManager.executeDelayed(1000) {
            // 1秒后执行
        }
    }
}

4. 使用 ApiServiceFactory（网络请求）

// Application 中初始化
class XinDaZhouApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // 设置默认 baseUrl
        ApiServiceFactory.baseUrlProvider = { 
            ServerConfigManager.getHttpServerUrl() 
        }
    }
}

// 业务层使用
class AuthRemoteDataSource : ApiBaseRemoteDataSource() {
    private val authApi = ApiServiceFactory.create<AuthApi>()
    
    suspend fun login(request: LoginRequest): Result<LoginResponse> {
        return executeRequest(
            request = { authApi.login(request) },
            errorMessage = "登录失败"
        )
    }
}

5. 使用 BaseActivity/BaseFragment（UI 基础类）

// app/src/.../LoginActivity.kt
import com.narutohuo.xindazhou.common.ui.BaseActivity
import com.narutohuo.xindazhou.common.ui.observeStateFlow

class LoginActivity : BaseActivity<ActivityLoginBinding>() {
    
    private val viewModel: LoginViewModel by viewModels()
    
    override fun getViewBinding() = ActivityLoginBinding.inflate(layoutInflater)
    
    override fun initView() {
        binding.btnLogin.setOnClickListener {
            viewModel.login()
        }
    }
    
    override fun initObserver() {
        // 观察 UI 状态
        observeStateFlow(viewModel.uiState) { state ->
            when (state) {
                is LoginUiState.Loading -> showLoading()
                is LoginUiState.Success -> {
                    hideLoading()
                    showSuccess("登录成功")
                }
                is LoginUiState.Error -> {
                    hideLoading()
                    showError(state.message)
                }
            }
        }
    }
}

---

⚠️ 注意事项

1. 业务层统一使用 base-common，不直接使用 base-core
2. ApiServiceFactory 需要在 Application 中初始化 baseUrlProvider
3. ConfigManager、BridgeManager、ExecutorManager 需要 app 模块实现对应的接口（通过 ARouter 注册）
4. ServerConfigManager 是特定业务场景，后续考虑移到 app 模块

---

🔗 相关文档

• base-core README
• 网络请求 MVVM 封装方案
• UI 层封装方案