SuperAPI AI 工具集

java

编程与开发

查看项目

更新于 11-07 08:29

技能介绍

概述

该技能定位为“Java 语言技能(language skill)”,是一个知识型技能而非智能体。在编写、编辑或评审 .java 文件时,它会按需加载上下文;角色智能体(/be、/rev、/arch)在处理语言级规则时会路由到该技能。它负责“语言”层面,而框架深度(Spring、持久化、API 设计、消息)留给 /be 的 java-expertise 参考文档。

触发条件

适用场景:

  • 编写、编辑或评审 .java 文件
  • 变更 pom.xml、build.gradle、build.gradle.kts 或 gradle/libs.versions.toml
  • 诊断 javac、Error Prone 或 JVM 测试失败
  • 设计 Java 组件(领域模型、null 契约、并发拓扑)
  • 为 Java 代码规划测试
  • 为 JVM 构建添加依赖

不适用:Kotlin(属于 /be 的 kotlin 参考)、Spring、API、持久化操作指南(属于 /be 的 java-expertise 参考)。

文档查证(强制要求)

任何实现前都应核对当前文档:Java 每六个月发布新版本,预览 API 在各版本间变动,工具链(Error Prone、NullAway、PIT、ArchUnit)独立演进,不能依赖记忆。

  • 使用 Context7 MCP:先以库名调用 mcp__context7__resolve-library-id,再用解析出的库 ID 调用 mcp__context7__query-docs 查询。典型查询包括 JUnit 6 API、ArchUnit 规则语法、Testcontainers 模块、NullAway 与 Error Prone 参数、pitest 配置、jqwik 生成器等。
  • 版本或公告类问题使用 WebSearch 与 WebFetch:功能状态查 JEP 页面的状态行;版本变更查对应 JDK 的发行说明或 JEP 索引;库版本查其仓库或 Maven Central;依赖公告查 OSV 数据库。
  • 预览 API 必须按当前 JEP 编号查证,不能凭记忆。例如结构化并发的 Joiner API 在 JDK 25 预览(JEP 505)与 JDK 26 预览(JEP 525)之间已改名。框架断言需核对项目实际使用的大版本,如 Spring Framework 7 使用 JSpecify 注解并推荐 NullAway,而 Spring 6 使用自有 null 安全注解。

版本基线

资料列出:Java 25(LTS,作为目标基线)、ScopedValue 自 25 起为正式功能(JEP 506)、Stream Gatherers 自 24 起为正式功能(JEP 485)、FFM 自 22 起为正式功能、结构化并发为预览(JEP 505 第五轮预览于 25,JEP 525 第六轮于 26,预计 27 转正)、虚拟线程固定问题修复于 JDK 24(JEP 491)、JSpecify 1.0、Error Prone ≥ 2.36、NullAway 0.12.x、JUnit 6.0.x、PIT 1.19.4+、jqwik 1.10.x、ArchUnit 1.4.x、Testcontainers 当前版本、OSV-Scanner、CycloneDX。资料同时提示这些版本以 2026 年 8 月为基准,固定前需重新核实;并注明 /be 的编号工程标准 1–7 同样逐字适用,此处不重复。

核心规则(J-standards,评审时阻塞)

类型驱动设计

  • J1:值类型一律使用 record,紧凑构造器负责校验并以 List.copyOf 防御性复制;可用 record 却手写 final 字段加 getter 的类视为评审问题。
  • J2:封闭层次用 sealed 接口,消费端使用模式匹配 switch 且不带 default,使新增变体在每个消费点编译失败。仅对不受控的非 sealed 类型才允许 default。
  • J3:不变式放在类型中而非注释中,按状态建模一个 sealed 变体,各携带该状态合法数据。
  • J4:领域标识符使用带校验的值 record,而非裸 String 或 long,避免参数互换仍能编译。
  • J5:公共方法返回 Optional 而非 null;Optional 仅作返回类型,不作字段或参数。

