#Java 开发最佳实践

my-spring-app/
├── CLAUDE.md                    ← 项目约定和上下文
├── pom.xml                      ← Maven 构建配置
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/app/
│   │   │       ├── Application.java
│   │   │       ├── controller/
│   │   │       ├── service/
│   │   │       ├── repository/
│   │   │       ├── model/
│   │   │       ├── dto/
│   │   │       ├── config/
│   │   │       └── exception/
│   │   └── resources/
│   │       ├── application.yml
│   │       └── db/migration/
│   └── test/
│       └── java/
│           └── com/example/app/
└── docs/

my-spring-app/
├── CLAUDE.md
├── build.gradle.kts
├── settings.gradle.kts
├── src/
│   ├── main/
│   │   ├── java/          ← 同 Maven 结构
│   │   └── resources/
│   └── test/
│       └── java/
└── gradle/

❌ "帮我写一个用户接口"
✅ "使用 Spring Boot 3.2 + JPA 实现用户 CRUD REST API：
   - UserRepository 继承 JpaRepository
   - UserService 包含分页查询
   - UserController 使用 @RestController
   - 使用 UserDTO 隔离 Entity
   - 遵循现有 src/main/java/com/example/app/service/OrderService.java 的代码风格"

> 第一步：先帮我创建 User 实体类和 DTO，放在 model/ 和 dto/ 包下
> 第二步：创建 UserRepository 接口
> 第三步：实现 UserService，包含 CRUD 和分页查询
> 第四步：创建 UserController，使用 @Validated 校验参数
> 第五步：编写单元测试和集成测试

> 参考 src/main/java/com/example/app/service/OrderService.java 的代码风格，
> 创建 ProductService，包含：
> - 分页查询所有商品
> - 按分类筛选
> - 库存扣减（需要 @Transactional）

> 用 TDD 方式实现邮箱验证服务：
> 1. 先写 EmailValidationService 的单元测试，覆盖以下场景：
>    - 合法邮箱返回 true
>    - 空字符串抛出 IllegalArgumentException
>    - 无 @ 符号返回 false
>    - 包含特殊字符的边界情况
> 2. 运行测试确认失败
> 3. 写最小实现让测试通过
> 4. 重构优化

> 为 src/main/java/com/example/app/service/OrderService.java 编写单元测试：
> - 使用 JUnit 5 + Mockito
> - Mock OrderRepository 和 PaymentService
> - 测试 createOrder 的正常流程
> - 测试库存不足时抛出 InsufficientStockException
> - 测试分页查询参数传递正确
> - 使用 @DisplayName 注解描述每个测试用例

> 为 UserController 编写集成测试：
> - 使用 @SpringBootTest + @AutoConfigureMockMvc
> - 使用 Testcontainers 启动 PostgreSQL
> - 测试完整的 HTTP 请求/响应流程
> - 验证 JSON 响应格式和状态码

> 在 pom.xml 中添加 Spring Security 依赖，版本使用 Spring Boot BOM 管理

> 分析 pom.xml 中的依赖冲突，找出哪些依赖版本不一致

> 为项目配置 Maven Wrapper（mvnw），确保团队使用统一的 Maven 版本

> 在 build.gradle.kts 中添加 Spring Security 依赖

> 配置 Gradle 的依赖版本目录（libs.versions.toml），统一管理第三方库版本

> 使用 Context7 查询 Spring Data JPA 3.2 的 findBy 方法命名规范

> 查询 Spring Security 6.2 的 @PreAuthorize 注解最新用法

> 使用 ECC 的 java-reviewer 审查 PaymentService.java：
> 检查 @Transactional 边界、异常处理、线程安全问题

> 使用 springboot-tdd skill 实现订单模块：
> 先写测试，再实现 Repository → Service → Controller

> java-build-resolver：pom.xml 报依赖冲突，帮我分析并解决

1. 🔴 RED    — 先写 JUnit 5 测试，运行 mvn test 确认失败
2. 🟢 GREEN  — 写最小实现让测试通过
3. 🔵 REFACTOR — 重构优化，运行 mvn test 确认无回归

> 使用 Superpowers 工作流，实现用户注册功能：
> 1. 头脑风暴确认需求（邮箱验证？手机验证？密码强度规则？）
> 2. 创建 Git Worktree 隔离开发
> 3. 编写计划：拆分为 Entity → DTO → Repository → Service → Controller → 测试
> 4. TDD 驱动：每个组件先写测试再实现
> 5. 代码审查：检查异常处理、事务边界、安全性

> /superpowers:brainstorming
> 设计一个订单状态机，支持待支付、已支付、发货中、已完成、已取消状态转换

> /superpowers:systematic-debugging
> 集成测试在 CI 上间歇性失败，本地无法复现，帮我排查

