fmode-app/.claude/skills/dev-expert/references/java-development.md

# Java 专项开发

本文件是 dev-expert 的 Java/Spring 专项补充参考，不作为独立子技能计数，也不提供 @ 显式调用入口。命中 Java、Spring Boot、Spring、MyBatis、Hibernate、JPA、Maven、Gradle、JUnit、Mockito、JVM、GC、线程池、并发、Java 源码分析等信号时，按需与 code-generation、code-review、test-generation、performance-benchmark、software-project 协同加载。

适用边界

• 适用：Java 项目源码走读、Spring Boot 应用开发、接口设计、数据访问、单元测试、并发分析、JVM/GC 基础诊断。
• 不适用：未确认语言/框架时强行套用 Spring 结构；Android、纯前端、PHP/CMS 项目不使用本参考。
• Java 版本：以项目 pom.xml、build.gradle、CI 和线上 JDK 为准。Java 17/21 特性只能在确认运行版本支持后使用。

源码分析流程

1. 先读结构：查看目录、包名、模块、构建文件，识别 Controller/Service/Repository/Domain 等分层。
2. 找入口：定位 main 类、Controller、Message Listener、Scheduled Task、CommandLineRunner 或核心业务入口。
3. 逐层深入：沿调用链追踪 Controller -> Service -> Repository/Mapper -> 外部依赖，标注关键分支和异常路径。
4. 识别依赖：梳理类间依赖、接口实现、循环依赖、配置注入和第三方组件。
5. 总结输出：给出项目概览、核心流程、关键类职责、风险点和验证建议。

源码分析输出模板

## 项目概览
- 技术栈：
- 分层架构：
- 构建工具：

## 核心流程
1. 入口：
2. 业务逻辑：
3. 数据访问：
4. 外部依赖：

## 关键类说明
| 类名 | 职责 | 关键方法 |
| --- | --- | --- |
| ... | ... | ... |

## 质量与风险
- 正确性：
- 性能：
- 安全：
- 并发：
- 建议验证：

Spring Boot 标准结构

src/main/java/com/example/
├── config/          # 配置类
├── controller/      # REST API 层
├── service/         # 业务逻辑层
│   └── impl/
├── repository/      # JPA Repository 或 DAO
├── mapper/          # MyBatis Mapper
├── domain/entity/   # 实体类
├── dto/             # 请求/响应 DTO
├── exception/       # 自定义异常与统一异常处理
└── util/            # 无状态工具类

常见注解速查

| 场景 | 注解 | | - | - | | REST Controller | @RestController, @RequestMapping, @GetMapping, @PostMapping | | 服务层 | @Service, @Transactional | | 仓储层 | @Repository, @Mapper | | 依赖注入 | 构造器注入、@RequiredArgsConstructor | | 配置 | @Configuration, @Bean, @ConfigurationProperties | | 参数校验 | @Valid, @Validated, @NotNull, @NotBlank, @Size | | 缓存 | @Cacheable, @CacheEvict, @CachePut | | 异常处理 | @RestControllerAdvice, @ExceptionHandler |

编码规范

• 类名使用 PascalCase，方法/变量使用 camelCase，常量使用 UPPER_SNAKE_CASE。
• 优先构造器注入，避免字段注入；依赖尽量声明为接口类型。
• 不吞异常；捕获后必须记录上下文、转换为业务异常或继续抛出。
• 使用 SLF4J 日志，禁止 System.out.println() 进入业务代码。
• Controller 不写业务细节，Service 不直接拼 HTTP 响应，Repository/Mapper 不承载业务规则。
• @Transactional 放在业务边界；注意自调用、异常类型和只读事务配置。
• DTO 与 Entity 分离，禁止把 JPA Entity 直接暴露为长期 API 响应契约。
• 魔法数字、状态码、业务类型优先使用 enum 或常量表达。

数据访问

• JPA：关注懒加载、N+1、事务边界、级联删除、脏检查和分页查询。
• MyBatis：关注 XML/注解 SQL 参数绑定，禁止 ${} 拼接外部输入，优先 #{}。
• 批量写入：使用批处理或分批提交，明确事务大小与失败回滚策略。
• 查询性能：为高频 WHERE/JOIN/ORDER BY 字段提供索引依据，必要时协同 mysql-database。

并发与异步

• 线程池必须显式配置核心线程数、最大线程数、队列长度、拒绝策略和线程名。
• CompletableFuture 需指定 Executor，避免默认 ForkJoinPool 被阻塞任务占满。
• 共享状态必须说明线程安全策略：不可变对象、局部变量、锁、并发集合或原子类。
• 分布式场景关注幂等、重试、超时、熔断、降级和链路追踪。
• @Async、调度任务、消息消费必须有异常处理和监控日志。

测试

• 单元测试：JUnit 5 + Mockito，隔离纯业务逻辑、边界条件和异常分支。
• Spring 集成测试：@SpringBootTest、@WebMvcTest、@DataJpaTest 按范围选择，避免所有测试都启动完整上下文。
• 外部依赖：数据库、Redis、MQ 可使用 Testcontainers 或测试替身。
• Web 接口：使用 MockMvc 或 WebTestClient 断言状态码、响应体和副作用。
• 每个修复缺陷至少补一条回归测试。

JVM 与性能

基础诊断参数示例，使用前需确认线上 JDK、容器内存和运维规范：

# 堆内存
-Xms512m -Xmx2g

# Java 11+ 常用 GC
-XX:+UseG1GC

# GC 日志
-Xlog:gc*:file=gc.log:time,uptime:filecount=5,filesize=10m

性能问题优先采集证据：接口耗时、线程 dump、堆 dump、GC 日志、慢 SQL、连接池指标。没有基线不得声称优化有效。

验证命令

按项目构建工具选择：

mvn test
mvn verify
mvn spring-boot:run
./gradlew test
./gradlew build
./gradlew bootRun

关联 reference

• code-generation：生成 Controller、Service、DTO、Repository、测试代码。
• code-review：按 Java 专项审查清单补充正确性、安全、性能、并发检查。
• test-generation：生成 JUnit、Mockito、Spring Boot Test、集成测试。
• performance-benchmark：JVM、GC、线程池、接口耗时和基准对比。
• software-project：发布、回滚、监控、告警、巡检。