jspecify-skill

Jspecify は、Java コードの nullness に関する期待値を明示的に宣言するためのアノテーションを提供します。

Maven プロジェクトで jSpecify のサポートを追加する

Maven を使用している場合は、pom.xml に jspecify の依存関係を追加します。 pom.xml の nullability-maven-plugin を更新するか追加して、次の設定を含めます。

<dependencies>
    <dependency>
        <groupId>org.jspecify</groupId>
        <artifactId>jspecify</artifactId>
        <version>1.0.0</version>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>am.ik.maven</groupId>
            <artifactId>nullability-maven-plugin</artifactId>
            <version>0.4.2</version>
            <extensions>true</extensions>
            <configuration>
                <checking>tests</checking>
                <outputDirectory>${project.basedir}/src/main/java</outputDirectory>
                <testOutputDirectory>${project.basedir}/src/test/java</testOutputDirectory>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <goal>configure</goal>
                        <goal>generate-package-info</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Gradle プロジェクトで jSpecify のサポートを追加する

Gradle を使用している場合は、jspecify の依存関係を追加します。 build.gradle または build.gradle.kts を更新するか、次の jspecify 設定を追加します。

plugins {
    id("net.ltgt.errorprone") version "5.1.0"
    id("net.ltgt.nullaway") version "3.1.0"
}

tasks.withType(JavaCompile).configureEach {
    options.errorprone {
        disableAllChecks = true // Other error prone checks are disabled
        error("RequireExplicitNullMarking") // Require @NullMarked or @NullUnmarked on everything
        nullaway {
            error()
        }
    }
    // Keep a JDK 25 baseline
    options.release = 25
}

nullaway {
    onlyNullMarked = true
    jspecifyMode = true
}

dependencies {
    implementation("org.jspecify:jspecify:1.0.0")
    errorprone("com.google.errorprone:error_prone_core:2.50.0")
    errorprone("com.uber.nullaway:nullaway:0.13.7")
}

package-info.java ファイルに @NullMarked を追加する

アプリケーションのメインソースコード（src/main/java）にあるすべての Java パッケージで、 package-info.java がまだ存在しない場合は作成し、次のように @NullMarked アノテーションを追加します。

@org.jspecify.annotations.NullMarked
package com.mycompnay.myproject;

package-info.java ファイルがすでに存在する場合は、ファイルを更新して @org.jspecify.annotations.NullMarked アノテーションを追加します。 package-info.java ファイル内の既存のコードはほかに削除しないでください。

jSpecify のサポートを検証する

Python がインストールされている場合は、jSpecify のサポートを追加した後、scripts/verify_nullmarked.py を実行して、 空でないすべてのパッケージに package-info.java ファイルがあるかどうかを確認します。

他のアノテーションライブラリから既存のコードベースを移行する

プロジェクトですでに別の nullability アノテーションライブラリ（JSR-305 / javax、Jakarta、 JetBrains、Spring、Android、FindBugs/SpotBugs、Checker Framework、Eclipse JDT）を使用している場合は、 @NullMarked を追加する前に、それらのアノテーションを JSpecify に移行してください。OpenRewrite の MigrateToJSpecify レシピは、 一般的なケース（javax、Jakarta、JetBrains、Micrometer、Micronaut）を自動化します。それ以外は簡単な手動マッピングで対応できます。 references/annotation-migration.md を参照してください。

大規模なコードベースでの段階的な導入

大規模またはレガシーなコードベースでは、すべてのパッケージを一度に @NullMarked に切り替えるのは現実的ではありません。 @NullUnmarked を使用すると、残りの部分には手を加えずに、対象範囲を広げながら NullAway を適用できます。 上記のビルドでは OnlyNullMarked モードが有効になっているため、@NullMarked のないパッケージは単純に 無視されます。つまり、パッケージごとにマーカーを追加するだけで導入を進められます。導入戦略、 進捗の追跡、NullAway の一般的なエラー、冗長な null ガードの削除については、 references/incremental-adoption.md を参照してください。

Kotlin との相互運用（任意）

プロジェクトに Kotlin ソースも含まれている場合、Kotlin コンパイラー（K2）は Java API の JSpecify アノテーションを読み取り、 プラットフォーム型ではなく、正確な nullability を提示します。references/kotlin-interop.md を参照してください。