P3c Code Quality

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 格式的测试报告

子技能说明

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

测试执行流程

步骤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：完整测试报告样例

# 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：魔法值

// ❌ 错误示例
if (status == 1) {
    // ...
}

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

案例 2：NPE 防护

// ❌ 错误示例
String name = user.getName();
if (name.equals("admin")) {
    // ...
}

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

案例 3：线程池使用

// ❌ 错误示例
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】禁止魔法值，必须定义常量