mcpField
J
jspecify-skill

jspecify-skill

github.com/sivaprasadreddy开发194121 次安装2 周前更新
代码仓库

关于 jspecify-skill

帮助 Java 项目添加 JSpecify 空值注解并逐步采用的技能，面向 Maven 和 Gradle 用户，涵盖包标记、旧注解迁移及可选的 Kotlin 互操作。

主要功能

  1. 01Maven 与 Gradle 配置指导
  2. 02通过 @NullMarked 标记包
  3. 03使用 @NullUnmarked 渐进采用
  4. 04迁移其他空值注解
  5. 05可选的 Kotlin 互操作指导

适用场景

  1. 01在 Java 项目中启用空值检查
  2. 02逐包推广空值标记
  3. 03将现有注解迁移到 JSpecify
  4. 04改善 Kotlin 使用 Java API 时的空值识别

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sivaprasadreddy/sivalabs-agent-skills --skill jspecify-skill

安装后在 Claude Code 中输入/jspecify-skill确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
annotation-migration.md
incremental-adoption.md
kotlin-interop.md
scripts/
verify_nullmarked.py

详细介绍

Jspecify 提供了一组注解，用于明确声明 Java 代码对 null 值的预期。

在 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），请先将这些注解迁移到 JSpecify，再添加 @NullMarked。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。

评论

支持 Markdown