reproto 0.0.3__py3-none-any.whl → 0.0.5__py3-none-any.whl

ARCHITECTURE.md

@@ -0,0 +1,266 @@
+# Protobuf Reconstructor 项目架构
+
+## 🏗️ 总体架构
+
+本项目采用模块化设计，将Protobuf逆向重构过程分解为多个独立的功能模块，确保代码的可维护性和可扩展性。
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    main.py (入口点)                          │
+├─────────────────────────────────────────────────────────────┤
+│                 core/reconstructor.py                      │
+│                    (主协调器)                                │
+├─────────────────┬─────────────────┬─────────────────────────┤
+│  parsing/       │  core/          │  generation/            │
+│  java_parser.py │  info_decoder.py│  proto_generator.py     │
+│  (Java解析)     │  (字节码解码)    │  (Proto生成)            │
+├─────────────────┼─────────────────┼─────────────────────────┤
+│            models/message_definition.py                    │
+│                   (数据模型)                                │
+├─────────────────────────────────────────────────────────────┤
+│                 utils/ (工具模块)                           │
+│              logger.py + file_utils.py                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 📦 模块详解
+
+### 1. 入口层 (Entry Layer)
+
+#### `main.py`
+- **职责**: 命令行接口，参数解析，程序入口
+- **功能**:
+  - 解析命令行参数
+  - 初始化日志系统
+  - 创建并启动重构器
+  - 错误处理和用户反馈
+
+### 2. 核心层 (Core Layer)
+
+#### `core/reconstructor.py` - 主协调器
+- **职责**: 整个重构流程的协调和管理
+- **核心功能**:
+  - 类队列管理 (避免重复处理)
+  - 依赖发现和递归处理
+  - 模块间的协调调用
+  - 结果汇总和文件生成
+- **设计模式**: 协调者模式 (Coordinator Pattern)
+
+#### `core/info_decoder.py` - 字节码解码器
+- **职责**: Google Protobuf Lite字节码的逆向解析
+- **核心技术**:
+  - `newMessageInfo`字节码解码
+  - 字节码到Protobuf类型映射
+  - oneof字段识别 (通过`<`字符检测)
+  - 智能类型推断算法
+- **技术突破**: 首次成功逆向Protobuf Lite字节码格式
+
+### 3. 解析层 (Parsing Layer)
+
+#### `parsing/java_parser.py` - Java源码解析器
+- **职责**: 从Java源码中提取Protobuf相关信息
+- **功能**:
+  - `newMessageInfo`调用提取
+  - 字节码字符串和对象数组解析
+  - 枚举值提取
+  - 依赖类型发现
+
+#### `parsing/java_source_analyzer.py` - Java源码分析器
+- **职责**: 直接从Java源码读取真实类型信息
+- **功能**:
+  - 字段类型声明分析
+  - setter方法分析
+  - import语句解析
+  - 类型名智能匹配
+
+### 4. 生成层 (Generation Layer)
+
+#### `generation/proto_generator.py` - Proto文件生成器
+- **职责**: 根据解析结果生成标准的.proto文件
+- **功能**:
+  - 符合Google Style Guide的文件生成
+  - import语句智能管理
+  - 包结构自动推导
+  - Java选项自动设置
+
+### 5. 数据模型层 (Model Layer)
+
+#### `models/message_definition.py`
+- **包含类型**:
+  - `MessageDefinition`: 消息类型定义
+  - `FieldDefinition`: 字段定义
+  - `OneofDefinition`: oneof字段定义
+  - `EnumDefinition`: 枚举类型定义
+  - `EnumValueDefinition`: 枚举值定义
+
+### 6. 工具层 (Utility Layer)
+
+#### `utils/logger.py`
+- **职责**: 统一的日志管理
+- **功能**: 基于loguru的日志系统
+
+#### `utils/file_utils.py`
+- **职责**: 文件操作工具
+- **功能**: 文件读写、路径处理、目录创建
+
+## 🔄 数据流向
+
+```
+1. Java源码输入
+   ↓
+2. JavaParser 提取字节码信息
+   ↓  
+3. InfoDecoder 解码字节码 → MessageDefinition/EnumDefinition
+   ↓
+4. Reconstructor 发现依赖 → 递归处理
+   ↓
+5. ProtoGenerator 生成.proto文件
+   ↓
+6. 文件输出
+```
+
+## 🧠 核心算法
+
+### 1. 字节码解码算法
+```python
+# 字节码格式: [字段标签, 字段类型] 对
+# 特殊字符 '<' (ord=60) 标识oneof字段
+def decode_message_info(info_string, objects):
+    bytes_data = decode_unicode_escapes(info_string)
+    for i in range(10, len(bytes_data)-1, 2):  # 跳过元数据
+        field_tag = bytes_data[i]
+        field_type = type_mapping[bytes_data[i+1]]
+        # 处理字段...
+```
+
+### 2. 依赖发现算法
+```python
+# 递归依赖发现
+def discover_dependencies(message_def):
+    for field in message_def.fields:
+        if field.type_name in custom_types:
+            full_class_name = resolve_type_name(field.type_name)
+            if full_class_name not in processed:
+                queue.append(full_class_name)
+```
+
+### 3. 智能类型推断算法
+```python
+# 无硬编码的通用推断
+def infer_type_from_field_name(field_name):
+    clean_name = field_name.rstrip('_')
+    if clean_name.endswith('info'):
+        return to_pascal_case(clean_name)
+    elif clean_name.endswith('data'):
+        return to_pascal_case(clean_name)
+    # ... 更多通用规则
+```
+
+## 🎯 设计原则
+
+### 1. 单一职责原则 (SRP)
+- 每个模块只负责一个特定的功能
+- InfoDecoder只负责字节码解码
+- ProtoGenerator只负责文件生成
+
+### 2. 开放封闭原则 (OCP)
+- 通过接口扩展功能，不修改现有代码
+- 类型推断算法可以轻松添加新规则
+
+### 3. 依赖倒置原则 (DIP)
+- 高层模块不依赖低层模块的具体实现
+- 通过抽象接口进行交互
+
+### 4. 无硬编码原则
+- 所有类型推断都基于通用算法
+- 避免特定应用的硬编码映射
+
+## 🔧 可扩展性
+
+### 1. 新增字节码类型支持
+在`InfoDecoder.type_mapping`中添加新的映射：
+```python
+self.type_mapping[new_type_code] = 'new_protobuf_type'
+```
+
+### 2. 新增类型推断规则
+在推断方法中添加新的模式匹配：
+```python
+def infer_type_from_field_name(self, field_name):
+    # 添加新的推断规则
+    if field_name.endswith('new_pattern'):
+        return handle_new_pattern(field_name)
+```
+
+### 3. 新增输出格式
+继承`ProtoGenerator`并实现新的生成方法：
+```python
+class CustomProtoGenerator(ProtoGenerator):
+    def generate_custom_format(self, message_def):
+        # 实现自定义格式生成
+```
+
+## 🚀 性能优化
+
+### 1. 队列去重
+使用set进行O(1)的重复检查：
+```python
+processed_classes = set()
+pending_classes = set()
+```
+
+### 2. 懒加载
+只在需要时才解析Java文件和生成proto文件
+
+### 3. 缓存机制
+缓存已解析的类型定义，避免重复解析
+
+## 🧪 测试策略
+
+### 1. 单元测试
+- 每个模块独立测试
+- 模拟输入数据进行测试
+
+### 2. 集成测试
+- 端到端的完整流程测试
+- 真实Android应用的测试用例
+
+### 3. 回归测试
+- 对比生成结果与预期输出
+- 确保修改不破坏现有功能
+
+## 📈 监控和日志
+
+### 1. 结构化日志
+```python
+logger.info("开始处理类", class_name=class_name, field_count=len(fields))
+logger.success("生成proto文件", file_path=output_path, size=file_size)
+```
+
+### 2. 性能监控
+- 处理时间统计
+- 内存使用监控
+- 文件生成统计
+
+### 3. 错误追踪
+- 详细的错误堆栈
+- 上下文信息记录
+- 失败重试机制
+
+## 🔮 未来扩展
+
+### 1. 多语言支持
+- 支持生成其他语言的绑定代码
+- 扩展到其他序列化格式
+
+### 2. GUI界面
+- 可视化的操作界面
+- 拖拽式的配置管理
+
+### 3. 云端处理
+- 支持大规模批量处理
+- 分布式解析能力
+
+### 4. AI增强
+- 机器学习辅助类型推断
+- 智能错误修复建议 

