Hey there! Great question—coming from Java, it totally makes sense to wonder why Kotlin opted for internal instead of sticking to the familiar package-level scope we know from Java. Let’s break down the core design decisions behind this choice:

1. Java’s Package Scope Has Encapsulation Leaks #

Java’s package-private access (the default scope when you don’t specify a modifier) sounds like it restricts access to the same package, but it has a big flaw: any class in any module can declare itself in the same package and gain access. This means if you have a utility class in com.example.utils with package-private methods, another module could create a class in the exact same package and call those methods, breaking your intended encapsulation.

Kotlin’s internal fixes this by tying visibility to a module (think a Gradle subproject, Maven module, or IntelliJ module). Any internal member is only visible to code within the same module—even if another module uses the same package name, it can’t access those members. This creates a far more reliable and secure encapsulation boundary.

2. Modules Are a More Natural Encapsulation Unit #

Modern projects are built around modules (e.g., a network module, ui module, core module) rather than just package structures. internal aligns perfectly with this modular approach: you can expose functionality to other parts of your module without leaking it to external modules, regardless of how your packages are organized.

In Java, you often end up forcing classes into the same package just to use package-private access, leading to bloated, poorly organized packages. With internal, you can structure your packages logically (by feature, layer, etc.) and still keep internal details hidden from outside modules.

3. Avoids Package Name Confusion and Forced Structure #

Ever had to name a package something awkward just to avoid conflicts, or to keep related classes together for package access? internal eliminates that hassle. You don’t have to contort your package structure to control visibility—focus on organizing code by its purpose, and let the module boundary handle access control.

This is especially helpful in large teams, where enforcing consistent package structure for access control can be a headache. internal simplifies the rules: if it’s in the same module, it can see internal members; otherwise, it can’t.

4. Compatibility with JVM (But Better Than Java’s Default) #

While the JVM doesn’t natively support module-level access, Kotlin’s compiler enforces internal visibility at compile time. Under the hood, internal members are compiled with JVM’s default (package-private) access, but Kotlin adds checks to ensure only code from the same module can access them. This gives you the best of both worlds: compatibility with JVM ecosystems, plus stronger encapsulation than Java’s package scope.

Quick Example to Illustrate #

Let’s say you have a module core with:

// core module, com.example.core.utils
internal fun internalHelper() { /* ... */ }

In another module app, even if you create a class in the same package:

// app module, com.example.core.utils
fun useHelper() {
    internalHelper() // ❌ Kotlin compiler error: cannot access internal member from different module
}

In Java, this would work just fine—leading to unintended access. Kotlin’s internal prevents this.

I totally get the initial confusion coming from Java, but once you start working with modular projects, internal becomes a much more intuitive and reliable way to control code visibility. It’s one of those Kotlin features that grows on you as you use it!

内容的提问来源于stack exchange，提问作者Antony