p3c-code-quality

---
name: "p3c-code-quality"
description: "执行代码质量检查测试，基于阿里巴巴 P3C 规范对代码进行全面检查，包括命名规范、异常处理、并发安全、数据库规范、OOP 规范、安全规约和单元测试规范。Invoke when user needs to verify code quality against P3C standards."
version: "1.0.0"
p3c_version: "《阿里巴巴 Java 开发手册》2022 版"
last_updated: "2026-03-11"
author: "赵辉亮"
---

# P3C代码质量检查测试

本技能基于阿里巴巴Java开发手册P3C规范，对代码进行全面的质量检查测试。

## 测试范围

本测试技能涵盖以下P3C规范领域：

### 1. 代码风格规范 (p3c-coding-style)
- 命名风格：类名、方法名、变量名、常量命名规范
- 代码格式：大括号、缩进、空格、行长度等格式规范
- 常量定义：魔法值、Long类型、常量分类
- 注释规约：Javadoc规范、注释语言、注释同步更新

### 2. 异常与日志规范 (p3c-exception-logging)
- 异常处理：异常捕获原则、异常处理要求、NPE防护
- 日志规约：日志框架、日志保存、日志输出、日志级别

### 3. 高级编程规范 (p3c-advanced-coding)
- 集合处理：hashCode和equals、subList使用、集合转数组、foreach循环
- 并发处理：线程池、锁性能、死锁预防、并发更新
- 控制语句：switch语句、大括号使用、if-else优化

### 4. MySQL数据库规范 (p3c-mysql-database)
- 建表规约：字段要求、表名要求、索引命名
- SQL语句规约：count使用、in操作、分页查询
- 索引规约：唯一索引、join限制、索引长度
- ORM映射规约：查询字段、参数绑定、事务管理

### 5. OOP编程规范 (p3c-oop-standards)
- 方法覆写：@Override注解、equals方法、包装类比较
- 序列化：serialVersionUID、toString方法
- 访问控制：类成员访问控制、final关键字使用

### 6. 安全规约 (p3c-security-rules)
- 权限控制：水平权限校验、数据脱敏
- SQL注入防护：参数绑定、字符串拼接
- XSS/CSRF防护：安全过滤、防重放限制
- 参数验证：有效性验证、防刷策略

### 7. 单元测试规范 (p3c-unit-testing)
- AIR原则：自动化、独立性、可重复性
- 测试粒度：方法级别测试、核心业务测试
- 测试覆盖率：语句覆盖率、分支覆盖率
- BCDE原则：边界值、正确输入、设计文档、错误输入

## 使用时机

- 功能开发完成后
- 需求变更后
- Bug修复后
- 回归测试
- 代码提交前

## 执行方式

本技能使用 Trae IDE 内置工具进行代码质量检查，无需额外脚本：

### 基本测试流程
1. **查找 Java 文件**：使用 `Glob` 工具查找所有 `.java` 文件
2. **读取代码内容**：使用 `Read` 工具读取文件内容
3. **代码结构分析**：使用 `SearchCodebase` 进行代码结构分析
4. **获取编译诊断**：使用 `GetDiagnostics` 获取编译错误和警告
5. **正则匹配检查**：使用 `Grep` 工具配合正则表达式匹配 P3C 规范违规
6. **调用子技能**：调用以下子技能进行详细检查
   - p3c-coding-style
   - p3c-exception-logging
   - p3c-advanced-coding
   - p3c-mysql-database
   - p3c-oop-standards
   - p3c-security-rules
   - p3c-unit-testing
7. **生成测试报告**：使用 `Write` 工具生成 Markdown 格式报告

### 常用 Trae IDE 内置工具

**文件查找工具**
- `Glob` - 查找所有 `.java` 文件
- `LS` - 列出目录结构

**代码读取工具**
- `Read` - 读取文件内容
- `SearchCodebase` - 搜索代码库中的特定模式和结构

**代码分析工具**
- `Grep` - 使用正则表达式搜索代码，匹配 P3C 规则
- `GetDiagnostics` - 获取 Trae IDE 的语言诊断信息（编译错误、警告等）

**报告生成工具**
- `Write` - 生成 Markdown 格式的测试报告

### 子技能说明

本技能是聚合技能，会调用以下子技能进行详细检查：

