dproto 1.0.0

package/CLI.md

@@ -0,0 +1,438 @@
+# dproto CLI 工具
+
+`dproto` 是一个强大的命令行工具，用于管理和编译 Protocol Buffers 定义文件。
+
+## 安装
+
+```bash
+npm install -g dproto
+```
+
+或直接使用：
+
+```bash
+node bin/dproto.js [command]
+```
+
+## 命令概览
+
+```bash
+dproto --help
+```
+
+可用命令：
+- `hello` - 显示欢迎信息
+- `init` - 初始化新的 proto 项目
+- `validate` - 验证 proto 文件语法
+- `check-edit-path` - 检查并添加 Request/Response 的 path 注释
+
+## 配置文件
+
+### dproto.json
+
+`dproto` 使用 `dproto.json` 配置文件来管理项目配置。**配置文件是必需的**，如果没有配置文件，工具会提示先初始化项目。
+
+#### 配置文件结构
+
+```json
+{
+  "apiPrefix": "/api/v1/",
+  "protoDir": "proto"
+}
+```
+
+#### 配置字段说明
+
+| 字段 | 类型 | 必需 | 默认值 | 说明 |
+|-----|------|------|-------|------|
+| `apiPrefix` | string | 否 | `/api/v1/` | API路径前缀 |
+| `protoDir` | string | **是** | `./proto` | Proto文件目录 |
+
+#### 创建配置文件
+
+**方式1: 使用 init 命令（推荐）**
+
+```bash
+dproto init my-project
+cd my-project
+# 配置文件会自动生成
+```
+
+**方式2: 手动创建**
+
+在项目根目录创建 `dproto.json` 文件：
+
+```json
+{
+  "apiPrefix": "/api/v1/",
+  "protoDir": "proto"
+}
+```
+
+#### 配置文件优先级
+
+命令行参数 > 配置文件 > 默认值
+
+```bash
+# 使用配置文件中的 protoDir
+dproto validate
+
+# 使用命令行参数（优先级更高）
+dproto validate --input ./other-proto
+```
+
+#### 配置文件检查
+
+运行命令时，工具会自动检查配置文件：
+
+```
+✅ 已加载配置文件: ./dproto.json
+
+或
+
+❌ 配置文件不存在: ./dproto.json
+
+请先初始化项目:
+  dproto init <项目名称>
+
+或手动创建配置文件 dproto.json
+```
+
+## 命令详解
+
+### 1. hello - 欢迎信息
+
+显示工具基本信息和支持的功能。
+
+```bash
+# 基本用法
+dproto hello
+
+# 自定义名字
+dproto hello --name "Developer"
+```
+
+### 2. init - 初始化项目
+
+创建一个新的 proto 项目，包含模板文件和基础结构。
+
+```bash
+# 创建完整模板项目
+dproto init my-project
+
+# 创建最小模板项目
+dproto init my-project --template minimal
+
+# 指定输出目录
+dproto init my-project --output ./projects
+
+# 强制覆盖现有目录
+dproto init my-project --force
+```
+
+**选项说明：**
+- `<name>` - 项目名称（必填）
+- `-o, --output <path>` - 输出目录（默认：项目名称）
+- `-t, --template <template>` - 模板类型
+  - `minimal` - 最小模板（common.proto + example.proto）
+  - `full` - 完整模板（common.proto + user.proto + example.proto）
+- `-f, --force` - 强制覆盖已存在的目录
+
+**生成的文件：**
+- `proto/` - Proto 定义目录
+- `dproto.json` - **配置文件（必需）**
+- `README.md` - 项目说明文档
+- `package.json` - 项目配置文件
+
+### 3. validate - 验证 Proto 文件
+
+验证 proto 文件的语法和结构，检查常见问题。
+
+```bash
+# 验证默认目录
+dproto validate
+
+# 验证指定目录
+dproto validate --input ./proto
+
+# 显示所有警告（严格模式）
+dproto validate --strict
+```
+
+**选项说明：**
+- `-i, --input <path>` - 输入 proto 目录（默认：`./proto`）
+- `-s, --strict` - 显示所有警告信息
+
+**验证内容：**
+
+1. ✅ 基本语法检查
+   - syntax 声明
+   - package 声明
+   - message/service 定义
+
+2. ✅ 结构检查
+   - import 文件是否存在
+   - 字段编号是否重复
+
+3. ✅ Message 命名冲突检查（跨文件）
+   - 检查所有 proto 文件中的 Message 全限定名（package.MessageName）
+   - 防止同名 Message 在不同文件中冲突
+   - 基于 package 命名空间检测重复
+
+4. ✅ Request/Response 匹配检查（跨文件）
+   - 检查每个 XXXRequest 是否有对应的 XXXResponse
+   - 检查每个 XXXResponse 是否有对应的 XXXRequest
+   - 确保 API 定义完整性（一对一匹配）
+
+5. ✅ 最佳实践检查
+   - go_package 选项
+   - java_package 选项
+   - 命名规范建议
+
+6. ✅ protoc 语法验证（如果已安装）
+   - 使用 protoc 进行完整语法验证
+
+**示例输出：**
+```
+🔍 验证 Proto 文件...
+
+📋 找到 5 个 proto 文件:
+
+✅ Request/Response 匹配成功:
+  找到 15 对匹配的 Request/Response
+
+⚠️  Request/Response 未完整匹配:
+  common.proto:
+    • BaseResponse → 缺少 BaseRequest
+    • PageRequest → 缺少 PageResponse
+
+❌ 发现 Message 命名冲突:
+  user.RegisterRequest 在 2 个文件中定义:
+    • user2.proto (package: user)
+    • user1.proto (package: user)
+
+📝 单文件验证:
+
+✅ verification.proto
+✅ user.proto
+✅ password.proto
+✅ order.proto
+✅ common.proto
+
+🔧 使用 protoc 进行语法验证...
+✅ verification.proto - protoc 验证通过
+
+📊 验证总结:
+✅ 有效文件: 5/5
+⚠️  警告数量: 9
+✨ 所有 Proto 文件验证通过!
+```
+
+### 4. check-edit-path - 检查并添加 Path 注释
+
+检查每个 Request/Response Message 是否有对应的 path 注释,如果没有则自动添加。
+
+```bash
+# 检查默认目录
+dproto check-edit-path
+
+# 检查指定目录
+dproto check-edit-path --input ./proto
+
+# 指定 API 前缀
+dproto check-edit-path --prefix /api/v2/
+```
+
+**选项说明：**
+- `-i, --input <path>` - 输入 proto 目录（默认：`./proto`)
+- `-p, --prefix <prefix>` - API 路径前缀（默认：`/api/v1/`)
+
+**功能说明：**
+
+1. ✅ 自动检测 Request/Response Message
+   - 扫描所有 proto 文件中的 `XXXRequest` 和 `XXXResponse`
+   - 检查每个 Message 定义前是否有 path 注释
+
+2. ✅ 自动计算 Path
+   - 根据 Message 名称自动计算对应的 API Path
+   - 例如: `LoginRequest` → `/api/v1/login`
+   - 例如: `GetUserInfoRequest` → `/api/v1/get/user/info`
+
+3. ✅ 自动添加注释
+   - 在 Message 定义前插入 path 注释
+   - 格式: `// /api/v1/xxx`
+   - 保持原有缩进和文件结构
+
+4. ✅ 智能跳过
+   - 已有正确 path 注释的 Message 会自动跳过
+   - 避免重复添加注释
+
+**示例输出：**
+```
+🔍 检查 Request/Response 的 Path 注释...
+
+API 前缀: /api/v1/
+Proto 目录: ./proto
+
+📋 找到 5 个 proto 文件
+
+📝 user.proto:
+  ✅ 已添加 10 个注释
+    • RegisterRequest → /api/v1/register
+    • RegisterResponse → /api/v1/register
+    • LoginRequest → /api/v1/login
+    • LoginResponse → /api/v1/login
+
+📊 总结:
+✅ 已添加注释: 10
+⏭️  已跳过: 0
+
+✨ Path 注释检查完成!
+```
+
+**生成的注释示例：**
+
+```protobuf
+// 登录请求
+// /api/v1/login
+message LoginRequest {
+  oneof credential {
+    string username = 1;
+    string email = 2;
+    string phone = 3;
+  }
+  string password = 4;
+}
+
+// 登录响应
+// /api/v1/login
+message LoginResponse {
+  common.BaseResponse base = 1;
+  UserInfo user_info = 2;
+  string token = 3;
+}
+```
+
+## 使用流程示例
+
+### 创建新项目
+
+```bash
+# 1. 初始化项目
+dproto init my-api --template full
+
+# 2. 进入项目目录
+cd my-api
+
+# 3. 验证 proto 文件
+dproto validate --strict
+```
+
+### 现有项目验证
+
+```bash
+# 1. 验证现有 proto 文件
+dproto validate --input ./proto
+```
+
+## 配置 package.json
+
+在项目的 `package.json` 中添加脚本：
+
+```json
+{
+  "scripts": {
+    "proto:validate": "dproto validate --input ./proto --strict"
+  }
+}
+```
+
+使用 npm 脚本：
+
+```bash
+npm run proto:validate
+```
+
+## 项目结构示例
+
+```
+my-api/
+├── proto/
+│   ├── common.proto       # 通用定义
+│   ├── user.proto         # 用户模块
+│   ├── verification.proto # 验证码模块
+│   ├── password.proto     # 密码找回模块
+│   └── order.proto        # 订单模块
+│   └── routes.yaml        # 路由配置（可选）
+├── README.md
+└── package.json
+```
+
+## 最佳实践
+
+1. **定期验证** - 在修改 proto 文件后立即验证
+   ```bash
+   dproto validate --strict
+   ```
+
+2. **版本管理** - 将 proto 文件纳入 Git 管理
+
+3. **统一命名** - 遵循 proto3 命名规范
+   - message: PascalCase
+   - field: snake_case
+   - enum: UPPER_SNAKE_CASE
+
+4. **模块化设计** - 每个模块独立 proto 文件
+
+5. **自动化编译** - 使用 CI/CD 自动编译
+
+## 问题排查
+
+### protoc 未安装
+
+```bash
+❌ protoc 未安装
+
+请先安装 protoc 编译器:
+  • macOS: brew install protobuf
+  • Linux: apt-get install protobuf-compiler
+  • Windows: choco install protoc
+```
+
+### 语言插件未安装
+
+```bash
+⚠️  Go 插件未安装
+
+安装命令: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+确保 $GOPATH/bin 已添加到 PATH 环境变量
+```
+
+### 验证失败
+
+```bash
+❌ common.proto
+   • 缺少 syntax 声明
+   • 缺少 package 声明
+
+❌ 请修复上述问题后重新验证
+```
+
+## 版本信息
+
+当前版本: **1.0.0**
+
+支持的语言:
+- Go
+- Java
+- Python
+- PHP
+- NodeJS
+
+## 许可证
+
+MIT License
+
+## 反馈与贡献
+
+如有问题或建议，请提交 Issue 或 Pull Request。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ApiProtobuf Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# ApiProtobuf
+
+> 一套 Api 使用 Protobuf 的思路方案 - 支持 JSON 和 Protobuf 二进制双格式传输
+
+## 🚀 快速开始 - dproto CLI 工具
+
+本项目提供了 `dproto` CLI 工具，用于管理和验证 Proto 文件！
+
+### 安装
+
+```bash
+npm install -g dproto
+```
+
+### 快速使用
+
+```bash
+# 初始化新项目
+dproto init my-api
+
+# 验证 proto 文件
+dproto validate --input ./proto
+```
+
+📚 **完整 CLI 使用指南**: [CLI.md](CLI.md)
+
+---
+
+## 项目简介
+
+这是一个完整的 HTTP API Protobuf 示例项目，展示了如何在传统 HTTP API 中使用 Protocol Buffers 定义数据结构。本项目支持**双格式传输**：
+
+- **JSON 格式** (`application/json`) - 易读易用，兼容传统 HTTP API
+- **Protobuf 二进制格式** (`application/x-protobuf`) - 高效压缩，性能优化
+
+## 目录结构
+
+```
+proto/
+├── common.proto       # 通用定义（状态码、分页、基础响应）
+├── user.proto         # 用户相关（登录、注册、用户信息）
+├── verification.proto # 验证码相关（发送、验证）
+├── password.proto     # 密码找回相关（找回、重置）
+├── order.proto        # 订单相关（创建、查询、管理）
+└── routes.yaml        # 路由配置文件（可选）
+
+output/                # 生成的 JavaScript/TypeScript 文件
+├── protoSplit/        # 多文件方案（推荐大型项目）
+│   ├── user.js        # 178KB - 用户模块
+│   ├── order.js       # 255KB - 订单模块
+│   └── *.d.ts         # TypeScript 类型定义
+├── protoJs/           # 单文件方案（小型项目）
+│   ├── proto.js       # 490KB - CommonJS
+│   └ proto.es6.js     # 490KB - ES6
+├── protoJson/         # JSON 描述文件
+├── protoMin/          # 最小化版本
+└── protoTs/           # TypeScript 类型定义
+
+examples/
+├── go/server.go       # Go语言示例
+├── php/ApiController.php  # Laravel框架示例
+├── java/ApiController.java # Spring Boot框架示例
+├── nodejs/server.js  # Express框架示例
+├── python/server.py   # Flask框架示例
+└── proto-usage.js     # JavaScript Protobuf 使用示例
+└── multi-file-usage.js # 多文件按需加载示例
+```
+
+## Proto 文件的作用
+
+### ⚠️ 重要说明
+
+**在 HTTP JSON API 方案中，Proto 文件的主要作用是：**
+
+1. **定义数据结构** - 定义 Request 和 Response 消息结构
+2. **生成类型定义代码** - 为各语言生成强类型类/结构体
+3. **提供 API 文档参考** - 清晰的数据结构和字段定义
+4. **支持双格式传输** - JSON 和 Protobuf 二进制格式互转
+
+**Proto 文件不用于：**
+- ❌ 定义 HTTP 路由路径（路由在代码或配置文件中定义）
+- ❌ 直接运行 RPC 调用（这是 HTTP API，不是 gRPC）
+- ❌ 自动生成 HTTP 服务端代码
+
+### 路由定义方式
+
+在 HTTP API 方案中，路由通过以下方式定义：
+
+#### 1. YAML 配置文件（可选）
+
+使用 [proto/routes.yaml](proto/routes.yaml) 定义路由映射：
+
+```yaml
+routes:
+  - path: /users/register
+    method: POST
+    request: user.RegisterRequest
+    response: user.RegisterResponse
+```
+
+#### 2. 框架路由注解（推荐）
+
+在代码中直接定义路由（各框架有自己的方式）：
+
+- **Laravel**: `routes/api.php`
+- **Spring Boot**: `@PostMapping("/api/v1/users/register")`
+- **Express**: `app.post('/api/v1/users/register', ...)`
+- **Flask**: `@app.route('/api/v1/users/register', methods=['POST'])`
+
+---
+
+## 📖 详细文档
+
+### JavaScript/TypeScript 生成方案
+
+**解决了大型项目（600 API / 1800 Message）的文件大小问题！**
+
+#### 多文件方案（推荐）
+
+```bash
+# 生成多文件，每个模块独立
+npm run proto:split
+```
+
+**优势**:
+- ✅ 首屏加载减少 70%
+- ✅ 按需动态加载
+- ✅ Webpack/Vite 自动分割
+- ✅ TypeScript 完整类型支持
+
+**使用方式**:
+```javascript
+// React/Vue 懒加载
+const userProto = await import('./output/protoSplit/user.js');
+
+// 只加载需要的模块，减少首屏加载时间
+```
+
+#### 详细指南
+
+- **[前端引导.md](前端引导.md)** - 前端开发者快速入门指南（React/Vue/Angular 示例）
+- **[PROTO-MULTI-FILE-GUIDE.md](PROTO-MULTI-FILE-GUIDE.md)** - 多文件方案技术深度指南
+- **[output/README.md](output/README.md)** - 生成的文件目录说明
+- **[examples/multi-file-usage.js](examples/multi-file-usage.js)** - 多文件使用示例
+
+---
+
+### 其他文档
+
+- **[CLI工具使用指南](CLI.md)** - dproto CLI 工具完整使用说明
+- **[示例项目文档](EXAMPLES.md)** - 详细的功能模块、框架实现示例、客户端调用示例
+- **[路径转换算法](Util.md)** - Message 到路径的自动转换规则
+
+---
+
+## License
+
+MIT
+
+## 联系方式
+
+如有问题或建议，请提交 Issue 或 Pull Request。