构建Spring Boot代码审查Skill：让Claude Code成为你的高级架构师

本文手把手教你创建一个专为Spring Boot项目设计的代码审查Skill，涵盖从架构规范到安全实践的全面检查，让AI辅助团队提升代码质量。

一、为什么需要AI驱动的代码审查？

代码审查是保障软件质量的关键环节，但传统人工审查存在明显痛点：

  • 人力成本高：资深工程师时间宝贵，难以覆盖所有代码
  • 标准不统一：不同审查者侧重点不同，结论差异大
  • 知识传承难：团队最佳实践难以固化，新人上手慢

借助Claude Code的Skills机制，我们可以将团队的审查标准、架构原则、安全规范封装成一个可复用的Skill。当开发者提交代码或请求审查时，Claude自动加载该Skill，化身“虚拟架构师”，系统化地检查代码，输出结构化报告，并给出修复建议。

二、Skill核心概念回顾

在深入构建审查Skill前，先回顾几个关键点：

概念 说明
SKILL.md 包含YAML元数据（name/description）和Markdown指令主体的文件，是Skill的核心。
渐进式披露 Claude先加载元数据（约30-50 tokens），匹配任务后才加载完整指令，节省上下文。
自动触发 当用户请求匹配description时，Skill自动激活，无需手动指定。
项目级安装 将Skill文件夹放入.claude/skills/，纳入Git版本管理，实现团队共享。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

三、Spring Boot代码审查Skill的设计

3.1 设计目标

  • 全面性：覆盖Controller、Service、Repository、Entity、Config、Security、Test等所有层次
  • 可操作性：每项检查都有明确的判定标准和修复提示
  • 结构化输出：生成包含评分、严重问题、一般问题、改进建议的标准化报告
  • 可定制性：允许团队根据项目实际情况增删检查项

3.2 Skill文件结构

.claude/skills/spring-boot-review/
└── SKILL.md

3.3 SKILL.md 核心内容解析

我们逐块解析该Skill的设计思路。

（1）元数据（YAML）
---
name: spring-boot-review
description: 对Spring Boot 3.x项目的Java代码进行系统化审查，覆盖控制器、服务、仓储、配置、安全、测试等全环节。当用户提到“审查代码”、“代码检查”、“review”或“检查Spring Boot项目”时自动触发。
---
  • name：Skill唯一标识
  • description：触发条件的关键，必须覆盖常见用户表述，确保匹配精准。
（2）审查流程总览

Skill首先定义了四步流程：

  1. 理解上下文：读取pom.xml确定版本和依赖，明确审查范围。
  2. 分层审查：按架构层次逐一检查，确保无遗漏。
  3. 输出报告：使用固定模板生成结构化报告。
  4. 交互与跟进：对不确定处提问，并可按需提供修复代码。
（3）分层检查项详解
控制器层（Controller）
检查点 重要性 常见问题
使用@RestController 必需 误用@Controller导致返回视图
路径规范（/api/v1/...） 推荐 路径混乱，无版本管理
参数校验（@Valid） 必需 未校验导致脏数据进入服务层
使用DTO而非Entity返回 高危 暴露数据库字段，引发安全风险
不捕获异常 必需 捕获异常后返回非标准响应，破坏全局处理
无业务逻辑 必需 控制器内写if/else，破坏分层
服务层（Service）
检查点 重要性 常见问题
构造器注入（非@Autowired字段） 推荐 字段注入导致单元测试困难
@Transactional粒度 重要 过大事务导致锁竞争，过小导致数据不一致
自定义业务异常 重要 抛出通用RuntimeException，难以区分错误类型
复杂条件分支 建议 大量if/else可引入策略模式或状态机
外部调用容错（超时/重试） 重要 未处理导致级联故障
数据访问层（Repository）
检查点 重要性 常见问题
SQL注入风险（@Query拼接） 高危 使用字符串拼接参数，易被注入
分页排序正确使用 建议 未使用Pageable导致全量查询
方法命名符合规范 建议 过长或模糊命名影响可读性
实体与DTO
检查点 重要性 常见问题
实体与DTO分离 必需 直接返回实体，或实体中包含JSON注解
Lombok合理使用 建议 滥用@Data导致无参构造器暴露，或@EqualsAndHashCode调用延迟加载
敏感字段脱敏（@JsonIgnore） 重要 密码等字段被序列化输出
全局异常处理
检查点 重要性 常见问题
存在@ControllerAdvice 必需 无统一处理，每个控制器各自捕获
统一错误响应格式 推荐 code、message、timestamp等不统一
处理参数校验异常 必需 MethodArgumentNotValidException未捕获，返回500
配置与安全
检查点 重要性 常见问题
类型安全的配置绑定（@ConfigurationProperties） 推荐 散落的@Value，难以维护
Spring Security配置 重要 未设置权限、密码未编码、CORS配置不当
敏感信息外泄（日志、响应） 高危 打印密码、令牌等
测试（可选）
  • 切片测试（@WebMvcTest、@DataJpaTest）使用
  • Mockito模拟依赖
  • 分支覆盖率和异常场景覆盖
