gRPC-Web代理是前端与Go后端gRPC服务通信的关键桥梁，它将浏览器的HTTP/1.1请求转换为gRPC后端的HTTP/2协议，实现协议转换、CORS处理和双向兼容，确保前端可通过生成的客户端桩安全调用强类型的gRPC服务。

Golang使用gRPC-Web实现前端通信的核心在于，它为浏览器端提供了一种高效、强类型的方式来与后端gRPC服务交互。尽管浏览器本身不直接支持gRPC的HTTP/2协议，gRPC-Web通过引入一个代理层，将浏览器发出的HTTP/1.1请求转换成gRPC后端能理解的HTTP/2格式，从而让前端也能享受到Protocol Buffers带来的类型安全和序列化效率，以及gRPC的服务定义优势。

解决方案

要实现Golang后端与前端通过gRPC-Web通信，这通常涉及几个关键步骤，说实话，第一次搭起来确实需要点耐心，因为涉及多语言的代码生成和代理配置。

首先，你需要定义你的服务接口和消息结构。这通过Protocol Buffers（通常是

.proto

// proto/myservice.proto
syntax = "proto3";

package myservice;

option go_package = "./myservice";

service MyService {
  rpc SayHello (HelloRequest) returns (HelloResponse);
  rpc StreamMessages (StreamRequest) returns (stream StreamResponse); // 示例：服务器流式
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

message StreamRequest {
  string topic = 1;
}

message StreamResponse {
  string content = 1;
  int32 sequence = 2;
}

接下来是代码生成。你需要为Golang后端和前端（通常是JavaScript或TypeScript）生成相应的代码。

立即学习“go语言免费学习笔记（深入）”；

对于Golang，使用

protoc

protoc-gen-go

protoc-gen-go-grpc

protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       proto/myservice.proto

这会生成

myservice.pb.go

myservice_grpc.pb.go

// server/main.go
package main

import (
    "context"
    "fmt"
    "log"
    "net"
    "time"

    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
    "google.golang.org/grpc/status"

    pb "your_module_path/proto" // 替换为你的模块路径
)

type myServiceServer struct {
    pb.UnimplementedMyServiceServer
}

func (s *myServiceServer) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloResponse, error) {
    log.Printf("Received: %v", in.GetName())
    return &pb.HelloResponse{Message: "Hello " + in.GetName()}, nil
}

func (s *myServiceServer) StreamMessages(in *pb.StreamRequest, stream pb.MyService_StreamMessagesServer) error {
    log.Printf("Stream request for topic: %s", in.GetTopic())
    for i := 0; i < 5; i++ {
        if stream.Context().Err() != nil {
            log.Println("Client disconnected during stream.")
            return status.Errorf(codes.Canceled, "Stream cancelled by client")
        }
        msg := fmt.Sprintf("Message %d for topic %s", i+1, in.GetTopic())
        log.Printf("Sending: %s", msg)
        if err := stream.Send(&pb.StreamResponse{Content: msg, Sequence: int32(i + 1)}); err != nil {
            log.Printf("Error sending stream message: %v", err)
            return err
        }
        time.Sleep(time.Second)
    }
    return nil
}

func main() {
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }
    s := grpc.NewServer()
    pb.RegisterMyServiceServer(s, &myServiceServer{})
    log.Printf("server listening at %v", lis.Addr())
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

对于前端，你需要

protoc-gen-grpc-web

# 安装 protoc-gen-grpc-web
npm install -g grpc-web
# 或者 go install github.com/grpc/grpc-web/protoc-gen-grpc-web@latest

# 生成前端代码 (JavaScript/TypeScript)
protoc --js_out=import_style=commonjs,binary:. \
       --grpc-web_out=import_style=typescript,mode=grpcwebtext:. \
       proto/myservice.proto

这里

mode=grpcwebtext

核心的一环是gRPC-Web代理。浏览器无法直接与gRPC（HTTP/2）服务通信，所以需要一个中间代理来转换协议。常见的选择是Envoy代理，或者你也可以用

grpcwebproxy

最后，前端代码会使用生成的客户端桩来调用后端服务：

// frontend/src/App.js (示例，使用React)
import React, { useEffect, useState } from 'react';
import { MyServiceClient } from './proto/MyserviceServiceClientPb'; // 假设生成路径
import { HelloRequest, StreamRequest } from './proto/Myservice_pb'; // 消息定义

