能力模块开发规范

📋 核心原则

每个能力模块必须完全独立，自己管理自己的所有配置和依赖，app 模块只负责组装，不负责管理能力模块的内部事务。

🎯 原始诉求

问题背景

❌ 之前的问题：所有配置都在 app 模块的 strings.xml 中
❌ 之前的问题：所有依赖都在 app 模块的 build.gradle 中重复声明
❌ 之前的问题：app 模块需要解析 XML 来读取配置
❌ 之前的问题：能力模块的配置散落在各处，难以维护

解决方案

✅ 现在：每个能力模块有自己的 strings.xml
✅ 现在：每个能力模块管理自己的依赖（使用 api 传递）
✅ 现在：不需要 XML 解析，直接使用 @string/ 引用
✅ 现在：能力模块完全独立，app 模块只负责组装

📁 模块结构规范

标准目录结构

capability-xxx/
├── build.gradle                    # 模块依赖配置
├── src/main/
│   ├── AndroidManifest.xml        # 模块的 AndroidManifest（包含 meta-data、Activity 等）
│   ├── res/
│   │   └── values/
│   │       └── strings.xml         # 模块自己的配置（必须！）
│   └── java/...                    # 模块代码
└── libs/                           # 模块自己的 SDK 文件（如果有）

🔧 配置管理规范

1. strings.xml 配置

每个能力模块必须有自己的 strings.xml

✅ 正确做法

<!-- capability-push/src/main/res/values/strings.xml -->
<resources>
    <!-- 极光推送配置 -->
    <string name="jpush_app_key">your_jpush_appkey_here</string>
    <string name="push_jpush_channel">developer-default</string>
</resources>

<!-- capability-share/src/main/res/values/strings.xml -->
<resources>
    <!-- 友盟分享配置 -->
    <string name="share_umeng_app_key">your_umeng_appkey_here</string>
    <string name="share_wechat_app_id">your_wechat_appid_here</string>
    <string name="qq_app_id_scheme">tencentyour_qq_appid_here</string>
</resources>

❌ 错误做法

<!-- app/src/main/res/values/strings.xml -->
<resources>
    <!-- ❌ 不要在这里放能力模块的配置！ -->
    <string name="jpush_app_key">...</string>
    <string name="share_umeng_app_key">...</string>
</resources>

2. AndroidManifest.xml 配置

每个能力模块在自己的 AndroidManifest.xml 中配置，使用自己的 @string/ 资源

✅ 正确做法

<!-- capability-push/src/main/AndroidManifest.xml -->
<application>
    <!-- 使用本模块的 @string/ 资源 -->
    <meta-data
        android:name="JPUSH_APPKEY"
        android:value="@string/jpush_app_key"
        tools:replace="android:value" />
    
    <!-- 厂商通道配置（覆盖厂商 SDK 的占位符） -->
    <meta-data
        android:name="XIAOMI_APPID"
        android:value="@string/mi_app_id"
        tools:replace="android:value" />
</application>

<!-- capability-share/src/main/AndroidManifest.xml -->
<activity>
    <!-- 使用本模块的 @string/ 资源 -->
    <data android:scheme="@string/qq_app_id_scheme" />
</activity>

❌ 错误做法

<!-- app/src/main/AndroidManifest.xml -->
<application>
    <!-- ❌ 不要在这里配置能力模块的 meta-data！ -->
    <meta-data android:name="JPUSH_APPKEY" ... />
</application>

// app/build.gradle
// ❌ 不要在这里配置能力模块的参数！
manifestPlaceholders = [
    XIAOMI_APPID: "..."
]

📦 依赖管理规范

1. 依赖声明

每个能力模块在自己的 build.gradle 中声明依赖

✅ 正确做法

// capability-share/build.gradle
dependencies {
    // 使用 api 让依赖传递到 app 模块
    api("com.tencent.mm.opensdk:wechat-sdk-android:6.8.24")
    api(files('libs/umeng-share-wechat-full-7.3.7.jar'))
}

// app/build.gradle
dependencies {
    // 只需要依赖能力模块，不需要重复声明能力模块的依赖
    implementation project(':capability-share')
    // ❌ 不要在这里重复声明微信 SDK！
}

❌ 错误做法

// app/build.gradle
dependencies {
    implementation project(':capability-share')
    // ❌ 不要重复声明能力模块的依赖！
    implementation("com.tencent.mm.opensdk:wechat-sdk-android:6.8.24")
}

2. 依赖传递规则

依赖类型	是否传递到 app 模块	使用场景
`api`	✅ 是	需要暴露给 app 模块使用的依赖（如 SDK）
`implementation`	❌ 否	模块内部使用的依赖