代码风格
  • 包命名规范
  • 注释完整性（特别是复杂逻辑）
  • 日志级别使用（@Slf4j）

四、报告模板设计

Skill强制要求输出结构化报告，包含以下部分：

# Spring Boot 代码审查报告
**项目**：[项目名称]  
**审查范围**：[具体包/文件]  
**审查日期**：[日期]  

## 总体评价
- **评分**：[优秀 / 良好 / 及格 / 待改进]
- **主要优点**：（2～3个）
- **主要缺陷**：（2～3个）

## 严重问题（必须修复）
| 文件 | 行号 | 问题描述 | 建议修复 |
|------|------|----------|----------|

## 一般问题（建议优化）
| 文件 | 行号 | 问题描述 | 建议修复 |
|------|------|----------|----------|

## 最佳实践建议
（2～4条针对性改进建议）

## 下一步行动
- [ ] 行动1
- [ ] 行动2

这种模板化输出便于团队追踪问题、分配修复任务，并与CI/CD流程集成。

五、如何使用该Skill

5.1 安装步骤

  1. 在项目根目录创建 .claude/skills/spring-boot-review/ 目录。

  2. 将上述 SKILL.md 内容保存到该目录下。

  3. （可选）在根目录的 CLAUDE.md 中补充项目特定的编码规范，如DTO后缀、异常基类等，Skill会自动继承这些约定。

    完整SILL.md内容:

    ---
name: spring-boot-review
description: 对Spring Boot 3.x项目的Java代码进行系统化审查，覆盖控制器、服务、仓储、配置、安全、测试等全环节。当用户提到“审查代码”、“代码检查”、“review”或“检查Spring Boot项目”时自动触发。

---

# Spring Boot 代码审查技能

你是一名拥有十年经验的 Java 架构师，专精于 Spring Boot 生态。收到代码审查请求后，请严格按照以下流程执行，并输出结构化的审查报告。

## 审查流程

### 第一步：理解上下文

1. 如果用户指定了具体文件或包路径，优先分析该范围。
2. 否则，默认审查 `src/main/java` 下的所有代码（可询问用户是否需包含测试代码）。
3. 先通过 `pom.xml` 或 `build.gradle` 了解项目使用的 Spring Boot 版本、主要依赖（如 JPA、MyBatis、Security、Cloud 等），以确定适用的最佳实践。

### 第二步：分层审查（按顺序）

#### 2.1 控制器层（Controller）

**检查项**：

- [ ] 类上是否有 `@RestController` 或 `@Controller` 注解？
- [ ] 是否使用了 `@RequestMapping` 或衍生注解（`@GetMapping` 等）并定义了合理的路径（如 `/api/v1/...`）？
- [ ] 方法参数是否使用 `@Valid` / `@Validated` 进行校验？
- [ ] **是否直接返回了实体类（Entity）？** → 必须使用 DTO 或 VO，避免暴露内部结构。
- [ ] 是否捕获了异常？→ 控制器不应捕获异常，应交给全局异常处理器。
- [ ] 是否在控制器中编写了业务逻辑？→ 仅做参数校验、调用服务、返回响应。
- [ ] 是否使用了 `@ResponseStatus` 或 `ResponseEntity` 正确设置 HTTP 状态码？

#### 2.2 服务层（Service）

**检查项**：

