gRPC Web
Một phiên bản JavaScript của gRPC cho các trình duyệt web. Để biết thêm thông tin, bao gồm bắt đầu nhanh , hãy xem gRPC-web documentation.
Các máy khách gRPC-web kết nối với các dịch vụ gRPC thông qua một proxy đặc biệt; theo mặc định, gRPC-web sử dụng Envoy.
Trong tương lai, chúng tôi kỳ vọng gRPC-web sẽ được hỗ trợ trong các khung web cụ thể cho các ngôn ngữ như Python, Java và Node. Để biết chi tiết, xem lộ trình.
Hỗ Trợ Luồng
Hiện tại, gRPC-web hỗ trợ 2 chế độ RPC:
- RPC Đơn (ví dụ)
- RPC Luồng Phía Máy Chủ (ví dụ) (CHÚ Ý: Chỉ khi sử dụng chế độ
grpcwebtext.)
Hiện không hỗ trợ luồng phía máy khách và song hướng (xem lộ trình luồng).
Bắt Đầu Nhanh
Muốn bắt đầu ngay? Hãy thử Hello World example. Từ ví dụ này, bạn sẽ tìm hiểu cách thực hiện các công việc sau:
- Xác định dịch vụ của bạn bằng cách sử dụng protocol buffers
- Triển khai một Dịch vụ gRPC đơn giản bằng cách sử dụng NodeJS
- Cấu hình proxy Envoy
- Tạo các lớp thông báo protobuf và dịch vụ khách dành cho máy khách
- Biên dịch tất cả các phụ thuộc JS thành một thư viện tĩnh có thể được trình duyệt tiêu thụ một cách dễ dàng
Bài Mẫu Nâng Cao: Ứng Dụng Echo Trình Duyệt
Bạn cũng có thể thử chạy một ứng dụng Echo nâng cao hơn từ trình duyệt với ví dụ về luồng.
Từ thư mục gốc của kho:
$ docker-compose pull prereqs node-server envoy commonjs-client
$ docker-compose up node-server envoy commonjs-client
Mở một tab trình duyệt và truy cập vào http://localhost:8081/echotest.html.
Để tắt: docker-compose down.
Thư Viện Thời Gian Chạy
Thư viện thời gian chạy gRPC-web có sẵn trên npm:
$ npm i grpc-web
Plugin Sinh Mã Mã Nguồn
Bạn có thể tải xuống plugin protoc-gen-grpc-web từ trang release của chúng tôi:
Nếu bạn chưa cài đặt protoc, bạn phải tải về từ here.
LƯU Ý: Đầu ra Javascript không còn được hỗ trợ bởi gói
protocolbuffers/protobufnhư trước. Vui lòng sử dụng phiên bản từ protocolbuffers/protobuf-javascript thay thế.
Đảm bảo cả hai có thể thực thi và có thể được tìm thấy từ đường dẫn của bạn.
Ví dụ, trên MacOS, bạn có thể thực hiện:
$ sudo mv ~/Downloads/protoc-gen-grpc-web-1.4.2-darwin-x86_64 \
/usr/local/bin/protoc-gen-grpc-web
$ chmod +x /usr/local/bin/protoc-gen-grpc-web
Tùy chọn Cấu hình Client
Thông thường, bạn sẽ chạy lệnh sau để tạo ra các thông điệp proto và đoạn mã dịch vụ từ định nghĩa .proto của bạn:
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:$OUT_DIR \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR
Sau đó, bạn có thể sử dụng Browserify, Webpack, Closure Compiler, vv. để giải quyết việc nhập vào thời gian biên dịch.
Kiểu Nhập khẩu
import_style=closure: Mã được tạo mặc định có kiểu nhập khẩu goog.require().
import_style=commonjs: Cũng hỗ trợ kiểu nhập khẩu require() theo CommonJS.
import_style=commonjs+dts: (Thử nghiệm) Ngoài ra, một tệp .d.ts sẽ được tạo ra cho các thông điệp protobuf và đoạn mã dịch vụ.
import_style=typescript: (Thử nghiệm) Đoạn mã dịch vụ sẽ được tạo ra bằng TypeScript. Xem phần Hỗ trợ TypeScript bên dưới để biết cách tạo tệp TypeScript.
Lưu ý: Các kiểu **commonjs+dts** và **typescript** chỉ được hỗ trợ bởi **--grpc-web_out=import_style=...**, không phải bởi **--js_out=import_style=...**.
Chế độ Định dạng Dây
Để biết thêm thông tin về định dạng dây gRPC-web, xem specification.
mode=grpcwebtext: Mã được tạo mặc định gửi dữ liệu trong định dạng grpc-web-text.
Content-type: application/grpc-web-text- Dữ liệu gửi đi được mã hóa base64.
- Cả cuộc gọi đơn và cuộc gọi phát sóng từ máy chủ được hỗ trợ.
mode=grpcweb: Cũng hỗ trợ định dạng protobuf nhị phân.
Content-type: application/grpc-web+proto- Dữ liệu gửi đi trong định dạng protobuf nhị phân.
- Chỉ hỗ trợ cuộc gọi đơn cho tới thời điểm này.
Cách hoạt động
Hãy xem cách gRPC-web hoạt động qua một ví dụ đơn giản. Bạn có thể tìm hiểu cách xây dựng, chạy và khám phá ví dụ một cách tự thân tại Build and Run the Echo Example.
1. Định nghĩa dịch vụ của bạn
Bước đầu tiên khi tạo bất kỳ dịch vụ gRPC nào là định nghĩa nó. Giống như tất cả các dịch vụ gRPC khác, gRPC-web sử dụng protocol buffers để định nghĩa các phương thức dịch vụ RPC và các loại thông điệp yêu cầu và phản hồi của chúng.
message EchoRequest {
string message = 1;
}
...
service EchoService {
rpc Echo(EchoRequest) returns (EchoResponse);
rpc ServerStreamingEcho(ServerStreamingEchoRequest)
returns (stream ServerStreamingEchoResponse);
}
2. Chạy máy chủ và proxy
Tiếp theo, bạn cần có một máy chủ gRPC thực hiện giao diện dịch vụ và một proxy cổng cho phép máy khách kết nối đến máy chủ. Ví dụ của chúng tôi xây dựng một máy chủ nền tảng Node gRPC đơn giản và proxy Envoy.
Đối với dịch vụ Echo: xem tại service implementations.
Đối với proxy Envoy: xem tại config yaml file.
3. Viết mã máy khách JS của bạn
Khi máy chủ và cổng đã hoạt động, bạn có thể bắt đầu thực hiện cuộc gọi gRPC từ trình duyệt!
Tạo máy khách của bạn:
var echoService = new proto.mypackage.EchoServiceClient(
'http://localhost:8080');
Thực hiện cuộc gọi RPC đơn:
var request = new proto.mypackage.EchoRequest();
request.setMessage(msg);
var metadata = {'custom-header-1': 'value1'};
echoService.echo(request, metadata, function(err, response) {
if (err) {
console.log(err.code);
console.log(err.message);
} else {
console.log(response.getMessage());
}
});
Phát sóng từ phía máy chủ:
var stream = echoService.serverStreamingEcho(streamRequest, metadata);
stream.on('data', function(response) {
console.log(response.getMessage());
});
stream.on('status', function(status) {
console.log(status.code);
console.log(status.details);
console.log(status.metadata);
});
stream.on('end', function(end) {
// stream end signal
});
// to close the stream
stream.cancel()
Để biết thêm về hướng dẫn chi tiết, xem this page.
Đặt Hạn chót
Bạn có thể đặt một hạn chót cho RPC của bạn bằng cách đặt tiêu đề deadline. Giá trị nên là một dấu thời gian Unix, tính bằng mili giây.
var deadline = new Date();
deadline.setSeconds(deadline.getSeconds() + 1);
client.sayHelloAfterDelay(request, {deadline: deadline.getTime().toString()},
(err, response) => {
// err will be populated if the RPC exceeds the deadline
...
});
Hỗ trợ TypeScript
Mô-đun grpc-web hiện có thể được nhập như một mô-đun TypeScript. Đây là một tính năng thử nghiệm hiện tại. Mọi phản hồi đều được hoan nghênh!
Khi sử dụng plugin protoc protoc-gen-grpc-web, như đã đề cập ở trên, truyền vào một trong những tùy chọn sau:
import_style=commonjs+dts: định dạng mẫu CommonJS hiện có + tệp.d.tsimport_style=typescript: đầu ra TypeScript đầy đủ
Không sử dụng import_style=typescript cho --js_out, nó sẽ bị bỏ qua một cách im lặng. Thay vào đó, bạn nên sử dụng --js_out=import_style=commonjs, hoặc --js_out=import_style=commonjs,binary nếu bạn đang sử dụng mode=grpcweb. Plugin --js_out sẽ tạo mã JavaScript (echo_pb.js), và plugin -grpc-web_out sẽ tạo một tệp định nghĩa TypeScript cho nó (echo_pb.d.ts). Đây là một giải pháp tạm thời cho đến khi --js_out tự hỗ trợ TypeScript.
Ví dụ, đây là lệnh bạn nên sử dụng để tạo mã TypeScript bằng định dạng dây nhị phân
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs,binary:$OUT_DIR \
--grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR
Nó sẽ tạo ra các tệp sau:
EchoServiceClientPb.ts– Được tạo bởi--grpc-web_out, chứa mã gRPC-web TypeScript.echo_pb.js– Được tạo bởi--js_out, chứa mã JavaScript Protobuf.-
echo_pb.d.ts– Được tạo bởi--grpc-web_out, chứa định nghĩa TypeScript choecho_pb.js.import * as grpcWeb from ‘grpc-web’;
import {EchoServiceClient} from ‘./EchoServiceClientPb’;
import {EchoRequest, EchoResponse} from ‘./echo_pb’;const echoService = new EchoServiceClient(‘http://localhost:8080’, null, null);
const request = new EchoRequest();
request.setMessage(‘Hello World!’);const call = echoService.echo(request, {‘custom-header-1’: ‘value1’},
(err: grpcWeb.RpcError, response: EchoResponse) => {
console.log(response.getMessage());
});
call.on(‘status’, (status: grpcWeb.Status) => {
// …
});
Đối với ví dụ TypeScript đầy đủ, xem ts-example/client.ts với instructions để chạy.
Hệ sinh thái
Tương tác với Proxy
Nhiều proxy hỗ trợ giao thức gRPC-web.
Proxy mặc định hiện tại là Envoy, hỗ trợ gRPC-web ngay khi cài đặt.
$ docker-compose up -d node-server envoy commonjs-client
Bạn cũng có thể thử gRPC-web Go proxy.
$ docker-compose up -d node-server grpcwebproxy binary-client
Apache APISIX cũng đã thêm hỗ trợ grpc-web, và chi tiết hơn có thể được tìm thấy tại here.
Nginx có một mô-đun grpc-web (doc, announcement)), và dường như hoạt động với các cấu hình đơn giản, theo người dùng feedback.
Các Framework Web hỗ trợ gRPC-Web
Chi tiết Tải về:
Tác giả: grpc
Mã nguồn: https://github.com/grpc/grpc-web
Giấy phép: Apache-2.0 license