规则：如果 app 模块需要使用某个依赖，能力模块必须使用 api 声明

🚫 禁止事项

❌ 禁止在 app 模块中做的事情

禁止在 app 模块的 strings.xml 中配置能力模块的参数

<!-- ❌ 禁止 -->
<string name="jpush_app_key">...</string>
<string name="share_umeng_app_key">...</string>

禁止在 app 模块的 AndroidManifest.xml 中配置能力模块的 meta-data
```

<meta-data android:name="JPUSH_APPKEY" ... />
```

禁止在 app 模块的 build.gradle 中重复声明能力模块的依赖

// ❌ 禁止
implementation("com.tencent.mm.opensdk:wechat-sdk-android:6.8.24")

禁止在 app 模块的 build.gradle 中使用 XML 解析读取配置

// ❌ 禁止
def xml = new XmlParser().parse(resFile)
manifestPlaceholders = [...]

禁止在 app 模块中管理能力模块的内部逻辑

✅ 正确做法检查清单

创建新能力模块时，请按以下清单检查：

配置管理

在 capability-xxx/src/main/res/values/strings.xml 中创建配置
在 capability-xxx/src/main/AndroidManifest.xml 中使用 @string/ 引用配置
不在 app 模块的 strings.xml 中添加能力模块的配置
不在 app 模块的 AndroidManifest.xml 中配置能力模块的 meta-data

依赖管理

在 capability-xxx/build.gradle 中声明所有依赖
需要暴露给 app 的依赖使用 api
模块内部依赖使用 implementation
不在 app 模块的 build.gradle 中重复声明能力模块的依赖

代码管理

能力模块的代码完全封装在模块内部
通过 Factory 模式暴露接口给 app 模块
app 模块只调用能力模块的公开接口

📝 示例：创建新能力模块

步骤 1：创建模块结构

capability-new/
├── build.gradle
├── src/main/
│   ├── AndroidManifest.xml
│   ├── res/values/strings.xml
│   └── java/...
└── libs/（如果需要）

步骤 2：创建 strings.xml

<!-- capability-new/src/main/res/values/strings.xml -->
<resources>
    <string name="new_module_config_key">your_config_value_here</string>
</resources>

步骤 3：在 AndroidManifest.xml 中使用

<!-- capability-new/src/main/AndroidManifest.xml -->
<application>
    <meta-data
        android:name="NEW_MODULE_KEY"
        android:value="@string/new_module_config_key" />
</application>

步骤 4：在 build.gradle 中声明依赖

// capability-new/build.gradle
dependencies {
    // 需要暴露给 app 的依赖使用 api
    api("com.example:sdk:1.0.0")
    
    // 模块内部依赖使用 implementation
    implementation("com.example:internal-lib:1.0.0")
}

步骤 5：在 app 模块中引用

// app/build.gradle
dependencies {
    // 只需要依赖能力模块，不需要重复声明能力模块的依赖
    implementation project(':capability-new')
}

🔍 常见问题

Q1: 为什么能力模块的依赖要用 `api` 而不是 `implementation`？

A: 因为 app 模块在运行时需要这些依赖（如微信 SDK），如果使用 implementation，依赖不会传递到 app 模块，会导致运行时找不到类。

Q2: 能力模块的 `strings.xml` 中的资源，app 模块能访问吗？

A: 可以。Android 构建系统会合并所有模块的资源，app 模块可以通过 context.resources.getIdentifier() 访问能力模块的资源。

Q3: 如果能力模块需要读取配置，应该怎么做？

A: 在能力模块的代码中使用 Android 标准的资源 API：

// 在能力模块的代码中
val resources = context.resources
val resId = resources.getIdentifier("config_key", "string", context.packageName)
val value = resources.getString(resId)

不要使用 XML 解析！

Q4: app 模块的 `strings.xml` 应该放什么？

A: 只放 app 模块自己的配置，如：

app_name
app 模块特有的配置

不要放能力模块的配置！

📚 参考

当前项目中的正确示例

capability-push 模块
- ✅ 配置：capability-push/src/main/res/values/strings.xml
- ✅ AndroidManifest：capability-push/src/main/AndroidManifest.xml
- ✅ 依赖：capability-push/build.gradle
capability-share 模块
- ✅ 配置：capability-share/src/main/res/values/strings.xml
- ✅ AndroidManifest：capability-share/src/main/AndroidManifest.xml
- ✅ 依赖：capability-share/build.gradle（使用 api 传递依赖）

🎯 总结

记住一句话：每个能力模块都是独立的，自己管理自己的所有事情，app 模块只负责组装，不负责管理！