const client = new MyServiceClient('http://localhost:8080', null, null); // 8080是代理端口

function App() {
  const [greeting, setGreeting] = useState('');
  const [streamMessages, setStreamMessages] = useState([]);

  useEffect(() => {
    // 调用 SayHello
    const request = new HelloRequest();
    request.setName('World from gRPC-Web');
    client.sayHello(request, {}, (err, response) => {
      if (err) {
        console.error('Error calling SayHello:', err);
        return;
      }
      setGreeting(response.getMessage());
    });

    // 调用 StreamMessages (服务器流式)
    const streamReq = new StreamRequest();
    streamReq.setTopic('updates');
    const stream = client.streamMessages(streamReq, {});
    stream.on('data', (response) => {
      setStreamMessages(prev => [...prev, response.getContent()]);
    });
    stream.on('end', () => {
      console.log('Stream finished.');
    });
    stream.on('error', (err) => {
      console.error('Stream error:', err);
    });

    // 清理流
    return () => {
      stream.cancel();
    };
  }, []);

  return (
    

      
gRPC-Web Demo
      
Greeting: {greeting}
      
Stream Messages:
      

        {streamMessages.map((msg, index) => (
          
{msg}
        ))}
      
    
  );
}

export default App;

这样一套流程下来，你就可以在前端愉快地调用Go后端提供的gRPC服务了。

gRPC-Web代理在整个架构中扮演什么角色？

gRPC-Web代理在整个通信链条中扮演着一个至关重要的“翻译官”角色，它不是可有可无的，而是架构中不可或缺的一环。简单来说，浏览器目前只支持HTTP/1.1协议，而原生的gRPC服务是基于HTTP/2协议构建的。这就导致了一个协议上的鸿沟，浏览器无法直接与gRPC服务对话。

代理的作用就在于弥补这个鸿沟。当浏览器（例如你的React应用）通过

fetch

XMLHttpRequest

此外，代理还经常负责处理CORS（跨域资源共享）问题。因为前端应用通常运行在与gRPC服务不同的域或端口上，没有代理的CORS配置，浏览器会直接拒绝跨域请求。代理可以配置适当的CORS头，允许前端访问后端服务。所以，它不仅仅是协议转换，更是前端与后端gRPC服务之间的一个安全、兼容的桥梁。我个人觉得，理解了代理的这层作用，整个gRPC-Web的架构就清晰多了。

在实际项目中，使用gRPC-Web有哪些常见的“坑”或注意事项？

在实际项目中落地gRPC-Web，确实会遇到一些小“坑”，或者说需要提前注意的地方，避免后期返工。我个人在实践中就踩过一些：

1. CORS配置是常态：这是最常见的问题。前端和gRPC-Web代理（以及代理和后端gRPC服务之间）很可能存在跨域。你需要确保代理正确配置了CORS头，允许前端域的请求。如果你的代理是Envoy，这需要Envoy的CORS过滤器配置；如果是

   grpcwebproxy

   ，它通常有内置的CORS选项。一旦CORS没配好，浏览器控制台就会报错，请求根本发不出去。
   

   Metafox企业内容管理系统0.9.1

   Metafox 是一个企业内容管理系统，使用一个特别的模板系统，你可通过一些特定的设计和代码来轻松创建 Web 网站，内容存储在 SQL 关系数据库，通过 Web 进行管理，简单、快速而且高效。 Metafox 0.9.1 发布，该版本改用一种更棒的 URL 风格，实现了 RSS 源（可包含远端网站内容到 Metafox 段中），重定向老的访问密钥到新的密钥，增加 RotateAntispam 技

   下载

2. 流式传输的限制：gRPC原生支持四种流式传输（单向、客户端流、服务器流、双向流）。但在gRPC-Web的世界里，由于浏览器HTTP/1.1的限制，客户端流和双向流通常是不支持的，或者说实现起来非常复杂，需要一些hacky的解决方案。服务器流式传输是支持的，但它依赖于HTTP/1.1的chunked encoding和trailer headers，这意味着一些旧的代理或网络设备可能会有问题。如果你的业务逻辑强依赖双向流，可能需要考虑WebSocket或其他方案。我记得有次想用客户端流上传大文件，结果发现gRPC-Web默认不支持，最后还是回到了传统的HTTP分块上传。

