36 Best Practices für robuste und effiziente Gradle-Builds

// Root settings.gradle.kts - Strukturierte Modulorganisation
rootProject.name = "enterprise-system"

// Feature modules
include(
    "core:domain",
    "core:common",
    "core:testing"
)

include(
    "services:user-service",
    "services:payment-service",
    "services:notification-service"
)

include(
    "libraries:rest-client",
    "libraries:messaging",
    "libraries:security"
)

include(
    "applications:web-app",
    "applications:mobile-backend",
    "applications:admin-portal"
)

// Convention plugin usage
// buildSrc/src/main/kotlin/java-service.gradle.kts
plugins {
    `java-library`
    id("java-conventions")
    id("testing-conventions")
    id("publishing-conventions")
}

dependencies {
    implementation(project(":core:domain"))
    implementation(project(":core:common"))
    testImplementation(project(":core:testing"))
}

java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(17))
    }
}

// Module boundary enforcement
configurations.all {
    resolutionStrategy {
        dependencySubstitution {
            // Prevent direct cross-service dependencies
            all {
                if (requested is ModuleComponentSelector) {
                    val module = requested as ModuleComponentSelector
                    if (module.group == "com.company" && 
                        module.module.contains("service") && 
                        project.name.contains("service") &&
                        !module.module.contains(project.name)) {
                        throw GradleException(
                            "Direct service-to-service dependency not allowed: " +
                            "${project.name} -> ${module.module}"
                        )
                    }
                }
            }
        }
    }
}

// Performance-optimized module configuration
subprojects {
    // Lazy configuration
    afterEvaluate {
        tasks.withType<JavaCompile>().configureEach {
            options.isFork = true
            options.isIncremental = true
        }
    }
    
    // Parallel execution
    tasks.withType<Test>().configureEach {
        maxParallelForks = (Runtime.getRuntime().availableProcessors() / 2).takeIf { it > 0 } ?: 1
    }
    
    // Build cache
    tasks.withType<Task>().configureEach {
        outputs.cacheIf { true }
    }
}

// Build Cache Configuration
buildCache {
    local {
        enabled = true
        directory = file("${rootDir}/.gradle/build-cache")
        removeUnusedEntriesAfterDays = 7
    }
    
    remote<HttpBuildCache> {
        enabled = true
        url = uri("https://cache.company.com/cache/")
        
        // Credentials from environment
        credentials {
            username = System.getenv("BUILD_CACHE_USER")
            password = System.getenv("BUILD_CACHE_PASS")
        }
        
        // Push only from CI
        isPush = System.getenv("CI") == "true"
    }
}

// Task optimization for caching
tasks.withType<JavaCompile>().configureEach {
    // Stable inputs for better cache keys
    options.isIncremental = true
    options.isFork = true
    options.forkOptions.executable = null  // Use toolchain
    
    // Normalize inputs
    inputs.property("java.version") {
        JavaVersion.current().majorVersion
    }
    
    // Cache even for small tasks
    outputs.cacheIf { true }
}

// Dependency resolution optimization
configurations.all {
    resolutionStrategy {
        // Cache dynamic versions
        cacheDynamicVersionsFor(10, TimeUnit.MINUTES)
        cacheChangingModulesFor(4, TimeUnit.HOURS)
        
        // Prefer cached artifacts
        preferProjectModules()
        
        // Fail fast on conflicts
        failOnVersionConflict()
    }
}

// Parallel execution configuration
gradle.startParameter.maxWorkerCount = 
    System.getenv("GRADLE_WORKERS")?.toInt() 
    ?: Runtime.getRuntime().availableProcessors()

// Configuration avoidance
tasks.register("build") {
    dependsOn(gradle.includedBuilds.map { it.task(":build") })
}

// Lazy configuration with providers
val buildNumber = providers.environmentVariable("BUILD_NUMBER")
    .orElse("LOCAL")

tasks.withType<Jar>().configureEach {
    manifest {
        attributes(
            "Build-Number" to buildNumber.get(),
            "Build-Time" to providers.provider { Instant.now().toString() }
        )
    }
}