> /plan-eng-review
> 审查多租户 SaaS 的架构方案：每个租户独立 Schema 还是共享 Schema + tenant_id？

> /review
> 在 feature/order-state-machine 分支上审查代码变更

> /cso
> 审查 Spring Security 配置和 JWT 实现，检查 OWASP Top 10 漏洞

> /ship
> 运行 mvn verify，确认测试通过后推送到远程并创建 PR

> 这个 Spring Boot 项目的认证流程是什么？从登录接口到 JWT 生成的完整链路

> 如果我修改 Order.java 的状态字段，会影响哪些 Service 和测试？

> 追踪从 POST /api/orders 到数据库 INSERT 的完整调用链

> 把 UserService.authenticate() 重命名为 verifyCredentials()，包括所有 Controller 和测试中的调用

> 哪些地方调用了 OrderRepository.findByStatus？如果删除这个方法会影响什么？

> 把 PaymentService 中的 calculateTotal 方法提取到 PricingStrategy 类中

> 查看 OrderService.java 的符号大纲，有哪些公开方法？

> /speckit.specify
> 为订单模块编写规格：
> - 用户可以创建订单（包含多个订单项）
> - 订单支持待支付、已支付、已发货、已完成、已取消五种状态
> - 状态转换有明确的业务规则（如已发货不可取消）
> - 支持按日期范围和状态筛选订单列表

> /speckit.clarify
> 澄清订单模块的规格

> /speckit.plan
> 生成 Spring Boot 技术方案

1. Superpowers: /superpowers:brainstorming 探索需求（邮箱验证？密码策略？）
2. Gstack: /plan-eng-review 审查架构方案
3. CodeGraph: codegraph_explore 理解现有代码结构
4. Superpowers: TDD 驱动实现 → 每层先写 JUnit 5 测试
5. ECC: java-reviewer 审查代码 → security-reviewer 安全审查
6. Gstack: /ship 运行 mvn verify → 推送并创建 PR

1. CodeGraph: codegraph_impact 分析重构影响范围
2. Serena: find_referencing_symbols 追踪所有引用
3. Gstack: /plan-eng-review 审查重构方案
4. Serena: rename_symbol / move_symbol 精确重构
5. CodeGraph: codegraph_impact 验证变更完整性
6. Gstack: /review 审查 → /cso 安全审计

1. CodeGraph: codegraph_explore 快速理解项目架构和路由
2. Serena: get_symbols_overview 梳理核心类的公开 API
3. Gstack: /office-hours 梳理业务需求
4. ECC: java-reviewer 识别代码问题 → security-reviewer 安全扫描
5. Superpowers: TDD 驱动渐进式重构，每步都有测试覆盖

1. ECC AgentShield: npx ecc-agentshield scan --opus --stream 深度安全扫描
2. CodeGraph: codegraph_trace 追踪敏感数据流向（用户密码、支付信息）
3. Gstack: /cso OWASP Top 10 + STRIDE 威胁建模
4. ECC: security-reviewer 逐模块审查
5. Superpowers: TDD 驱动安全修复 → 回归测试

1. Gstack: /office-hours 探索业务需求 → /plan-eng-review 审查架构
2. Spec-Kit: /speckit.constitution 建立 Java 项目原则（Library-First、Test-First）
3. Spec-Kit: /speckit.specify 编写功能规格 → /speckit.clarify 澄清边界情况
4. Spec-Kit: /speckit.plan 生成 Spring Boot 技术方案 → /speckit.analyze 验证一致性
5. Superpowers: TDD 驱动实现 → 每层先写 JUnit 5 测试
6. Spec-Kit: /speckit.taskstoissues 同步任务到 GitHub Issues → 团队协作开发

> 基于现有的 User 实体类，生成完整的 REST API：
> 1. UserDTO（请求和响应分开：CreateUserRequest, UpdateUserRequest, UserResponse）
> 2. MapStruct 转换器 UserMapper
> 3. UserRepository（继承 JpaRepository）
> 4. UserService（CRUD + 分页 + 按用户名搜索）
> 5. UserController（RESTful 路由 + 参数校验）
> 6. 全局异常处理器
> 7. 对应的单元测试和集成测试
>
> 参考项目中 Order 模块的代码风格

> 创建 Flyway 迁移脚本，添加 product 表：
> - id: BIGSERIAL 主键
> - name: VARCHAR(100) 非空
> - price: DECIMAL(10,2) 非空
> - stock: INTEGER 默认 0
> - category_id: BIGINT 外键关联 category 表
> - created_at, updated_at: TIMESTAMP
> 添加索引：category_id 和 name

> 创建 OrderMapper（MapStruct），实现：
> - Order → OrderResponse 转换
> - CreateOrderRequest → Order 转换
> - List<Order> → List<OrderResponse> 批量转换
> - 嵌套对象：OrderItem → OrderItemResponse
> 使用 @Mapper(componentModel = "spring")