- [ ] 类上是否标注 `@Service`？
- [ ] 是否使用**构造器注入**（推荐）而非 `@Autowired` 字段注入？
- [ ] 业务方法是否合理划分，单一职责？
- [ ] 是否使用了 `@Transactional`？检查事务边界是否合理（通常放在 service 层，避免过大）。
- [ ] 是否抛出**自定义业务异常**（而非 `RuntimeException`）？
- [ ] 是否有过多的 `if/else` 或 switch，考虑使用策略模式或枚举？
- [ ] 是否对输入参数进行了业务级校验（非空、范围等）？
- [ ] 是否调用了其他 service 或外部接口，是否有超时/重试等容错处理？

#### 2.3 数据访问层（Repository / DAO）

**检查项**：

- [ ] 接口是否继承 `JpaRepository`（或 `MyBatis-Plus` 的 `BaseMapper`）？
- [ ] 自定义查询方法命名是否符合 Spring Data 规范？
- [ ] 使用原生 SQL 或条件构造器时，是否存在 SQL 注入风险？（检查 `@Query` 中的拼接）
- [ ] 是否合理使用分页（`Pageable`）和排序？
- [ ] 是否在 repository 中定义了不必要的复杂方法？

#### 2.4 实体与 DTO

**检查项**：

- [ ] 实体类是否使用 `@Entity`，并正确配置 JPA 注解（`@Id`、`@GeneratedValue`、`@Column`）？
- [ ] 是否使用 Lombok 简化代码（`@Data`、`@Builder` 等）？
- [ ] DTO/VO 是否与实体分离？是否使用 `@JsonIgnore` 避免序列化敏感字段？
- [ ] 是否在实体中编写了业务逻辑？→ 实体应是纯数据容器，逻辑应放到 service。

#### 2.5 全局异常处理（Exception Handler）

**检查项**：

- [ ] 是否存在 `@ControllerAdvice` 或 `@RestControllerAdvice` 类？
- [ ] 是否使用 `@ExceptionHandler` 统一处理自定义异常和标准异常？
- [ ] 错误响应格式是否统一（如包含 code、message、timestamp）？
- [ ] 是否处理了参数校验失败异常（`MethodArgumentNotValidException`）？

#### 2.6 配置类与安全

**检查项**：

- [ ] 是否使用 `@Configuration` 和 `@Bean` 合理组织配置？
- [ ] 是否将外部配置（`application.yml`）通过 `@ConfigurationProperties` 绑定为类型安全的类？
- [ ] 如果使用了 Spring Security，检查：
  - [ ] 是否配置了 `SecurityFilterChain`？
  - [ ] 是否对敏感接口进行了权限控制（`@PreAuthorize`）？
  - [ ] 密码是否使用 `PasswordEncoder` 编码？
- [ ] CORS 配置是否正确？（若前后端分离）

#### 2.7 单元测试与集成测试

**检查项**（如果用户要求审查测试代码）：

- [ ] 是否使用 `@SpringBootTest` 或 `@WebMvcTest` / `@DataJpaTest` 切片测试？
- [ ] 是否使用 `Mockito` 模拟依赖？
- [ ] 是否覆盖了核心业务分支？
- [ ] 是否验证了异常场景？

#### 2.8 代码风格与规范

- [ ] 包命名是否符合规范（如 `com.example.project.module`）？
- [ ] 类、方法、变量命名是否清晰且符合 CamelCase？
- [ ] 是否包含必要的注释（尤其是复杂逻辑）？
- [ ] 是否使用了 `@Slf4j` 并合理打印日志（不要过多或过少）？

### 第三步：输出审查报告

请按以下模板生成最终报告：

```markdown
# Spring Boot 代码审查报告

**项目**：[项目名称]  
**审查范围**：[具体包/文件]  
**审查日期**：[日期]  

## 总体评价
- **评分**：[优秀 / 良好 / 及格 / 待改进]
- **主要优点**：（列出 2～3 个亮点）
- **主要缺陷**：（列出 2～3 个核心问题）

## 严重问题（必须修复）
| 文件 | 行号 | 问题描述 | 建议修复 |
|------|------|----------|----------|
| ...  | ...  | ...      | ...      |

## 一般问题（建议优化）
| 文件 | 行号 | 问题描述 | 建议修复 |
|------|------|----------|----------|
| ...  | ...  | ...      | ...      |

## 最佳实践建议
（列出 2～4 条针对该项目的具体改进建议，例如：引入统一响应体、添加缓存、优化事务粒度等）

## 下一步行动
- [ ] 行动1
- [ ] 行动2
```