// Performance monitoring
gradle.taskGraph.whenReady {
    val slowTaskThreshold = 10000L // 10 seconds
    
    gradle.taskGraph.allTasks.forEach { task ->
        task.doLast {
            if (task.state.executed && task.state.duration > slowTaskThreshold) {
                logger.warn("Slow task detected: ${task.path} took ${task.state.duration}ms")
            }
        }
    }
}

// Robust error handling
abstract class ResilientTask : DefaultTask() {
    @get:InputFile
    abstract val inputFile: RegularFileProperty
    
    @get:OutputDirectory
    abstract val outputDir: DirectoryProperty
    
    @TaskAction
    fun execute() {
        // Input validation
        val input = inputFile.get().asFile
        require(input.exists()) {
            "Input file does not exist: ${input.absolutePath}"
        }
        require(input.canRead()) {
            "Cannot read input file: ${input.absolutePath}"
        }
        
        // Output preparation with error handling
        val output = outputDir.get().asFile
        try {
            output.mkdirs()
        } catch (e: SecurityException) {
            throw GradleException(
                "Cannot create output directory: ${output.absolutePath}. " +
                "Check file permissions.", e
            )
        }
        
        // Processing with retry logic
        retry(3, delay = 1000) {
            processFile(input, output)
        }
    }
    
    private fun <T> retry(
        times: Int, 
        delay: Long = 0, 
        block: () -> T
    ): T {
        var lastException: Exception? = null
        
        repeat(times) { attempt ->
            try {
                return block()
            } catch (e: Exception) {
                lastException = e
                logger.warn("Attempt ${attempt + 1} failed: ${e.message}")
                
                if (attempt < times - 1) {
                    Thread.sleep(delay)
                }
            }
        }
        
        throw GradleException(
            "Operation failed after $times attempts", 
            lastException
        )
    }
}

// Property validation
val requiredProperties = listOf("api.key", "deploy.url", "version")

tasks.register("validateConfiguration") {
    description = "Validate required configuration"
    
    doFirst {
        val missingProperties = requiredProperties.filter {
            !project.hasProperty(it) || project.property(it).toString().isBlank()
        }
        
        if (missingProperties.isNotEmpty()) {
            throw GradleException("""
                Missing required properties:
                ${missingProperties.joinToString("\n") { "  - $it" }}
                
                Please configure these properties in:
                  - gradle.properties (for persistent values)
                  - ~/.gradle/gradle.properties (for user-specific values)
                  - Command line: -P${'$'}{property}=value
                  - Environment: ORG_GRADLE_PROJECT_${'$'}{property}=value
            """.trimIndent())
        }
    }
}

// Network resilience
abstract class NetworkTask : DefaultTask() {
    @TaskAction
    fun execute() {
        val url = "https://api.company.com/data"
        
        val data = withTimeout(30000) {
            withRetry(3) {
                URL(url).openConnection().apply {
                    connectTimeout = 5000
                    readTimeout = 10000
                    
                    // Handle different response codes
                    if (this is HttpURLConnection) {
                        when (responseCode) {
                            200 -> inputStream.readText()
                            404 -> throw FileNotFoundException("Resource not found: $url")
                            500..599 -> throw IOException("Server error: $responseCode")
                            else -> throw IOException("Unexpected response: $responseCode")
                        }
                    } else {
                        inputStream.readText()
                    }
                }
            }
        }
        
        processData(data)
    }
}

// Graceful degradation
tasks.withType<Test>().configureEach {
    ignoreFailures = project.hasProperty("test.ignoreFailures")
    
    addTestListener(object : TestListener {
        override fun afterTest(test: TestDescriptor, result: TestResult) {
            if (result.resultType == TestResult.ResultType.FAILURE) {
                val critical = test.className?.contains("Critical") ?: false
                
                if (critical && !ignoreFailures) {
                    throw GradleException(
                        "Critical test failed: ${test.className}.${test.name}"
                    )
                }
            }
        }
    })
}

