docs/README_PRECOMPILE.md

# Warp2Api 预编译模式使用指南

## 概述

Warp2Api 现在支持预编译模式，可以避免运行时依赖 grpcio-tools。这种模式通过预先编译 .proto 文件生成描述符集，使服务器在运行时可以直接加载预编译的描述符集，而不需要动态编译 .proto 文件。

## 优势

1. **减少依赖**：不再需要在生产环境中安装 grpcio-tools
2. **加快启动速度**：避免了运行时编译 .proto 文件的时间
3. **更少的内存占用**：不需要加载 grpcio-tools 相关的库
4. **更简单的部署**：减少了依赖项，简化了部署流程

## 使用方法

### 1. 预编译 .proto 文件

首先，需要运行预编译脚本生成描述符集文件：

```bash
# 安装开发依赖（仅在开发环境需要）
pip install -e ".[dev]"

# 运行预编译脚本
python precompile_protos.py
```

这将在 `proto/` 目录下生成 `compiled_descriptors.pb` 文件，这是预编译的描述符集。

### 2. 部署到生产环境

预编译后，您可以将整个项目（包括生成的 `compiled_descriptors.pb` 文件）部署到生产环境。在生产环境中，不需要安装 grpcio-tools，服务器将自动使用预编译的描述符集。

```bash
# 在生产环境中安装（不包含开发依赖）
pip install .

# 启动服务器
python server.py
```

### 3. 更新 .proto 文件

如果您需要更新 .proto 文件，请按照以下步骤操作：

1. 在开发环境中修改 .proto 文件
2. 重新运行预编译脚本生成新的描述符集
3. 将更新后的 .proto 文件和新生成的描述符集一起部署到生产环境

## 故障排除

### 如果预编译的描述符集不可用

如果预编译的描述符集不可用（例如，文件丢失或损坏），服务器将尝试回退到运行时编译模式。如果 grpcio-tools 未安装，将显示以下错误：

```
无法初始化protobuf运行时：grpcio-tools未安装，且预编译的描述符集不可用。
请执行以下操作之一：
1. 安装grpcio-tools: pip install grpcio-tools
2. 运行预编译脚本: python precompile_protos.py
```

### 验证预编译模式是否生效

您可以通过查看服务器启动日志来验证预编译模式是否生效。如果看到以下日志，表示预编译模式已成功启用：

```
尝试加载预编译的描述符集: /path/to/proto/compiled_descriptors.pb
✅ 成功加载预编译的描述符集，包含 XXX 个消息类型
```

## 技术细节

预编译模式的实现主要涉及以下文件：

1. `precompile_protos.py`：预编译脚本，用于生成描述符集
2. `warp2protobuf/core/protobuf.py`：修改后的 protobuf 运行时，优先使用预编译的描述符集
3. `pyproject.toml`：将 grpcio-tools 从必须依赖移到可选依赖

预编译模式的工作流程：

1. 服务器启动时，首先检查是否存在预编译的描述符集
2. 如果存在，直接加载预编译的描述符集
3. 如果不存在或加载失败，尝试运行时编译（需要安装 grpcio-tools）
4. 如果运行时编译也失败，显示错误信息并退出

## 注意事项

- 预编译的描述符集与生成它的 protobuf 版本相关联。如果您更新了 protobuf 库，可能需要重新生成描述符集。
- 确保预编译的描述符集与 .proto 文件保持同步。如果修改了 .proto 文件但没有更新描述符集，可能会导致运行时错误。
- 在开发环境中，建议安装完整的依赖（包括 grpcio-tools），以便在需要时可以动态编译 .proto 文件。