pix-class-to-protobuf 技能

📂 基础信息

🎯 核心目标

解决的问题

适用场景

1. •逆向工程：从编译后的 Java 代码恢复 protobuf 协议定义
2. •协议迁移：将现有的 Java protobuf 代码迁移到标准 protobuf 格式
3. •文档生成：从 .class 文件生成协议文档
4. •代码审查：验证 .class 文件中的 protobuf 定义是否正确

🚀 使用方法

激活方式

当用户询问以下类型的问题时，pix-class-to-protobuf 会自动激活：

• •"从 class 文件生成 protobuf"
• •"将 class 转换为 proto"
• •"生成 protobuf 协议文件"
• •"从字节码生成 proto"
• •"反编译 class 文件生成 protobuf"
• •"class 到 protobuf 转换"

预期输出

pix-class-to-protobuf 会提供：

1. •完整的 .proto 文件生成流程
2. •字段信息提取和类型映射
3. •import 语句自动生成
4. •常见问题的解决方案
5. •调试技巧和最佳实践

📚 文档结构

核心文档

脚本文档

示例代码

🛠️ 快速开始

1. 准备工作

# 创建 .class 文件目录结构
mkdir -p protobuf-class-to-proto/classes/com/dnfm/mina/protobuf

# 复制 .class 文件到目标目录
cp -r path/to/classes/*.class protobuf-class-to-proto/classes/com/dnfm/mina/protobuf/

2. 运行脚本

# 生成所有 proto 文件
python generate_proto_from_class.py

# 使用分批调试（推荐用于大量文件）
python generate_proto_from_class_batch.py --batch batch_1.txt

3. 验证结果

# 使用 buf lint 验证 proto 文件
cd proto/generated/batch_1_test
buf lint

# 使用 buf generate 生成 Java 代码
buf generate

🌟 核心功能

1. 字段信息提取

从 Java .class 文件中提取字段信息，包括：

• •字段名称
• •字段类型
• •字段序号
• •是否必需

2. 类型映射

自动将 Java 类型映射到 Protobuf 类型：

• •基本类型：int32, int64, string, bool 等
• •复杂类型：List, Map 等
• •枚举类型：ENUM 类型
• •自定义类型：消息类型

3. import 语句生成

自动收集和生成 import 语句：

• •识别自定义类型
• •生成正确的 import 路径
• •处理依赖关系

4. 特殊字符处理

自动处理 Java 类名中的特殊字符：

• •替换 $ 为 _
• •处理泛型类型
• •确保符合 protobuf 语法规范

📋 分批调试

当需要处理大量 .class 文件时，建议使用分批调试策略：

分批测试策略

1. •第 1 批：选择 10 个简单类型文件，测试基本功能
2. •第 2 批：选择 15 个复杂类型文件，测试 ENUM、repeated、map 类型
3. •第 3 批：选择 20 个有依赖关系的文件，测试 import 语句
4. •第 4 批：选择 30 个文件，测试批量处理性能
5. •第 5 批：生成所有文件，验证完整性

创建批次文件

# 创建批次文件，每行一个 .class 文件名
echo "RES_VERIFICATION_AUTH.class" > batch_1.txt
echo "REQ_VERIFICATION_AUTH.class" >> batch_1.txt

# 清理批次文件，移除注释行
Get-Content test_batch.txt | Where-Object { $_ -notlike '#*' -and $_ -notlike '' } | Set-Content test_batch_clean.txt

🚨 常见问题

Q1: 为什么生成的 proto 文件有语法错误？

原因：类型名包含特殊字符（如 $）、字段名包含特殊字符、重复的字段标签

解决方案：替换特殊字符为 _、检查并跳过重复标签、使用 buf lint 验证生成的 proto 文件

详细解答：参见 docs/04-faq.md

Q2: 为什么某些字段没有被提取？

原因：字段没有 @Protobuf 注解、字段是 private 或 protected、正则表达式没有匹配到字段

解决方案：检查字段是否有 @Protobuf 注解、使用 javap -p -v 查看字段信息、调整正则表达式

详细解答：参见 docs/04-faq.md

Q3: 为什么 import 语句没有生成？

原因：自定义类型没有被正确识别、类型名不满足 import 条件

解决方案：检查类型名是否以大写字母开头、确保类型名不等于当前类名、调试 imported_types 集合

详细解答：参见 docs/04-faq.md

Q4: 为什么 ENUM 类型没有正确处理？

原因：fieldType 为 ENUM，但没有从 Java 类型中提取枚举类型名

解决方案：检查 Java 类型是否包含 ENUM_、从完整类名中提取枚举类型名、替换 $ 为 _

详细解答：参见 docs/04-faq.md

Q5: 为什么 import 文件缺失？

原因：生成的 proto 文件包含 import 语句，但 import 的文件不在当前目录、import 的文件还没有生成

解决方案：创建 common 子目录、将 import 的文件复制到 common 目录中、对于缺失的文件，创建占位符文件

详细解答：参见 docs/04-faq.md

Q6: 为什么枚举类型字段生成错误？

原因：FIELD_TYPE_MAP 中包含了 'ENUM': 'enum'，导致枚举类型被错误映射、生成的字段类型为 enum，但 enum 是 protobuf 的保留关键字

解决方案：从 FIELD_TYPE_MAP 中移除 'ENUM': 'enum'、将 ENUM 类型检查移到 FIELD_TYPE_MAP 检查之前、从 Java 类型中提取枚举类型名

详细解答：参见 docs/04-faq.md

Q7: 为什么文件不存在错误？

原因：批次文件中指定的 .class 文件不存在、文件路径错误或文件被删除

解决方案：检查文件路径是否正确、确保文件存在于指定目录中、从批次文件中移除不存在的文件

详细解答：参见 docs/04-faq.md

Q8: 为什么嵌套类型引用错误？

原因：生成的 proto 文件中引用了其他 proto 文件，但被引用的文件还没有生成、被引用的文件不在当前目录中

解决方案：按照依赖关系顺序生成 proto 文件、将被引用的文件复制到 common 目录中、对于缺失的文件，创建占位符文件

详细解答：参见 docs/04-faq.md

Q9: 为什么批次文件注释处理错误？

原因：批次文件中包含注释行，脚本会将这些注释行当作文件名处理、注释行以 # 开头，被认为是有效的文件名

解决方案：修改批次文件，移除注释行，只保留实际的文件名、或者修改脚本，添加对注释行的支持

详细解答：参见 docs/04-faq.md

Q10: 为什么批量处理性能问题？

原因：处理大量文件时，脚本执行速度较慢、每次处理文件都需要调用 javap 命令，开销较大

解决方案：分批处理文件，避免一次处理太多文件、考虑使用并行处理，提高处理速度、缓存 javap 输出，避免重复执行相同的命令

详细解答：参见 docs/04-faq.md

Q11: 为什么泛型类型提取错误？

原因：Java 类型中包含泛型类型，如 java.util.List<com.dnfm.mina.protobuf.ENUM_IDIP_PROHIBIT_TYPE$T>、脚本在提取泛型类型时，没有正确处理 > 符号、生成的类型名包含 > 符号，导致 protobuf 语法错误

解决方案：修改脚本中的泛型类型提取逻辑，正确处理 > 符号、从 Java 类型中提取泛型类型时，应该移除 > 符号、添加对特殊字符的处理，确保生成的类型名符合 protobuf 语法规范

详细解答：参见 docs/04-faq.md

📚 参考资源

相关文档

• •Protobuf 官方文档
• •Java 字节码规范
• •javap 命令文档

示例代码

• •scripts/generate_proto_from_class.py - 完整的生成脚本
• •scripts/generate_proto_from_class_batch.py - 支持分批调试的生成脚本
• •references/examples/ - 示例 .class 和 .proto 文件

相关技能

• •pix-java-to-protobuf - 从 Java 源文件生成 protobuf
• •pix-skill-creator - 创建 agent skill

🎓 总结

pix-class-to-protobuf 是一个强大的技能，能够从 Java .class 文件自动生成 Protobuf 协议文件。通过使用 javap 解析字节码，提取字段信息和注解，我们可以准确地重建 protobuf 协议定义。

核心优势：

1. •自动化：无需手动编写 protobuf 文件
2. •准确性：直接从字节码提取信息，避免人为错误
3. •完整性：自动生成 import 语句，处理复杂类型
4. •可扩展：支持自定义类型映射和注解解析
5. •可调试性：支持分批调试，快速定位和解决问题

适用场景：

• •逆向工程：从编译后的代码恢复协议定义
• •协议迁移：将现有代码迁移到标准 protobuf 格式
• •文档生成：从 .class 文件生成协议文档
• •代码审查：验证 protobuf 定义是否正确

文档结构：

• •实现细节 - 完整的生成脚本实现和核心流程
• •关键技术点 - 常量池解析、注解处理、类型映射等关键技术
• •最佳实践 - 调试技巧、错误处理、性能优化等最佳实践
• •常见问题 - 常见问题的解决方案和调试技巧
• •脚本使用指南 - 脚本的使用方法、参数说明和示例

现在，你已经准备好使用 pix-class-to-protobuf 技能了！