✅ 配置 → 能力模块的 strings.xml
✅ AndroidManifest → 能力模块的 AndroidManifest.xml
✅ 依赖 → 能力模块的 build.gradle（使用 api 传递）
✅ 代码 → 能力模块的 java/ 目录

app 模块只做一件事：implementation project(':capability-xxx')

💻 代码开发规范

1. 接口设计规范

✅ 必须定义接口（API）

每个能力模块必须定义清晰的接口，实现类封装在内部：

// capability-xxx/src/main/java/.../api/XxxService.kt
interface XxxService {
    fun initialize(context: Context, config: XxxConfig)
    fun doSomething(): XxxResponse
    // ...
}

✅ 实现类使用 internal 或 private

// capability-xxx/src/main/java/.../impl/XxxServiceImpl.kt
internal class XxxServiceImpl : XxxService {
    // 实现细节
}

❌ 禁止直接暴露实现类

// ❌ 禁止
class XxxServiceImpl : XxxService { ... }  // 不要用 public

2. Factory 模式规范

每个能力模块必须使用 Factory 模式提供单例服务

✅ 标准 Factory 结构

// capability-xxx/src/main/java/.../factory/XxxServiceFactory.kt
object XxxServiceFactory {
    @Volatile
    private var instance: XxxService? = null
    
    /**
     * 初始化服务（全局单例）
     * @param context 应用上下文
     * @param config 配置（可选，默认从资源文件读取）
     */
    @JvmStatic
    fun init(context: Context, config: XxxConfig? = null) {
        if (instance == null) {
            synchronized(this) {
                if (instance == null) {
                    val finalConfig = config ?: XxxConfig.fromResources(context)
                    instance = XxxServiceImpl().apply {
                        initialize(context, finalConfig)
                    }
                }
            }
        }
    }
    
    /**
     * 获取服务实例（必须在 init 之后调用）
     */
    @JvmStatic
    fun getInstance(): XxxService {
        return instance ?: throw IllegalStateException(
            "XxxService 未初始化，请先调用 XxxServiceFactory.init()"
        )
    }
}

✅ 使用示例

// 在 Application 中初始化
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        XxxServiceFactory.init(applicationContext)
    }
}

// 在业务代码中使用
val service = XxxServiceFactory.getInstance()
service.doSomething()

3. 配置类设计规范

✅ 配置类必须支持从资源文件读取

// capability-xxx/src/main/java/.../model/XxxConfig.kt
data class XxxConfig(
    val appKey: String,
    val channel: String = "developer-default"
) {
    companion object {
        /**
         * 从资源文件读取配置
         * 资源文件：capability-xxx/src/main/res/values/strings.xml
         */
        @JvmStatic
        fun fromResources(context: Context): XxxConfig {
            val resources = context.resources
            val packageName = context.packageName
            
            fun getString(name: String): String? {
                val resId = resources.getIdentifier(name, "string", packageName)
                return if (resId != 0) resources.getString(resId) else null
            }
            
            val appKey = getString("xxx_app_key") 
                ?: throw IllegalStateException("未配置 xxx_app_key")
            val channel = getString("xxx_channel") ?: "developer-default"
            
            return XxxConfig(appKey = appKey, channel = channel)
        }
    }
}

❌ 禁止使用 XML 解析

// ❌ 禁止在代码中解析 XML
val xml = XmlParser().parse(file)

4. 响应模型规范

✅ 统一的响应模型

// capability-xxx/src/main/java/.../model/XxxResponse.kt
data class XxxResponse(
    val success: Boolean,
    val data: Any? = null,
    val errorMessage: String? = null,
    val timestamp: Long = System.currentTimeMillis()
)

5. 错误处理规范

✅ 必须处理异常，返回统一的响应

override fun doSomething(): XxxResponse {
    return try {
        // 业务逻辑
        XxxResponse(success = true, data = result)
    } catch (e: Exception) {
        ILog.e(tag, "操作失败", e)
        XxxResponse(
            success = false,
            errorMessage = e.message ?: "未知错误"
        )
    }
}

❌ 禁止抛出未处理的异常

// ❌ 禁止
override fun doSomething() {
    throw Exception("错误")  // 必须捕获并返回 Response
}

📝 日志规范

1. 使用统一的日志接口

所有能力模块必须使用 base-core 模块的 ILog 接口

✅ 正确做法

import com.narutohuo.xindazhou.core.log.ILog

class XxxServiceImpl {
    private val tag = "XxxService"
    