| 子技能 | 描述 | 检查内容 |
|--------|------|---------|
| p3c-coding-style | 代码风格规范 | 命名风格、代码格式、常量定义、注释规约 |
| p3c-exception-logging | 异常与日志规范 | 异常处理、日志规约、NPE防护 |
| p3c-advanced-coding | 高级编程规范 | 集合处理、并发处理、控制语句 |
| p3c-mysql-database | MySQL数据库规范 | 建表规约、SQL语句、索引规约、ORM映射 |
| p3c-oop-standards | OOP编程规范 | 方法覆写、equals/hashCode、包装类、序列化 |
| p3c-security-rules | 安全规约 | 权限控制、SQL注入防护、XSS/CSRF防护、参数验证 |
| p3c-unit-testing | 单元测试规范 | AIR原则、测试粒度、测试覆盖率、BCDE原则 |

## 测试执行流程

### 步骤1：代码扫描
使用 Trae IDE 内置工具扫描指定的Java源代码文件或目录：
- 使用 `Glob` 查找所有 `.java` 文件
- 使用 `Read` 读取文件内容
- 使用 `SearchCodebase` 进行代码结构分析
- 使用 `GetDiagnostics` 获取编译诊断信息

### 步骤2：规范检查
根据P3C规范对代码进行逐项检查。本技能是聚合技能，会调用以下子技能进行详细检查：

#### 子技能调用
1. **p3c-coding-style** - 代码风格规范
   - 命名风格：类名、方法名、变量名、常量命名规范
   - 代码格式：大括号、缩进、空格、行长度等格式规范
   - 常量定义：魔法值、Long类型、常量分类
   - 注释规约：Javadoc规范、注释语言、注释同步更新

2. **p3c-exception-logging** - 异常与日志规范
   - 异常处理：异常捕获原则、异常处理要求、NPE防护
   - 日志规约：日志框架、日志保存、日志输出、日志级别

3. **p3c-advanced-coding** - 高级编程规范
   - 集合处理：hashCode和equals、subList使用、集合转数组、foreach循环
   - 并发处理：线程池、锁性能、死锁预防、并发更新
   - 控制语句：switch语句、大括号使用、if-else优化

4. **p3c-mysql-database** - MySQL数据库规范
   - 建表规约：字段要求、表名要求、索引命名
   - SQL语句规约：count使用、in操作、分页查询
   - 索引规约：唯一索引、join限制、索引长度
   - ORM映射规约：查询字段、参数绑定、事务管理

5. **p3c-oop-standards** - OOP编程规范
   - 方法覆写：@Override注解、equals方法、包装类比较
   - 序列化：serialVersionUID、toString方法
   - 访问控制：类成员访问控制、final关键字使用

6. **p3c-security-rules** - 安全规约
   - 权限控制：水平权限校验、数据脱敏
   - SQL注入防护：参数绑定、字符串拼接
   - XSS/CSRF防护：安全过滤、防重放限制
   - 参数验证：有效性验证、防刷策略

7. **p3c-unit-testing** - 单元测试规范
   - AIR原则：自动化、独立性、可重复性
   - 测试粒度：方法级别测试、核心业务测试
   - 测试覆盖率：语句覆盖率、分支覆盖率
   - BCDE原则：边界值、正确输入、设计文档、错误输入

#### 检查方法
使用 `Grep` 工具配合正则表达式匹配代码中的P3C规范违规：
- **强制规范**：必须遵守，违反即视为严重问题
- **推荐规范**：建议遵守，违反视为一般问题
- **参考规范**：可选择性遵守，违反视为轻微问题

### 步骤3：问题分类
将检查到的问题按严重程度分类：
- **致命问题**：违反强制规范，可能导致严重后果
- **严重问题**：违反强制规范，影响代码质量
- **一般问题**：违反推荐规范，影响代码可维护性
- **轻微问题**：违反参考规范，属于优化建议

### 步骤4：生成测试报告
使用 `Write` 工具生成详细的测试报告，包含：
- 测试范围和测试时间
- 问题统计（按严重程度和规范类别）
- 问题详情列表
- 改进建议

## 输入参数

执行测试时需要提供以下参数：

1. **代码路径**：要检查的Java源代码文件或目录路径
2. **业务名称**：用于生成报告路径和文件名
3. **测试内容**：描述本次测试的具体内容
4. **测试接口/模块名称**：被测试的接口或模块名称

## 测试报告格式

测试报告将生成到以下路径：
```
doc/{业务名称}/测试报告/{测试内容}/{测试接口名称}_{时间戳}.md
```

报告包含以下内容：

