组件元数据修正

源：Gradle 官方文档 - Component Metadata Rules

组件元数据修正允许在不修改原始库的情况下，修正或增强依赖的元数据信息，解决第三方库元数据错误或不完整的问题。

元数据问题

常见元数据问题

缺失传递依赖：

library.pom 中未声明必需的依赖

错误的依赖范围：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>runtime-lib</artifactId>
    <scope>compile</scope>  <!-- 应该是 runtime -->
</dependency>

过时的依赖版本：

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>18.0</version>  <!-- 太旧 -->
</dependency>

平台信息缺失：

库未声明为平台（BOM）

---

组件元数据规则

基本语法

dependencies {
    components {
        all {
            // 规则应用到所有组件
        }
    }
}

针对特定组件

dependencies {
    components {
        withModule("com.example:library") {
            // 仅应用到 com.example:library
        }
    }
}

---

修正传递依赖

添加缺失的依赖

dependencies {
    components {
        withModule("com.example:broken-lib") {
            allVariants {
                withDependencies {
                    add("com.example:missing-dep:1.0")
                }
            }
        }
    }
}

移除错误的依赖

dependencies {
    components {
        withModule("com.example:library") {
            allVariants {
                withDependencies {
                    removeAll { it.group == "com.example" && it.name == "unwanted-dep" }
                }
            }
        }
    }
}

替换依赖

dependencies {
    components {
        withModule("com.example:library") {
            allVariants {
                withDependencies {
                    // 移除旧依赖
                    removeAll { it.name == "old-dep" }
                    // 添加新依赖
                    add("com.example:new-dep:2.0")
                }
            }
        }
    }
}

---

修正依赖版本

强制特定版本

dependencies {
    components {
        withModule("com.example:library") {
            allVariants {
                withDependencies {
                    // 将所有 Guava 依赖升级到 32.0.0
                    filter { it.group == "com.google.guava" }
                        .forEach {
                            it.version { require("32.0.0") }
                        }
                }
            }
        }
    }
}

使用版本约束

dependencies {
    components {
        all {
            allVariants {
                withDependencyConstraints {
                    filter { it.group == "org.jetbrains.kotlin" }
                        .forEach {
                            it.version { prefer("1.9.22") }
                            it.because("统一 Kotlin 版本")
                        }
                }
            }
        }
    }
}

---

声明为平台

将库声明为 BOM

dependencies {
    components {
        withModule("com.example:bom") {
            allVariants {
                attributes {
                    attribute(
                        Category.CATEGORY_ATTRIBUTE,
                        objects.named(Category::class.java, Category.REGULAR_PLATFORM)
                    )
                }
            }
        }
    }
}

使用：

dependencies {
    implementation(platform("com.example:bom:1.0"))
    implementation("com.example:library")
}

---

修正变体信息

添加缺失的变体属性

dependencies {
    components {
        withModule("com.example:library") {
            allVariants {
                attributes {
                    attribute(
                        TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE,
                        17
                    )
                }
            }
        }
    }
}

修正能力信息

dependencies {
    components {
        withModule("com.example:library") {
            allVariants {
                withCapabilities {
                    addCapability("com.example", "feature-x", "1.0")
                }
            }
        }
    }
}

---

实战案例

案例1：修正 Kotlin stdlib

问题：旧库依赖过时的 Kotlin stdlib

dependencies {
    components {
        all {
            allVariants {
                withDependencies {
                    filter {
                        it.group == "org.jetbrains.kotlin" &&
                        (it.name == "kotlin-stdlib-jdk7" || it.name == "kotlin-stdlib-jdk8")
                    }.forEach {
                        it.version { require("1.9.22") }
                    }
                }
            }
        }
    }
}

案例2：AndroidX 迁移

问题：旧库依赖 Support Library

dependencies {
    components {
        all {
            allVariants {
                withDependencies {
                    // 移除所有 Support Library
                    removeAll { it.group == "com.android.support" }
                    
                    // 添加对应的 AndroidX
                    if (any { it.group == "com.android.support" && it.name == "appcompat-v7" }) {
                        add("androidx.appcompat:appcompat:1.7.0")
                    }
                }
            }
        }
    }
}

案例3：修正传递依赖版本

问题：库引入了有安全漏洞的依赖

dependencies {
    components {
        withModule("com.example:vulnerable-lib") {
            allVariants {
                withDependencies {
                    // 升级有漏洞的 Jackson 版本
                    filter { it.group == "com.fasterxml.jackson.core" }
                        .forEach {
                            it.version { require("2.17.0") }
                            it.because("修复 CVE-2024-XXXX")
                        }
                }
            }
        }
    }
}

---

共享元数据规则

在根项目定义

// build.gradle.kts (project)
subprojects {
    configurations.all {
        resolutionStrategy {
            componentSelection {
                all {
                    // 共享规则
                }
            }
        }
    }
    
    dependencies {
        components {
            all {
                // 应用到所有子项目
            }
        }
    }
}

使用约定插件

// buildSrc/src/main/kotlin/DependencyMetadataPlugin.kt
class DependencyMetadataPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        target.dependencies {
            components {
                all {
                    allVariants {
                        withDependencies {
                            // 统一元数据修正
                        }
                    }
                }
            }
        }
    }
}

应用：

plugins {
    id("dependency-metadata")
}

---

最佳实践

最小化规则：

• 仅修正确实有问题的元数据
• 避免过度修正
• 定期审查是否还需要

文档化原因：

withModule("com.example:library") {
    allVariants {
        withDependencies {
            add("com.example:missing-dep:1.0")
            // 原因：library 1.0 的 POM 缺失此依赖
            // 已报告给维护者：https://github.com/example/library/issues/123
        }
    }
}

验证修正效果：

# 查看依赖树
./gradlew :app:dependencies

# 确认修正生效
./gradlew :app:dependencyInsight --dependency <name>

定期检查上游修复：

• 检查库新版本
• 确认是否已修复元数据问题
• 移除不再需要的规则

---

调试元数据规则

查看生效的规则

./gradlew :app:dependencies --debug

验证依赖变更

# 修正前
./gradlew :app:dependencies > before.txt

# 添加规则后
./gradlew :app:dependencies > after.txt

# 对比
diff before.txt after.txt

---

性能考虑

规则数量：

• 避免过多规则
• 影响依赖解析性能

规则范围：

• 尽量针对特定组件
• 避免 all 匹配所有组件

缓存：

• 元数据规则会影响缓存
• 规则变更会导致重新解析

---

与其他机制对比

机制	用途	灵活性	适用场景
元数据规则	修正元数据	高	第三方库问题
exclude	排除依赖	中	简单排除
force	强制版本	低	版本冲突
constraints	约束版本	高	版本管理

推荐使用场景：

• 第三方库元数据错误
• 无法修改源库
• 需要精细控制依赖