    fun doSomething() {
        ILog.d(tag, "开始执行操作")
        try {
            // ...
            ILog.d(tag, "操作成功")
        } catch (e: Exception) {
            ILog.e(tag, "操作失败", e)
        }
    }
}

❌ 禁止直接使用 Android Log

// ❌ 禁止
import android.util.Log
Log.d("Tag", "message")

2. 日志级别规范

级别	使用场景	示例
`ILog.d()`	调试信息、流程跟踪	"开始初始化"、"收到回调"
`ILog.i()`	重要信息	"服务初始化成功"
`ILog.w()`	警告信息	"配置缺失，使用默认值"
`ILog.e()`	错误信息（必须带异常）	"初始化失败", exception

3. Tag 命名规范

// ✅ 使用类名或模块名
private val tag = "XxxService"
private val tag = "XxxServiceImpl"
private val tag = "XxxReceiver"

🔨 编译配置规范

1. build.gradle 配置

✅ 标准配置结构

plugins {
    alias(libs.plugins.kotlin.android)
    id("com.android.library")  // 能力模块必须是 library
}

android {
    namespace = "com.narutohuo.xindazhou.xxx"  // 模块自己的 namespace
    compileSdk = 36

    defaultConfig {
        minSdk = 26
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
    
    kotlinOptions {
        jvmTarget = "17"
    }
}

repositories {
    flatDir {
        dirs 'libs'  // 本地 SDK 文件
    }
    mavenCentral()
    google()
}

dependencies {
    // 1. 依赖 base-core（所有能力模块都依赖）
    implementation(project(":base-core"))
    
    // 2. AndroidX 基础依赖
    implementation(libs.androidx.core.ktx)
    
    // 3. 模块特定的依赖
    // 需要暴露给 app 的依赖使用 api
    api("com.example:sdk:1.0.0")
    // 模块内部依赖使用 implementation
    implementation("com.example:internal-lib:1.0.0")
    
    // 4. 本地 SDK 文件
    implementation(files('libs/xxx-sdk.jar'))
    implementation(name: 'xxx-sdk', ext: 'aar')
}

❌ 禁止事项

// ❌ 禁止使用 application 插件
plugins {
    id("com.android.application")  // 能力模块必须是 library
}

// ❌ 禁止在能力模块中配置 applicationId
defaultConfig {
    applicationId "..."  // 只有 app 模块才有
}

2. AndroidManifest.xml 配置

✅ 标准结构

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
    
    <!-- 模块需要的权限 -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <application>
        <!-- 模块的 Service、Receiver、Activity 等 -->
        <!-- 使用本模块的 @string/ 资源 -->
        <meta-data
            android:name="XXX_KEY"
            android:value="@string/xxx_config_key" />
    </application>
</manifest>

3. ProGuard 规则

如果模块使用了第三方 SDK，必须在模块的 proguard-rules.pro 中添加规则

# capability-xxx/proguard-rules.pro
-keep class com.example.sdk.** { *; }
-dontwarn com.example.sdk.**

🧪 测试规范

1. 单元测试

每个能力模块应该有自己的单元测试

capability-xxx/
└── src/test/
    └── java/.../XxxServiceTest.kt

2. 集成测试

在 app 模块中进行集成测试

app/
└── src/androidTest/
    └── java/.../XxxServiceIntegrationTest.kt

📦 版本管理规范

1. SDK 版本管理

所有 SDK 版本统一在 gradle/libs.versions.toml 中管理

[versions]
androidx-core = "1.12.0"
retrofit = "2.9.0"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "androidx-core" }

2. 模块版本号

能力模块不需要版本号（因为是内部模块）

// ❌ 不需要
version = "1.0.0"

🔍 代码审查检查清单

创建新能力模块时检查

[ ] 模块结构
- 有 strings.xml 配置文件
- 有 AndroidManifest.xml
- 有 build.gradle（使用 library 插件）
[ ] 接口设计
- 定义了清晰的 API 接口
- 实现类使用 internal 或 private
- 使用 Factory 模式提供单例
[ ] 配置管理
- 配置在模块自己的 strings.xml 中
- AndroidManifest 使用 @string/ 引用
- 配置类支持从资源文件读取
[ ] 依赖管理
- 依赖在模块自己的 build.gradle 中
- 需要暴露的依赖使用 api
- app 模块不重复声明依赖
[ ] 日志规范
- 使用 ILog 接口
- 不使用 android.util.Log
- Tag 命名规范
[ ] 错误处理
- 所有异常都被捕获
- 返回统一的 Response 模型
- 不抛出未处理的异常

🚨 常见错误和解决方案

错误 1：运行时找不到类

原因：依赖使用了 implementation 而不是 api

解决：

