ApiProtobuf

一套 Api 使用 Protobuf 的思路方案 - 支持 JSON 和 Protobuf 二进制双格式传输

🚀 快速开始 - dproto CLI 工具

本项目提供了 dproto CLI 工具，用于管理和验证 Proto 文件！

安装

npm install -g dproto

快速使用

# 初始化新项目
dproto init my-api

# 验证 proto 文件
dproto validate --input ./proto

📚 完整 CLI 使用指南: 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 定义路由映射：

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）的文件大小问题！

多文件方案（推荐）

# 生成多文件，每个模块独立
npm run proto:split

优势:

• ✅ 首屏加载减少 70%
• ✅ 按需动态加载
• ✅ Webpack/Vite 自动分割
• ✅ TypeScript 完整类型支持

使用方式:

// React/Vue 懒加载
const userProto = await import('./output/protoSplit/user.js');

// 只加载需要的模块，减少首屏加载时间

详细指南

• 前端引导.md - 前端开发者快速入门指南（React/Vue/Angular 示例）
• PROTO-MULTI-FILE-GUIDE.md - 多文件方案技术深度指南
• output/README.md - 生成的文件目录说明
• examples/multi-file-usage.js - 多文件使用示例

其他文档

• CLI工具使用指南 - dproto CLI 工具完整使用说明
• 示例项目文档 - 详细的功能模块、框架实现示例、客户端调用示例
• 路径转换算法 - Message 到路径的自动转换规则

License

MIT

联系方式

如有问题或建议，请提交 Issue 或 Pull Request。