空值安全

  • J6:每个包加 @NullMarked(JSpecify 1.0),非空为默认,@Nullable 为可见且可检查的例外。
  • J7:NullAway 在构建中以 ERROR 运行(Error Prone ≥ 2.36 上加 -Xep:NullAway:ERROR),增量采用可用 OnlyNullMarked 模式。
  • J8:边界读取(Map.get、反序列化 DTO 字段、JDBC/ORM 读取)在证明前视为可空,应在读取处用 getOrDefault、computeIfAbsent 或 orElseThrow 处理缺失。

不可变性

  • J9:默认不可变——final 字段、暴露集合一律 List.copyOf、构造时防御性复制可变输入、领域类型无 setter,演进通过 with 式复制或 builder。
  • J10:禁止静态可变状态,唯一例外是带文档化淘汰策略与线程安全设计的缓存。

并发

  • J11:I/O 密集并发默认用虚拟线程,一个任务一个虚拟线程,写阻塞式线性代码;仅当流式或背压本身是需求时才用响应式;不要池化虚拟线程。
  • J12:固定(pinning)建议需区分运行时版本。JDK 24 起(JEP 491)synchronized 不再固定虚拟线程,剩余来源为原生帧与类初始化器;用 JFR jdk.VirtualThreadPinned 事件诊断。旧版“用 ReentrantLock 替换 synchronized”仅适用于 24 之前的运行时。
  • J13:上下文传递优先用 ScopedValue(JDK 25 起正式),新增 ThreadLocal 需在 PR 中书面说明理由。
  • J14:结构化并发用于扇出,但作为受预览门控的选项:生产默认关闭,除非项目明确选择并记录决定。无预览替代方案为逐个提交子任务并用 ExecutorCompletionService 在显式截止时间内消费完成结果,首个失败时自行取消其余 future(invokeAll 无法做到);所有 fork 必须 join,fire-and-forget 提交属缺陷。
  • J15:每个阻塞式外部调用(HTTP、JDBC、队列、缓存)都需在调用点或客户端构建器显式声明连接与读取超时,不继承库默认值。
  • J16:现代替代对照——JNI→FFM(自 22 正式);collect-then-restream→Gatherers(windowFixed、scan、mapConcurrent,自 24 正式);Date/Calendar→java.time;ThreadLocalRandom 可重现随机→SplittableRandom(seed);finalize()→Cleaner;每次调用 Pattern.compile→缓存 static final Pattern;DI bean 上的静态业务逻辑→实例方法。另给出共享状态或协调真正需要时的原语选择表:并发集合、原子操作、锁、同步器、执行器、CompletableFuture。

构建卫生

  • J17:版本只存在一处——Gradle 只允许出现在 gradle/libs.versions.toml,Maven 用 BOM 导入加 <properties>。
  • J18:质量门在 CI 编译时生效:Error Prone + NullAway 作为错误加 -Xlint:all,抑制只能以命名注解在最小范围使用并附理由。
  • J19:依赖完整性强制执行——Gradle 依赖校验元数据或 Maven lockfile、可重现构建、CI 中运行 OSV-Scanner(优于 owasp-dependency-check 的误报率),CVSS ≥ 7 阻断合并,通过 CycloneDX 发布 SBOM。

测试

  • J20:使用 JUnit 6,Platform、Jupiter、Vintage 统一版本(Java 17 基线)。命名约定为 should_<expected>_when_<condition> 或用 @DisplayName 描述可观察行为;工具形态包括 Mockito 5(只 mock 协作者,不 mock 被测类型)、AssertJ 链式断言、Given-When-Then 结构与每个测试一个断言概念。

适用场景与限制

适用于 Java 代码编写与评审、构建脚本变更、编译与测试问题诊断、组件设计、测试规划与依赖引入。限制与边界:资料明确指出框架层面(Spring、持久化、API 设计、消息)不在本技能范围;Kotlin 不在范围;生产环境默认禁用预览特性;版本基线需重新核实;资料未提供独立的收费、价格、平台或安装方式信息,相关内容暂未提供。