概述
该技能定位为“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不再固定虚拟线程,剩余来源为原生帧与类初始化器;用 JFRjdk.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 不在范围;生产环境默认禁用预览特性;版本基线需重新核实;资料未提供独立的收费、价格、平台或安装方式信息,相关内容暂未提供。