5.2 触发方式

  • 自动触发：在Claude Code会话中说出关键词，例如：
    • “帮我审查一下 UserController 这个类。”
    • “对整个项目做一次代码质量检查。”
    • “我的Spring Boot项目快上线了，帮我review一遍。”
  • 手动触发：输入 /spring-boot-review 强制启用（如果自动匹配未生效）。

5.3 交互示例

用户：

请按照 spring-boot-review 技能，审查我的 com.example.demo.controller.UserController 和 com.example.demo.service.UserService 文件。

Claude（加载Skill后）：

  1. 读取两个文件的代码。
  2. 依次检查控制器、服务层相关项。
  3. 发现问题后，会提问确认（例如：“我看到 UserController 的 create 方法直接返回了 User 实体，是否考虑改用 UserDto？”）。
  4. 生成完整报告，并附上修复代码示例（如果需要）。

测试效果：

请添加图片描述

六、扩展与定制建议

每个团队都有自己的技术栈和规范，Skill应当具备可定制性。

6.1 添加团队特有规则

例如，你的团队强制使用@Slf4j且禁止System.out.println，可以在Skill中增加检查项：

#### 日志规范
- [ ] 是否使用 `@Slf4j` 而非 `System.out`？
- [ ] 日志级别是否正确（debug/info/warn/error）？

6.2 针对不同模块拆分Skill

  • spring-boot-security-review：专注安全配置
  • spring-boot-performance-review：关注缓存、异步、连接池
  • spring-boot-test-review：专注于测试覆盖率与质量

6.3 结合CI/CD

可以将Skill集成到GitHub Actions中，每次PR自动触发审查并评论报告，实现自动化代码质量门禁。

七、关键知识点提炼

知识点 说明
构造器注入 vs 字段注入 构造器注入使依赖不可变，且便于单元测试（无需反射）。
事务传播与隔离级别 根据业务场景选择REQUIRED、REQUIRES_NEW等，避免死锁。
全局异常处理 统一处理避免重复代码，且能返回标准错误格式，提升API友好性。
DTO与Entity分离 防止敏感字段泄露，同时解耦API与数据库模型。
Spring Security权限控制 使用@PreAuthorize实现方法级权限，比URL拦截更细粒度。
SQL注入防范 使用JPA参数绑定（:name）而非字符串拼接。

八、结语

通过创建Spring Boot代码审查Skill，我们不仅将团队多年的经验沉淀为可执行的知识库，还实现了AI辅助审查的自动化。开发者提交代码后，Claude Code能够快速定位潜在问题，并提供修复指导，既节省了高级工程师的时间，又加速了新人的成长。

这个Skill只是一个起点。你可以根据项目特点不断迭代，让它覆盖更多场景（如微服务调用链、性能监控等）。最终，Skill将成为团队不可或缺的“代码质量守护者”。

延伸阅读

# spring boot # 大数据 # 后端
Logo
亚马逊云科技技术品牌专区

更多推荐

从Java全栈到Vue3：一位资深开发者的实战面试记录

面试官：今天我们的面试就到这里。总体来说，你表现得很专业，尤其是在Spring Boot和Vue3方面的经验很扎实。如果你通过这次面试，我们会在一周内通知你。Java基础：JVM内存模型、GC机制、Spring Boot的使用微服务架构：Spring Cloud、服务治理、分布式事务前端技术：Vue3、TypeScript、组件化开发项目实战：电商系统、响应式编程、HTTP请求云原生数据库与ORM

avatar 亚马逊云科技技术品牌专区
cover

54.1.智能药盒（语音播报）-基于STM32单片机物联网设计【硬件+APP+云平台】

avatar 亚马逊云科技技术品牌专区
cover

58.1.智慧银行-指纹+人脸-基于STM32单片机物联网设计【硬件+APP+云平台】

avatar 亚马逊云科技技术品牌专区