// Self-documenting build configuration
tasks.register<GenerateDocsTask>("generateApiDocs") {
    description = "Generates API documentation from source code annotations"
    group = "documentation"
    
    // Clear property documentation
    sourceFiles.from(layout.projectDirectory.dir("src/main/java"))
    outputDirectory.set(layout.buildDirectory.dir("docs/api"))
    format.set(DocumentFormat.HTML)
    includePrivate.set(false)
    
    // Usage instructions in task
    doFirst {
        logger.lifecycle("""
            Generating API documentation:
              Source: ${sourceFiles.files.size} files
              Output: ${outputDirectory.get()}
              Format: ${format.get()}
            
            View documentation: 
              file://${outputDirectory.get()}/index.html
        """.trimIndent())
    }
}

// Documented extension DSL
/**
 * Configuration for deployment tasks.
 * 
 * Example:
 * ```
* deployment {
*     environment = "production"
*     url = "https://api.company.com"
*     timeout = 30
*     retries = 3
* }
* ```
*/
abstract class DeploymentExtension {
/** Target environment (development, staging, production) */
abstract val environment: Property<String>

    /** Deployment endpoint URL */
    abstract val url: Property<String>
    
    /** Connection timeout in seconds (default: 30) */
    abstract val timeout: Property<Int>
    
    /** Number of retry attempts on failure (default: 3) */
    abstract val retries: Property<Int>
    
    init {
        // Documented defaults
        timeout.convention(30)
        retries.convention(3)
    }
}

// Build documentation generation
tasks.register("generateBuildDocs") {
description = "Generate documentation for build configuration"
group = "documentation"

    val docFile = file("${layout.buildDirectory.get()}/docs/BUILD.md")
    outputs.file(docFile)
    
    doLast {
        docFile.parentFile.mkdirs()
        docFile.writeText("""
            # Build Configuration Guide
            
            ## Project Structure
            ${generateProjectStructure()}
            
            ## Available Tasks
            ${generateTaskDocumentation()}
            
            ## Configuration Properties
            ${generatePropertyDocumentation()}
            
            ## Dependencies
            ${generateDependencyDocumentation()}
            
            ## Troubleshooting
            ${generateTroubleshootingGuide()}
            
            Generated: ${Instant.now()}
        """.trimIndent())
    }
}

// Complexity management
object BuildUtils {
/**
* Calculate version based on git tags and branch
*/
fun calculateVersion(project: Project): String {
val gitTag = executeGitCommand("describe --tags --exact-match")
.getOrNull()
?.trim()

        if (gitTag != null) {
            return gitTag.removePrefix("v")
        }
        
        val branch = executeGitCommand("rev-parse --abbrev-ref HEAD")
            .getOrDefault("unknown")
        
        val commitCount = executeGitCommand("rev-list --count HEAD")
            .getOrDefault("0")
        
        val baseVersion = project.findProperty("version.base") as String? ?: "1.0.0"
        
        return when (branch) {
            "main", "master" -> "$baseVersion-$commitCount"
            "develop" -> "$baseVersion-dev.$commitCount"
            else -> "$baseVersion-${branch.replace("/", "-")}.$commitCount"
        }
    }
}

// Usage of extracted complexity
version = BuildUtils.calculateVersion(project)

// Team standards enforcement
tasks.register("enforceStandards") {
    description = "Enforce team coding and build standards"
    group = "verification"
    
    dependsOn("checkstyle", "spotbugs", "pmd")
    
    doLast {
        // Check build script quality
        val buildFiles = fileTree(rootDir) {
            include("**/*.gradle.kts")
            include("**/*.gradle")
            exclude("**/build/**")
        }
        
        val violations = mutableListOf<String>()
        
        buildFiles.forEach { file ->
            val content = file.readText()
            
            // Check for common anti-patterns
            if (content.contains("compile(") && !content.contains("compileOnly(")) {
                violations.add("${file.name}: Uses deprecated 'compile' configuration")
            }
            
            if (content.contains("task<")) {
                violations.add("${file.name}: Uses eager task creation, use register<> instead")
            }
            
            if (content.contains(".execute()")) {
                violations.add("${file.name}: Direct task execution detected")
            }
            
            if (content.contains("rootProject.")) {
                violations.add("${file.name}: Direct rootProject access reduces build isolation")
            }
        }
        
        if (violations.isNotEmpty()) {
            throw GradleException(
                "Build standard violations found:\n" + 
                violations.joinToString("\n") { "  - $it" }
            )
        }
    }
}