### 报告头部
- 测试时间
- 测试人员
- 测试范围
- 测试工具

### 问题统计
- 问题总数
- 致命问题数量
- 严重问题数量
- 一般问题数量
- 轻微问题数量

### 问题分类统计
按P3C规范类别统计问题分布

### 问题详情列表
每个问题包含：
- 问题编号
- 严重程度
- 规范类别
- 规则描述
- 代码位置（文件名、行号）
- 问题说明
- 修改建议

### 改进建议
- 高优先级改进项
- 中优先级改进项
- 低优先级改进项

### 质量评估
- 代码质量评分
- 符合度百分比
- 风险评估

## 使用示例

### 示例 1：检查单个文件
```
输入：
- 代码路径：src/main/java/com/example/UserService.java
- 业务名称：用户管理
- 测试内容：代码质量检查
- 测试接口名称：UserService

输出：
- 报告路径：doc/用户管理/测试报告/代码质量检查/UserService_20250103143025.md
```

### 示例 2：检查整个模块
```
输入：
- 代码路径：src/main/java/com/example/order/
- 业务名称：订单系统
- 测试内容：代码质量检查
- 测试接口名称：OrderModule

输出：
- 报告路径：doc/订单系统/测试报告/代码质量检查/OrderModule_20250103143025.md
```

### 示例 3：完整测试报告样例
```markdown
# P3C 代码质量检查报告

## 基本信息
- 测试时间：2026-03-11 14:30:25
- 测试人员：AI Assistant
- 测试范围：src/main/java/com/bgyfw/parking/
- P3C 版本：《阿里巴巴 Java 开发手册》2022 版

## 问题统计
- 问题总数：15
- 致命问题：2
- 严重问题：5
- 一般问题：6
- 轻微问题：2

## 问题详情

### 致命问题
【问题编号】P3C-001
【严重程度】致命
【规范类别】p3c-security-rules
【规则描述】SQL 注入防护 - 禁止使用字符串拼接 SQL
【代码位置】RefundOrderController.java:45
【问题说明】发现使用字符串拼接 SQL 语句，存在 SQL 注入风险
【修改建议】使用参数化查询或 MyBatis 的#{param} 方式

### 严重问题
【问题编号】P3C-002
【严重程度】严重
【规范类别】p3c-exception-logging
【规则描述】异常处理 - 禁止捕获 Exception 后不做任何处理
【代码位置】RefundOrderServiceImpl.java:78
【问题说明】catch 块中仅打印日志，未进行异常传播或返回错误状态
【修改建议】抛出运行时异常或返回明确的错误响应

### 一般问题
【问题编号】P3C-003
【严重程度】一般
【规范类别】p3c-coding-style
【规则描述】命名风格 - 方法名应使用动词 + 名词形式
【代码位置】RefundOrder.java:23
【问题说明】方法名"status"不够清晰，无法表达是获取状态还是设置状态
【修改建议】修改为 getStatus() 或 setStatus()

### 轻微问题
【问题编号】P3C-004
【严重程度】轻微
【规范类别】p3c-coding-style
【规则描述】注释规约 - 公共方法应有 Javadoc 注释
【代码位置】RefundOrderMapper.java:15
【问题说明】selectById 方法缺少 Javadoc 注释
【修改建议】添加/** */格式的 Javadoc 注释
```

## 常见违规案例

### 案例 1：魔法值
```java
// ❌ 错误示例
if (status == 1) {
    // ...
}

// ✅ 正确示例
public static final int STATUS_ACTIVE = 1;
if (status == STATUS_ACTIVE) {
    // ...
}
```

### 案例 2：NPE 防护
```java
// ❌ 错误示例
String name = user.getName();
if (name.equals("admin")) {
    // ...
}

// ✅ 正确示例
if ("admin".equals(user.getName())) {
    // ...
}
```

### 案例 3：线程池使用
```java
// ❌ 错误示例
ExecutorService executor = Executors.newCachedThreadPool();

// ✅ 正确示例
ExecutorService executor = new ThreadPoolExecutor(
    corePoolSize,
    maximumPoolSize,
    keepAliveTime,
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>(capacity),
    new ThreadFactoryBuilder().setNameFormat("custom-%d").build(),
    new ThreadPoolExecutor.CallerRunsPolicy()
);
```

## 检查规则说明

### 强制规范检查（必须遵守）
以下规范违反将导致**致命**或**严重**问题：

