前端API设计：gRPC Web实战指南

前端API设计：gRPC Web实战指南

前言

gRPC是Google推出的高性能、开源的远程过程调用（RPC）框架。gRPC Web是gRPC的Web版本，它允许浏览器直接与gRPC服务通信。今天我就来给大家详细介绍gRPC Web的使用方法。

什么是gRPC Web

gRPC Web是一个允许Web客户端直接调用gRPC服务的协议。它基于HTTP/2协议，提供了高效的双向通信能力。

gRPC Web的核心优势

const grpcWebAdvantages = [ '高性能：基于HTTP/2协议', '类型安全：使用Protocol Buffers', '双向流支持', '代码自动生成', '跨语言支持' ];

gRPC Web工作原理

# gRPC Web架构 Web Client ↔ Envoy Proxy ↔ gRPC Server 1. Web客户端发送HTTP/1.1请求 2. Envoy代理将请求转换为HTTP/2 3. 转发到gRPC服务器 4. 服务器响应通过Envoy返回给客户端

gRPC Web实战

1. 定义Protocol Buffers

// user.proto syntax = "proto3"; package user; service UserService { rpc GetUser(GetUserRequest) returns (User) {} rpc GetUsers(GetUsersRequest) returns (stream User) {} rpc CreateUser(CreateUserRequest) returns (User) {} rpc UpdateUser(UpdateUserRequest) returns (User) {} rpc DeleteUser(DeleteUserRequest) returns (Empty) {} } message User { string id = 1; string name = 2; string email = 3; int32 age = 4; } message GetUserRequest { string id = 1; } message GetUsersRequest { int32 page = 1; int32 limit = 2; } message CreateUserRequest { string name = 1; string email = 2; int32 age = 3; } message UpdateUserRequest { string id = 1; optional string name = 2; optional string email = 3; optional int32 age = 4; } message DeleteUserRequest { string id = 1; } message Empty {}

2. 生成代码

# 安装工具 npm install grpc-web protoc # 生成JavaScript代码 protoc \ --proto_path=./proto \ --js_out=import_style=commonjs,binary:./src \ --grpc-web_out=import_style=commonjs,mode=grpcwebtext:./src \ user.proto

3. 配置Envoy代理

# envoy.yaml static_resources: listeners: - name: listener_0 address: socket_address: { address: 0.0.0.0, port_value: 8080 } filter_chains: - filters: - name: envoy.filters.network.http_connection_manager typed_config: "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager codec_type: auto stat_prefix: ingress_http route_config: name: local_route virtual_hosts: - name: local_service domains: ["*"] routes: - match: { prefix: "/" } route: cluster: grpc_backend max_stream_duration: grpc_timeout_header_max: 0s http_filters: - name: envoy.filters.http.grpc_web - name: envoy.filters.http.router clusters: - name: grpc_backend connect_timeout: 0.25s type: logical_dns lb_policy: round_robin load_assignment: cluster_name: grpc_backend endpoints: - lb_endpoints: - endpoint: address: socket_address: address: localhost port_value: 9090

4. 创建gRPC客户端

// grpc-client.js import { UserServiceClient } from './user_grpc_web_pb'; import { GetUserRequest, GetUsersRequest, CreateUserRequest, UpdateUserRequest, DeleteUserRequest } from './user_pb'; const client = new UserServiceClient('http://localhost:8080'); // 获取用户 function getUser(userId) { const request = new GetUserRequest(); request.setId(userId); return new Promise((resolve, reject) => { client.getUser(request, {}, (error, response) => { if (error) { reject(error); } else { resolve(response.toObject()); } }); }); } // 获取用户列表 function getUsers(page, limit) { const request = new GetUsersRequest(); request.setPage(page); request.setLimit(limit); return new Promise((resolve, reject) => { const users = []; const stream = client.getUsers(request); stream.on('data', (user) => { users.push(user.toObject()); }); stream.on('end', () => { resolve(users); }); stream.on('error', (error) => { reject(error); }); }); } // 创建用户 function createUser(user) { const request = new CreateUserRequest(); request.setName(user.name); request.setEmail(user.email); request.setAge(user.age); return new Promise((resolve, reject) => { client.createUser(request, {}, (error, response) => { if (error) { reject(error); } else { resolve(response.toObject()); } }); }); }

5. 在React中使用

import { useState, useEffect } from 'react'; import { getUser, createUser } from './grpc-client'; function UserProfile({ userId }) { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); const [error, setError] = useState(null); useEffect(() => { async function fetchUser() { try { setLoading(true); const userData = await getUser(userId); setUser(userData); setError(null); } catch (err) { setError(err.message); } finally { setLoading(false); } } fetchUser(); }, [userId]); if (loading) return <div>Loading...</div>; if (error) return <div>Error: {error}</div>; return ( <div> <h1>{user.name}</h1> <p>Email: {user.email}</p> <p>Age: {user.age}</p> </div> ); }

gRPC Web高级特性

1. 双向流

// 双向流示例 function chatStream() { const stream = client.chat(); stream.on('data', (message) => { console.log('Received:', message.toObject()); }); stream.on('end', () => { console.log('Stream ended'); }); // 发送消息 const message = new ChatMessage(); message.setContent('Hello'); stream.write(message); // 关闭流 stream.close(); }

2. 错误处理

// 错误处理示例 async function safeGetUser(userId) { try { const user = await getUser(userId); return user; } catch (error) { if (error.code === 5) { console.error('权限不足'); } else if (error.code === 3) { console.error('参数错误'); } else if (error.code === 14) { console.error('服务器不可用'); } throw error; } }

3. 元数据传递

// 设置请求元数据 const metadata = { 'Authorization': 'Bearer token', 'X-Request-Id': 'abc123' }; client.getUser(request, metadata, (error, response) => { // ... });

gRPC Web与REST对比

# gRPC Web vs REST对比 | 特性 | gRPC Web | REST | |------|----------|------| | 协议 | HTTP/2 | HTTP/1.1 | | 数据格式 | Protocol Buffers | JSON | | 性能 | 高 | 一般 | | 类型安全 | 是 | 否 | | 代码生成 | 自动 | 手动 | | 双向流 | 支持 | 有限 | | 学习曲线 | 高 | 低 |

gRPC Web最佳实践

1. 使用Protocol Buffers

# Proto文件组织 proto/ user.proto post.proto common.proto

2. 代码生成脚本

{ "scripts": { "generate": "protoc --proto_path=./proto --js_out=import_style=commonjs,binary:./src --grpc-web_out=import_style=commonjs,mode=grpcwebtext:./src user.proto" } }

3. 错误处理

// 统一错误处理 class GrpcError extends Error { constructor(code, message) { super(message); this.code = code; this.name = 'GrpcError'; } }

总结

gRPC Web提供了一种高性能、类型安全的API调用方式：

1. 高性能：基于HTTP/2协议，支持多路复用
2. 类型安全：使用Protocol Buffers定义接口
3. 代码生成：自动生成客户端代码
4. 双向流：支持实时通信

如果你需要高性能的API调用，gRPC Web是一个很好的选择！

核心要点：

• 定义清晰的Protocol Buffers
• 使用Envoy代理
• 自动生成客户端代码
• 合理处理错误

希望这篇文章能帮助你掌握gRPC Web！