p3c-code-quality（p3c 代码质量）

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

1. 生成测试报告：使用 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规范、注释语言、注释同步更新

1. p3c-exception-logging - 异常与日志规范

- 异常处理：异常捕获原则、异常处理要求、NPE防护 - 日志规约：日志框架、日志保存、日志输出、日志级别

1. p3c-advanced-coding - 高级编程规范

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

1. p3c-mysql-database - MySQL数据库规范

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

1. p3c-oop-standards - OOP编程规范

- 方法覆写：@Override注解、equals方法、包装类比较 - 序列化：serialVersionUID、toString方法 - 访问控制：类成员访问控制、final关键字使用

1. p3c-security-rules - 安全规约

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

1. 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】禁止魔法值，必须定义常量

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 兼容性而无法修改的命名

豁免方式

// 方式 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 秒，可通过参数调整

1. 排除目录：以下目录默认不检查

- 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 流程中

   # GitLab CI 示例
   p3c_check:
     stage: test
     script:
       - mvn checkstyle:check
       - mvn spotbugs:check

1. 问题跟踪：将检查到的问题录入缺陷管理系统

- 致命问题：24 小时内修复 - 严重问题：3 个工作日内修复 - 一般问题：1 周内修复 - 轻微问题：迭代优化

1. 团队培训：定期进行 P3C 规范培训，提高团队代码质量意识
2. 规范更新：及时更新 P3C 规范版本，保持与最新标准一致
3. 工具集成：

- IDE 插件：安装 Alibaba Java Coding Guidelines 插件 - Maven 插件：使用 p3c-maven-plugin 进行构建时检查 - SonarQube：集成 P3C 规则集

1. 质量门禁：

- 新增代码违规数为 0 - 存量违规数每周递减 10% - 单元测试覆盖率不低于 70%

现在，请提供以下信息开始测试：

1. 代码路径（文件或目录）
2. 业务名称
3. 测试内容描述
4. 测试接口/模块名称