#### 1. 安全规约（致命级别）
- 【P3C-SEC-001】禁止使用字符串拼接 SQL 语句，必须使用参数化查询
- 【P3C-SEC-002】涉及用户敏感数据必须进行脱敏处理
- 【P3C-SEC-003】接口必须进行参数有效性验证，防止恶意输入
- 【P3C-SEC-004】禁止硬编码密码、密钥等敏感信息

#### 2. 异常处理（严重级别）
- 【P3C-EXC-001】禁止捕获 Exception 后不做任何处理（空 catch）
- 【P3C-EXC-002】禁止使用 printStackTrace()，必须使用日志框架
- 【P3C-EXC-003】事务方法中必须进行异常传播，不能吞掉异常
- 【P3C-EXC-004】NPE 防护：使用 equals 时常量在前，或使用 Objects.equals()

#### 3. 并发处理（严重级别）
- 【P3C-CON-001】禁止使用 Executors 创建线程池，必须使用 ThreadPoolExecutor
- 【P3C-CON-002】线程池必须指定拒绝策略
- 【P3C-CON-003】SimpleDateFormat 非线程安全，禁止在多线程环境下直接使用
- 【P3C-CON-004】集合类遍历时禁止直接修改集合结构

#### 4. 数据库规范（严重级别）
- 【P3C-DB-001】表必备字段：id（主键）、gmt_create（创建时间）、gmt_modified（修改时间）
- 【P3C-DB-002】禁止使用物理删除，必须使用逻辑删除
- 【P3C-DB-003】SQL 查询必须使用索引优化，禁止全表扫描
- 【P3C-DB-004】count(*) 用于统计行数，count(列名) 用于统计非 NULL 值

#### 5. 代码风格（严重级别）
- 【P3C-STY-001】类名：UpperCamelCase（DO/BO/DTO/VO 等后缀大写）
- 【P3C-STY-002】方法名、变量名：lowerCamelCase
- 【P3C-STY-003】常量名：UPPER_CASE，用下划线分隔
- 【P3C-STY-004】禁止魔法值，必须定义常量

#### 6. OOP 规范（严重级别）
- 【P3C-OOP-001】覆写 equals 必须同时覆写 hashCode
- 【P3C-OOP-002】包装类比较必须使用 equals，禁止使用==
- 【P3C-OOP-003】类必须有访问控制符，成员变量必须是 private
- 【P3C-OOP-004】POJO 类必须实现 Serializable 接口

#### 7. 单元测试（严重级别）
- 【P3C-TST-001】测试方法必须使用@Test注解
- 【P3C-TST-002】测试类必须遵循*Test命名规范
- 【P3C-TST-003】核心业务逻辑必须有单元测试覆盖

### 推荐规范检查（建议遵守）
以下规范违反将导致**一般**问题：

#### 1. 注释完整性
- 【P3C-CMT-001】公共方法应有 Javadoc 注释
- 【P3C-CMT-002】复杂算法、业务逻辑应有详细注释
- 【P3C-CMT-003】注释语言应与项目一致（中文项目用中文）

#### 2. 代码可读性
- 【P3C-RED-001】方法长度不超过 80 行
- 【P3C-RED-002】单行代码不超过 120 个字符
- 【P3C-RED-003】避免过深的嵌套（不超过 4 层）
- 【P3C-RED-004】使用有意义的命名，避免缩写

#### 3. 性能优化
- 【P3C-PER-001】循环体内禁止创建重复对象
- 【P3C-PER-002】大数据量查询必须分页
- 【P3C-PER-003】优先使用 StringBuilder 进行字符串拼接
- 【P3C-PER-004】及时关闭资源，使用 try-with-resources

#### 4. 代码复用
- 【P3C-RUS-001】重复代码超过 3 处应抽取为公共方法
- 【P3C-RUS-002】工具类应设计为私有构造方法的 final 类
- 【P3C-RUS-003】避免过度设计，遵循 KISS 原则

### 参考规范检查（优化建议）
以下规范违反将导致**轻微**问题：

#### 1. 代码风格
- 【P3C-REF-001】import 顺序应按字母序排列
- 【P3C-REF-002】左大括号前应有空格
- 【P3C-REF-003】操作符两侧应有空格
- 【P3C-REF-004】方法调用结束后空行

#### 2. 最佳实践
- 【P3C-BPR-001】优先使用 JDK 动态代理而非 CGLIB
- 【P3C-BPR-002】使用 Optional 处理可能为 null 的值
- 【P3C-BPR-003】接口设计遵循最少知识原则
- 【P3C-BPR-004】异常类应包含详细的错误信息