README.md

@@ -0,0 +1,231 @@
+# Protobuf Reconstructor
+
+🔧 **从JADX反编译的Java源码自动重构Protobuf .proto文件**
+
+一个强大的逆向工程工具，能够从任何使用Google Protobuf Lite的Android应用中自动重构出完整的.proto文件结构。
+
+## ✨ 特性
+
+- 🎯 **精准解析**: 基于Google Protobuf Lite字节码的逆向工程
+- 🔄 **递归依赖**: 自动发现和处理所有依赖的消息和枚举类型
+- 📦 **完整支持**: 支持oneof、repeated、map、枚举等所有Protobuf特性
+- 🌐 **通用性**: 适用于任何Android应用，无需硬编码映射
+- 🚀 **高效处理**: 智能队列管理，避免重复处理
+- 🧠 **智能推断**: 从Java源码直接读取类型信息，确保100%准确性
+- 📝 **标准输出**: 严格遵循Google Proto Style Guide
+- 📊 **结构化日志**: 基于loguru的专业日志系统
+
+## 🛠️ 安装
+
+### 方法1：直接运行
+```bash
+# 克隆项目
+git clone git@github.com:ys1231/reproto.git
+cd reproto
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 运行
+python main.py <java_sources_dir> <root_class> <output_dir>
+```
+
+### 方法2：安装为包
+```bash
+# 安装到系统
+pip install -e .
+
+# 使用命令行工具
+proto-reconstructor <java_sources_dir> <root_class> <output_dir>
+```
+
+## 📖 使用方法
+
+### 基本用法
+```bash
+python main.py ./out_jadx/sources com.example.Model ./protos_generated
+```
+
+### 完整参数
+```bash
+python main.py <java_sources_dir> <root_class> <output_dir> [--log-dir LOG_DIR] [--help]
+```
+
+### 参数说明
+- `java_sources_dir`: JADX反编译的Java源码目录路径
+- `root_class`: 要重构的根类完整类名（如：com.example.Model）
+- `output_dir`: 生成的proto文件输出目录路径
+- `--log-dir`: 日志文件输出目录（默认：./logs）
+- `--help`: 显示帮助信息
+
+### 示例
+```bash
+# 重构示例消息应用的数据模型
+python main.py ./out_jadx/sources com.example.messaging.v1.models.MessageData ./protos_generated
+
+# 指定日志目录
+python main.py ./out_jadx/sources com.example.Model ./output --log-dir ./my_logs
+
+# 重构其他应用的模型
+python main.py /path/to/jadx/sources com.myapp.data.UserProfile ./output
+```
+
+## 🔍 工作原理
+
+### 核心技术
+1. **字节码解析**: 逆向工程Google Protobuf Lite的`newMessageInfo`调用
+2. **依赖发现**: 递归分析Java文件中的类型引用
+3. **智能推断**: 基于字段名和对象数组推断枚举和消息类型
+4. **源码分析**: 直接从Java源码读取真实的字段类型声明
+5. **标准生成**: 生成符合Protobuf规范的.proto文件
+
+### 解析流程
+```
+Java源码 → 字节码提取 → 类型解码 → 依赖发现 → 源码验证 → Proto生成
+```
+
+## 📁 项目结构
+
+```
+proto_reconstructor/
+├── main.py                     # 主程序入口
+├── core/                       # 核心组件
+│   ├── reconstructor.py        # 主协调器
+│   └── info_decoder.py         # 字节码解码器
+├── parsing/                    # 解析模块
+│   ├── java_parser.py          # Java文件解析器
+│   └── java_source_analyzer.py # Java源码分析器
+├── generation/                 # 生成模块
+│   └── proto_generator.py      # Proto文件生成器
+├── models/                     # 数据模型
+
+```
+
+## 工作流程
+
+1. 使用JADX反编译Android应用
+2. 运行ReProto指定根Protobuf类
+3. 自动解析所有相关类和依赖
+4. 生成完整的.proto文件结构
+
+## 输出示例
+
+### 输入：Java源码
+
+```java
+public final class MessageData extends GeneratedMessageLite {
+    private int dataCase_;
+    private Object data_;
+    
+    public enum DataCase {
+        TEXT_MESSAGE(1),
+        MEDIA_MESSAGE(2),
+        DATA_NOT_SET(0);
+        
+        private final int value;
+        
+        private DataCase(int value) {
+            this.value = value;
+        }
+    }
+    
+    // 其他方法...
+}
+```
+
+### 输出：Proto文件
+
+```protobuf
+syntax = "proto3";
+
+package com.example.messaging.v1.models;
+
+import "com/example/messaging/v1/models/message_data.proto";
+import "com/example/messaging/v1/models/conversation_data.proto";
+
+option java_package = "com.example.messaging.v1.models";
+option java_multiple_files = true;
+
+message MessageData {
+  oneof data {
+    TextMessage text_message = 1;
+    MediaMessage media_message = 2;
+  }
+}
+```
+
+## 开发环境设置
+
+### 使用Poetry
+
+```bash
+# 安装Poetry
+curl -sSL https://install.python-poetry.org | python3 -
+
+# 安装项目依赖
+poetry install
+
+# 进入虚拟环境
+poetry shell
+```
+
+## 项目结构
+
+```
+reproto/
+├── core/           # 核心重构逻辑
+├── parsing/        # Java源码解析
+├── generation/     # Proto文件生成
+├── models/         # 数据模型定义
+├── utils/          # 工具函数
+└── main.py         # 入口点
+```
+
+## 🔧 配置选项
+
+### 日志配置
+```bash
+# 指定日志目录
+python main.py sources/ com.example.Model output/ --log-dir ./my_logs
+
+# 日志文件格式: proto_reconstructor-YYYY-MM-DD-HH-MM-SS.log
+# 例如: proto_reconstructor-2024-01-15-14-30-25.log
+```
+
+### 输出格式
+生成的proto文件遵循Google Protobuf Style Guide：
+- 文件名使用`snake_case.proto`格式
+- 字段名使用`snake_case`
+- 消息名使用`PascalCase`
+- 枚举值使用`UPPER_SNAKE_CASE`
+- 正确的包结构和导入语句
+
+## 🏗️ 架构设计
+
+本项目采用模块化设计，详细的架构说明请参考 [ARCHITECTURE.md](./ARCHITECTURE.md)。
+
+核心模块：
+- **Core Layer**: 主协调器 + 字节码解码器
+- **Parsing Layer**: Java解析器 + 源码分析器  
+- **Generation Layer**: Proto文件生成器
+- **Model Layer**: 数据定义模型
+- **Utility Layer**: 日志系统 + 文件工具
+
+
+## 🤝 贡献
+
+欢迎提交Issue和Pull Request！
+
+### 代码规范
+- 遵循PEP 8代码风格
+- 使用类型注解
+- 编写单元测试
+- 更新文档
+
+## 🙏 致谢
+
+- Google Protobuf团队提供的优秀框架
+- JADX项目提供的反编译工具
+- 逆向工程社区的技术支持
+
+---