// 改为 api
api("com.example:sdk:1.0.0")

错误 2：找不到资源

原因：在 app 模块的 strings.xml 中配置了能力模块的资源

解决：移到能力模块自己的 strings.xml 中

错误 3：编译错误：unable to resolve class

原因：依赖没有正确传递

解决：

检查能力模块的依赖是否使用 api
检查 app 模块是否正确依赖了能力模块

错误 4：配置读取失败

原因：使用了 XML 解析而不是 Android 资源 API

解决：

// ✅ 正确
val resId = resources.getIdentifier("key", "string", packageName)
val value = resources.getString(resId)

// ❌ 错误
val xml = XmlParser().parse(file)

📚 参考示例

当前项目中的标准实现

capability-push 模块
- ✅ Factory: PushServiceFactory
- ✅ API: PushService
- ✅ Config: PushConfig.fromResources()
- ✅ 配置: capability-push/src/main/res/values/strings.xml
capability-share 模块
- ✅ Factory: ShareServiceFactory
- ✅ API: ShareService
- ✅ Config: ShareConfig.fromResources()
- ✅ 配置: capability-share/src/main/res/values/strings.xml

🎯 总结

核心原则（再次强调）

独立性：每个能力模块完全独立，不依赖 app 模块
封装性：实现细节封装在模块内部，只暴露接口
统一性：使用统一的 Factory 模式、日志接口、响应模型
规范性：遵循统一的代码规范和目录结构

开发流程

创建模块目录结构
定义 API 接口
实现服务类（internal）
创建 Factory（单例）
创建配置类（支持从资源读取）
创建 strings.xml 配置文件
配置 AndroidManifest.xml
配置 build.gradle（依赖使用 api）
在 app 模块中依赖：implementation project(':capability-xxx')
在 Application 中初始化：XxxServiceFactory.init(context)

最后更新：2024年

能力模块开发规范.md 21 KB Lịch sử Raw

能力模块开发规范

📋 核心原则

🎯 原始诉求

问题背景

解决方案

📁 模块结构规范

标准目录结构

🔧 配置管理规范

1. strings.xml 配置

✅ 正确做法

❌ 错误做法

2. AndroidManifest.xml 配置

✅ 正确做法

❌ 错误做法

📦 依赖管理规范

1. 依赖声明

✅ 正确做法

❌ 错误做法

2. 依赖传递规则

🚫 禁止事项

❌ 禁止在 app 模块中做的事情

✅ 正确做法检查清单

配置管理

依赖管理

代码管理

📝 示例：创建新能力模块

步骤 1：创建模块结构

步骤 2：创建 strings.xml

步骤 3：在 AndroidManifest.xml 中使用

步骤 4：在 build.gradle 中声明依赖

步骤 5：在 app 模块中引用

🔍 常见问题

Q1: 为什么能力模块的依赖要用 api 而不是 implementation？

Q2: 能力模块的 strings.xml 中的资源，app 模块能访问吗？

Q3: 如果能力模块需要读取配置，应该怎么做？

Q4: app 模块的 strings.xml 应该放什么？

📚 参考

当前项目中的正确示例

🎯 总结

💻 代码开发规范

1. 接口设计规范

✅ 必须定义接口（API）

✅ 实现类使用 internal 或 private

❌ 禁止直接暴露实现类

2. Factory 模式规范

✅ 标准 Factory 结构

✅ 使用示例

3. 配置类设计规范

✅ 配置类必须支持从资源文件读取

❌ 禁止使用 XML 解析

4. 响应模型规范

✅ 统一的响应模型

5. 错误处理规范

✅ 必须处理异常，返回统一的响应

❌ 禁止抛出未处理的异常

📝 日志规范

1. 使用统一的日志接口

✅ 正确做法

❌ 禁止直接使用 Android Log

2. 日志级别规范

3. Tag 命名规范

🔨 编译配置规范

1. build.gradle 配置

✅ 标准配置结构

❌ 禁止事项

2. AndroidManifest.xml 配置

✅ 标准结构

3. ProGuard 规则

🧪 测试规范

1. 单元测试

2. 集成测试

📦 版本管理规范

1. SDK 版本管理

2. 模块版本号

🔍 代码审查检查清单

创建新能力模块时检查

🚨 常见错误和解决方案

错误 1：运行时找不到类

错误 2：找不到资源

能力模块开发规范.md 21 KB

Lịch sử Raw

Q1: 为什么能力模块的依赖要用 `api` 而不是 `implementation`？

Q2: 能力模块的 `strings.xml` 中的资源，app 模块能访问吗？

Q4: app 模块的 `strings.xml` 应该放什么？