// Continuous improvement metrics
tasks.register("collectBuildMetrics") {
    description = "Collect build metrics for analysis"
    group = "metrics"
    
    val metricsFile = file("${rootDir}/build-metrics.csv")
    
    doLast {
        val metrics = BuildMetrics(
            timestamp = Instant.now(),
            duration = gradle.buildFinished.get() - gradle.buildStarted.get(),
            taskCount = gradle.taskGraph.allTasks.size,
            cacheHitRate = calculateCacheHitRate(),
            parallelism = gradle.startParameter.maxWorkerCount,
            outcome = if (gradle.buildResult.failure == null) "SUCCESS" else "FAILURE"
        )
        
        // Append to CSV for trend analysis
        if (!metricsFile.exists()) {
            metricsFile.writeText("timestamp,duration,tasks,cache_hit_rate,parallelism,outcome\n")
        }
        
        metricsFile.appendText(
            "${metrics.timestamp},${metrics.duration},${metrics.taskCount}," +
            "${metrics.cacheHitRate},${metrics.parallelism},${metrics.outcome}\n"
        )
        
        // Alert on degradation
        val previousMetrics = parsePreviousMetrics(metricsFile)
        val avgDuration = previousMetrics.takeLast(10).map { it.duration }.average()
        
        if (metrics.duration > avgDuration * 1.5) {
            logger.warn("Build duration ${metrics.duration}ms significantly above average ${avgDuration}ms")
        }
    }
}

// Knowledge sharing
tasks.register("generateBuildPlaybook") {
    description = "Generate playbook for common build scenarios"
    group = "documentation"
    
    val playbook = file("${rootDir}/BUILD_PLAYBOOK.md")
    
    doLast {
        playbook.writeText("""
            # Build Playbook
            
            ## Quick Start
            ```bash
            ./gradlew build          # Full build with tests
            ./gradlew build -x test  # Build without tests  
            ./gradlew tasks --all    # List all available tasks
            ```
            
            ## Common Scenarios
            
            ### Fast Development Build
            ```bash
            ./gradlew assemble --parallel --build-cache
            ```
            
            ### Debug Slow Build
            ```bash
            ./gradlew build --scan --profile
            ```
            
            ### Clean Build
            ```bash
            ./gradlew clean build --no-build-cache
            ```
            
            ### Update Dependencies
            ```bash
            ./gradlew dependencyUpdates
            ./gradlew refreshDependencies
            ```
            
            ## Troubleshooting
            
            ### Out of Memory
            Increase heap: `export GRADLE_OPTS="-Xmx4g"`
            
            ### Cache Problems
            Clear cache: `./gradlew cleanBuildCache`
            
            ### Dependency Conflicts
            Analyze: `./gradlew dependencies`
            
            ## Performance Tips
            ${generatePerformanceTips()}
            
            ## Team Contacts
            - Build Support: build-team@company.com
            - Slack: #gradle-help
            
            Last Updated: ${Instant.now()}
        """.trimIndent())
    }
}

// Deprecation management
@Deprecated(
    message = "Use newBuildTask instead",
    replaceWith = ReplaceWith("newBuildTask"),
    level = DeprecationLevel.WARNING
)
tasks.register("oldBuildTask") {
    doFirst {
        logger.warn("Task 'oldBuildTask' is deprecated and will be removed in version 3.0")
        logger.warn("Please use 'newBuildTask' instead")
    }
    
    finalizedBy("newBuildTask")
}

// Feature flags for gradual migration
val useNewBuildSystem = project.findProperty("feature.newBuildSystem") == "true"

if (useNewBuildSystem) {
    apply(plugin = "new-build-plugin")
} else {
    apply(plugin = "legacy-build-plugin")
    logger.lifecycle("Using legacy build system. Enable new system with -Pfeature.newBuildSystem=true")
}