#### 3. 优化建议
- 【P3C-OPT-001】考虑使用缓存提升性能
- 【P3C-OPT-002】考虑异步处理耗时操作
- 【P3C-OPT-003】考虑添加监控和告警
- 【P3C-OPT-004】考虑国际化支持

### 参考规范检查
- 代码风格：是否符合团队编码风格
- 最佳实践：是否使用了推荐的最佳实践
- 优化建议：是否有进一步优化的空间

## 排除规则与豁免

### 允许豁免的情况
以下情况可以申请豁免检查：

1. **遗留代码**：历史遗留代码逐步改进，可暂时豁免（需标注 TODO）
2. **特殊需求**：因业务特殊性无法满足规范，需技术负责人审批
3. **第三方依赖**：第三方库的类名、方法名不符合规范
4. **性能考量**：某些场景下为性能牺牲规范（需有充分理由）
5. **兼容性要求**：为保持 API 兼容性而无法修改的命名

### 豁免方式
```java
// 方式 1：使用@SuppressNullWarning 注解（针对 NPE 检查）
@SuppressNullWarning
public String getUserInfo() { ... }

// 方式 2：使用注释标注（针对特定规则）
// CHECKSTYLE:OFF - 遗留代码，待后续重构
public void legacyMethod() { ... }
// CHECKSTYLE:ON

// 方式 3：TODO 标记（针对临时豁免）
// TODO [P3C-EXC-001] 待改进：需要完善异常处理
public void needImprove() { ... }
```

### 渐进式改进策略
对于存量代码，建议采用以下策略：

1. **新增代码零容忍**：所有新增代码必须符合 P3C 规范
2. **核心代码优先**：优先改进核心业务模块的代码
3. **分阶段改进**：制定改进计划，按优先级逐步修复
4. **自动化修复**：使用 IDE 插件自动修复格式问题
5. **Code Review**：将 P3C 检查纳入 Code Review 流程

## 注意事项

1. **报告路径**：确保 doc 目录存在且有写入权限
2. **代码编码**：确保源代码文件使用 UTF-8 编码
3. **依赖解析**：对于复杂的依赖关系，可能需要额外的配置
4. **误报处理**：某些规则可能存在误报，需要人工审核
5. **优先级处理**：优先处理致命和严重问题
6. **性能优化**：
   - 对于大型项目，建议按模块分批检查
   - 支持增量检查，仅检查变更文件
   - 检查超时时间默认设置为 300 秒，可通过参数调整
7. **排除目录**：以下目录默认不检查
   - `target/`、`build/`等构建输出目录
   - `.git/`、`.svn/`等版本控制目录
   - `vendor/`、`lib/`等第三方库目录
   - `generated/`等代码生成目录

## 质量评分标准

- **优秀**：90分以上，无致命和严重问题
- **良好**：80-89分，无致命问题，严重问题不超过3个
- **合格**：70-79分，致命问题不超过1个，严重问题不超过5个
- **需改进**：60-69分，致命问题不超过2个，严重问题不超过10个
- **不合格**：60分以下，存在较多严重问题

## 最佳实践

1. **定期检查**：建议在代码提交前进行 P3C 规范检查
2. **持续集成**：将 P3C 检查集成到 CI/CD 流程中
   ```yaml
   # GitLab CI 示例
   p3c_check:
     stage: test
     script:
       - mvn checkstyle:check
       - mvn spotbugs:check
   ```
3. **问题跟踪**：将检查到的问题录入缺陷管理系统
   - 致命问题：24 小时内修复
   - 严重问题：3 个工作日内修复
   - 一般问题：1 周内修复
   - 轻微问题：迭代优化
4. **团队培训**：定期进行 P3C 规范培训，提高团队代码质量意识
5. **规范更新**：及时更新 P3C 规范版本，保持与最新标准一致
6. **工具集成**：
   - IDE 插件：安装 Alibaba Java Coding Guidelines 插件
   - Maven 插件：使用 p3c-maven-plugin 进行构建时检查
   - SonarQube：集成 P3C 规则集
7. **质量门禁**：
   - 新增代码违规数为 0
   - 存量违规数每周递减 10%
   - 单元测试覆盖率不低于 70%

---

**现在，请提供以下信息开始测试：**
1. 代码路径（文件或目录）
2. 业务名称
3. 测试内容描述
4. 测试接口/模块名称