47 lines
1.8 KiB
Plaintext
47 lines
1.8 KiB
Plaintext
== Why is this an issue?
|
|
|
|
The public API of a framework, plugin, or library is the way its provider intended it to be used.
|
|
API stability and compatibility (within the same major version number) of a library are guaranteed only for its public API.
|
|
|
|
Internal APIs are mere implementation details and are prone to breaking changes as the implementation of the library changes.
|
|
No guarantees are being made about them. Therefore, users should not use internal APIs, even when visible.
|
|
|
|
=== What is the potential impact?
|
|
|
|
==== Code Stability
|
|
|
|
If not fixed, your code might break when the library is upgraded to a new version, even if only the minor version number or the patch number changes.
|
|
|
|
== How to fix it
|
|
|
|
Replace internal API usage with the public API designed for your use case.
|
|
This may imply a refactoring of the affected code if no one-to-one replacement is available in the public API.
|
|
If a specific functionality is required, copying the required parts of the implementation into your code may even be better than using the internal API.
|
|
|
|
=== Code examples
|
|
|
|
==== Noncompliant code example
|
|
|
|
[source,kotlin,diff-id=1,diff-type=noncompliant]
|
|
----
|
|
if (org.gradle.internal.os.OperatingSystem.current().isWindows) { // Noncompliant, OperatingSystem is part of Gradle internal API
|
|
// ...
|
|
}
|
|
----
|
|
|
|
==== Compliant solution
|
|
|
|
[source,kotlin,diff-id=1,diff-type=compliant]
|
|
----
|
|
if (System.getProperty("os.name").toLowerCase().contains("windows")) { // Compliant
|
|
// ...
|
|
}
|
|
----
|
|
|
|
== Resources
|
|
|
|
=== Documentation
|
|
|
|
* https://docs.gradle.org/current/userguide/authoring_maintainable_build_scripts.html#sec:avoiding_gradle_internal_apis[Gradle Documentation - Avoid using internal Gradle APIs]
|
|
* https://github.com/liutikas/gradle-best-practices#dont-use-internal-apis[Best Practices when using Gradle - Don't use internal APIs (Liutikas)]
|