本技能基于阿里巴巴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 内置工具进行代码质量检查，无需额外脚本：

基本测试流程

• 查找 Java 文件：使用 Glob 工具查找所有 .java 文件
• 读取代码内容：使用 Read 工具读取文件内容
• 代码结构分析：使用 SearchCodebase 进行代码结构分析
• 获取编译诊断：使用 GetDiagnostics 获取编译错误和警告
• 正则匹配检查：使用 Grep 工具配合正则表达式匹配 P3C 规范违规
• 调用子技能：调用以下子技能进行详细检查

- p3c-coding-style - p3c-exception-logging - p3c-advanced-coding - p3c-mysql-database - p3c-oop-standards - p3c-security-rules - p3c-unit-testing

• 生成测试报告：使用 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规范对代码进行逐项检查。本技能是聚合技能，会调用以下子技能进行详细检查：

子技能调用

• p3c-coding-style - 代码风格规范

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

• p3c-exception-logging - 异常与日志规范

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

• p3c-advanced-coding - 高级编程规范

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

• p3c-mysql-database - MySQL数据库规范

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

• p3c-oop-standards - OOP编程规范

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

• p3c-security-rules - 安全规约

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

• p3c-unit-testing - 单元测试规范

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

检查方法

使用 Grep 工具配合正则表达式匹配代码中的P3C规范违规：

• 强制规范：必须遵守，违反即视为严重问题
• 推荐规范：建议遵守，违反视为一般问题
• 参考规范：可选择性遵守，违反视为轻微问题

步骤3：问题分类

将检查到的问题按严重程度分类：

• 致命问题：违反强制规范，可能导致严重后果
• 严重问题：违反强制规范，影响代码质量
• 一般问题：违反推荐规范，影响代码可维护性
• 轻微问题：违反参考规范，属于优化建议

步骤4：生成测试报告

使用 Write 工具生成详细的测试报告，包含：

• 测试范围和测试时间
• 问题统计（按严重程度和规范类别）
• 问题详情列表
• 改进建议

输入参数

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

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

测试报告格式

测试报告将生成到以下路径：

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】考虑国际化支持

参考规范检查

• 代码风格：是否符合团队编码风格
• 最佳实践：是否使用了推荐的最佳实践
• 优化建议：是否有进一步优化的空间

排除规则与豁免

允许豁免的情况

以下情况可以申请豁免检查：

• 遗留代码：历史遗留代码逐步改进，可暂时豁免（需标注 TODO）
• 特殊需求：因业务特殊性无法满足规范，需技术负责人审批
• 第三方依赖：第三方库的类名、方法名不符合规范
• 性能考量：某些场景下为性能牺牲规范（需有充分理由）
• 兼容性要求：为保持 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() { ... }

渐进式改进策略

对于存量代码，建议采用以下策略：

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

注意事项

• 报告路径：确保 doc 目录存在且有写入权限
• 代码编码：确保源代码文件使用 UTF-8 编码
• 依赖解析：对于复杂的依赖关系，可能需要额外的配置
• 误报处理：某些规则可能存在误报，需要人工审核
• 优先级处理：优先处理致命和严重问题
• 性能优化：

- 对于大型项目，建议按模块分批检查 - 支持增量检查，仅检查变更文件 - 检查超时时间默认设置为 300 秒，可通过参数调整

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

- target/、build/等构建输出目录 - .git/、.svn/等版本控制目录 - vendor/、lib/等第三方库目录 - generated/等代码生成目录

质量评分标准

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

最佳实践

• 定期检查：建议在代码提交前进行 P3C 规范检查
• 持续集成：将 P3C 检查集成到 CI/CD 流程中

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

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

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

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

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

• 质量门禁：

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

---

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

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