3. 调试不如REST直观：当你在浏览器开发者工具的网络面板中查看gRPC-Web请求时，你不会看到像RESTful API那样清晰的JSON结构。请求和响应体通常是Base64编码的二进制数据（如果你用的是

   grpcwebtext

   模式），需要手动解码和解析Protobuf才能看懂。这无疑增加了调试的复杂性，需要一些专门的工具或技巧（比如浏览器插件）。

4. Protobuf与JavaScript/TypeScript类型映射：虽然Protobuf提供了强类型，但它到JavaScript/TypeScript的映射可能不如你想象的那么完美，尤其是在处理枚举、

   oneof

   字段或

   Any

   类型时。生成的JS/TS代码可能需要一些适应和封装才能更好地融入你的前端代码风格。比如，

   oneof

   字段在JS中通常表现为一系列

   hasXxx()

   和

   getXxx()

   方法，而不是一个直接的联合类型。

5. 构建流程的复杂度：在项目中引入gRPC-Web，意味着你的构建流程会变得更复杂一点。你需要确保

   protoc

   及其插件（

   protoc-gen-go

   、

   protoc-gen-go-grpc

   、

   protoc-gen-grpc-web

   ）都在正确的位置，并且前端和后端都能在各自的构建阶段正确执行代码生成。自动化这个过程很重要，比如通过Makefile、npm scripts或者CI/CD流水线。

6. 错误处理：gRPC的错误模型（状态码和元数据）在gRPC-Web中会通过HTTP状态码和响应体进行映射。前端需要知道如何解析这些信息来判断错误类型。例如，一个gRPC的

   UNAUTHENTICATED

   错误可能会映射成HTTP 401，但具体的错误信息可能在响应体中。

这些都不是无法克服的问题，但了解它们能让你在项目初期就做好准备，少走弯路。

如何将gRPC-Web与React/Vue等前端框架集成？

将gRPC-Web与React、Vue这类现代前端框架集成，主要围绕着如何方便地在组件中调用生成的客户端代码，并管理请求的生命周期和状态。这个过程的核心在于利用

protoc-gen-grpc-web

首先，确保你的前端项目能够正确地执行

protoc

_pb.js

_grpc_web_pb.js

src/proto

package.json

scripts

prebuild

generate-proto

在React或Vue组件中，你首先需要导入生成的客户端类和消息定义：

// 在你的组件文件顶部
import { MyServiceClient } from './proto/myservice_grpc_web_pb'; // 客户端服务类
import { HelloRequest, StreamRequest } from './proto/myservice_pb'; // 消息请求/响应类

接着，实例化你的gRPC-Web客户端。客户端需要知道你的gRPC-Web代理的地址。通常，这个地址会是一个环境变量或者配置文件中的值：

// 客户端实例化，通常在应用启动时或者一个服务模块中进行
const client = new MyServiceClient('http://localhost:8080', null, null); // 假设代理运行在8080端口

这里的

null, null

现在，你就可以在组件的生命周期方法（React的

useEffect

mounted

对于一元（Unary）RPC调用：

// React示例
useEffect(() => {
  const request = new HelloRequest();
  request.setName('React User');

  client.sayHello(request, {}, (err, response) => {
    if (err) {
      console.error('Error calling SayHello:', err.code, err.message);
      // 根据err.code处理不同类型的错误，例如显示错误消息
      return;
    }
    // 更新组件状态
    setGreeting(response.getMessage());
  });
}, []); // 空依赖数组表示只运行一次

这里

{}

对于服务器流式（Server Streaming）RPC调用：

// React示例
useEffect(() => {
  const streamReq = new StreamRequest();
  streamReq.setTopic('news');
  const stream = client.streamMessages(streamReq, {});

  stream.on('data', (response) => {
    // 每次收到新数据时更新状态
    setStreamMessages(prev => [...prev, response.getContent()]);
  });

  stream.on('end', () => {
    console.log('Stream finished.');
  });

  stream.on('error', (err) => {
    console.error('Stream error:', err.code, err.message);
    // 处理流错误
  });

  // 在组件卸载时取消流，避免内存泄漏
  return () => {
    console.log('Cancelling stream...');
    stream.cancel();
  };
}, []);

流式调用会返回一个可订阅的流对象，你可以监听

data

end

error

stream.cancel()

在实际项目中，我通常会创建一个单独的

api

services

grpc-client.js