> 创建统一 API 响应包装：
> 1. ApiResponse<T> 泛型类：code, message, data, timestamp
> 2. PageResponse<T> 分页响应：content, totalElements, totalPages, currentPage
> 3. 创建 ApiResponseHelper 工具类：
>    - success(T data) → ApiResponse
>    - success(Page<T>) → PageResponse
>    - error(ErrorCode) → ApiResponse
>    - error(int code, String message) → ApiResponse

> 创建统一异常处理体系：
> 1. ErrorCode 枚举：定义业务错误码（USER_NOT_FOUND, ORDER_ALREADY_PAID 等）
> 2. BusinessException 继承 RuntimeException，包含 ErrorCode
> 3. GlobalExceptionHandler 使用 @RestControllerAdvice：
>    - BusinessException → 对应错误码和消息
>    - MethodArgumentNotValidException → 400 + 字段错误列表
>    - AccessDeniedException → 403
>    - Exception → 500 + 通用错误消息
> 4. ErrorResponse DTO：code, message, errors, timestamp

> 配置 Spring Security：
> 1. SecurityConfig 类，使用 @Configuration
> 2. 配置 JWT 认证过滤器
> 3. 放行公开接口：/api/auth/login, /api/auth/register, /actuator/health
> 4. 其他接口需要认证
> 5. 配置 CORS 允许前端域名
> 6. 配置密码编码器 BCryptPasswordEncoder

> 使用 MyBatis-Plus 实现用户模块：
> 1. UserMapper 继承 BaseMapper<User>
> 2. UserServiceImpl 实现 IService<User>
> 3. 自定义查询使用 @Select 注解或 XML Mapper
> 4. 分页使用 MybatisPlusInterceptor + PaginationInnerInterceptor

> 审查 src/main/java/com/example/app/service/PaymentService.java：
> 1. 检查线程安全问题
> 2. 检查异常处理是否完善
> 3. 检查是否有资源泄漏（数据库连接、流等）
> 4. 检查事务边界是否正确
> 5. 检查是否有 N+1 查询问题

> 扫描整个 service/ 包，找出：
> - 缺少 @Transactional 的方法
> - 硬编码的魔法值
> - 过长的方法（超过 50 行）
> - 不一致的异常处理方式

> 重构 src/main/java/com/example/app/service/OrderService.java：
> 1. 提取订单状态机逻辑到 OrderStateMachine 类
> 2. 将金额计算逻辑抽取到 PricingStrategy 接口
> 3. 使用策略模式替代 if-else 的支付方式选择
> 4. 保持所有现有测试通过

> 分析 src/main/java/com/example/app/legacy/ 目录：
> 1. 找出使用的过时 API（如 javax.* → jakarta.*）
> 2. 识别可以使用 Java 21 新特性的代码（record, sealed class, pattern matching）
> 3. 标记可以使用 Stream API 替代 for 循环的地方
> 4. 列出 Lombok 可以消除的样板代码
> 生成重构计划，按风险从低到高排序

> 分析 ProductService 的性能问题：
> 1. 找出 N+1 查询（检查 @OneToMany, @ManyToOne 的 fetch 类型）
> 2. 检查是否有不必要的数据库调用可以批量处理
> 3. 分析是否需要添加缓存（@Cacheable）
> 4. 检查分页查询是否使用了正确的索引
> 给出优化建议和具体代码改动

.claude/skills/
├── create-api-endpoint/
│   └── SKILL.md          ← 创建 REST API 端点的标准流程
├── flyway-migration/
│   └── SKILL.md          ← Flyway 迁移脚本审查流程
└── service-review/
    └── SKILL.md          ← Service 层代码审查检查清单

> /create-api-endpoint
> 创建商品管理 API，包含 CRUD、分页查询和按分类筛选

> /service-review
> 审查 OrderService.java

> /flyway-migration
> 审查 V3__add_payment_table.sql

# 验证 LSP 是否生效
# 进入 Java 项目后问 Claude：
> UserService 在哪里定义？
# 如果秒返回精确文件路径和行号 = LSP 已生效
# 如果返回多个 grep 结果并逐个分析 = LSP 未生效

# 使用 /compact 压缩上下文
> /compact 保留 Spring Boot 和 Maven 相关的上下文

# 使用 /clear 重新开始
> 当切换到不相关的功能模块时，用 /clear 清除上下文避免干扰

# 使用 Context7 获取最新文档
> 查询 Spring Data JPA 3.2 的 findBy 方法命名规范

# 使用 CodeGraph 快速探索代码
> codegraph_explore 这个项目的权限控制是怎么实现的？

# 使用 Serena 精确重构
> 把 UserService.authenticate 重命名为 verifyCredentials，包括所有引用