Next.js 15 call gRPC 關鍵紀錄

next.js 15, gRPC, protobuf 3, proto3

§ 引言

試著應用 Next.js 15。向後叫用 gRPC。目標可以部署到雲端。

gRPC 服務端實作用 NET8 必竟這是最熟悉的。此部份過去已實作不在此範圍。 重點在 next.js 如何叫用 gRPC 的開發程序。

§ 關鍵步驟

gRPC 用戶端開發的步驟都是一樣的。

1. 自 gRPC 服務拿取標 proto 檔。

2. 用工具產生 gRPC client。

3. 撰寫用戶端程式碼：設定、連線、通訊。，Ｄ

§ 開發環境

• next.js 15 在後端叫用 gRPC 才能發揮它最大的功效。

§ 安裝套件

// 核心依賴
npm install @grpc/grpc-js @protobuf-ts/grpc-transport @protobuf-ts/runtime @protobuf-ts/runtime-rpc

// 開發工具
npm install -D @protobuf-ts/plugin @protobuf-ts/protoc

套件簡介

以官網為主。這邊只做簡易紀錄。適用於 node/next.js 執行環境的套件經搜尋後如下：

核心套件

• @grpc/grpc-js 官方推薦的通訊套件。

• @protobuf-ts/grpc-transport 高階套件。最終用此套件執行連線。

• @protobuf-ts/runtime與@protobuf-ts/runtime-rpc 基本操作函式庫。

開發工具

• @protobuf-ts/plugin 將提供 CLI 指令 protoc 轉換 .proto 定義檔規格成 .ts TypeScript 定義檔與並生成 client 模組。

• @protobuf-ts/protoc 有安裝 @protobuf-ts/plugin 好像就不需要此套件了？

轉換指令

安裝 @protobuf-ts/plugin 套件後就可使用此 CLI 指令。

> protoc --ts_out src/generated/ --proto_path protos protos/*.proto

此指令也可設定到 package.json 之後可用 npm 叫用，如下：

package.jso

{
  "name": "next15mui7",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbopack --experimental-https",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "proto:generate": "protoc --ts_out src/generated/ --proto_path protos protos/*.proto"
  },
  "dependencies": {
    "@emotion/cache": "^11.14.0",
    "@emotion/react": "^11.14.0",
    "@emotion/styled": "^11.14.0",
    "@fontsource/roboto": "^5.2.6",
    "@grpc/grpc-js": "^1.13.4",
    "@mui/icons-material": "^7.1.2",
    "@mui/material": "^7.1.2",
    "@mui/material-nextjs": "^7.1.1",
    "@protobuf-ts/grpc-transport": "^2.11.1",
    "@protobuf-ts/runtime": "^2.11.1",
    "@protobuf-ts/runtime-rpc": "^2.11.1",
    "date-fns": "^4.1.0",
    "next": "15.3.4",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@eslint/eslintrc": "^3",
    "@protobuf-ts/plugin": "^2.11.1",
    "@protobuf-ts/protoc": "^2.11.1",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "eslint": "^9",
    "eslint-config-next": "15.3.4",
    "typescript": "^5"
  }
}

之後可用 npm 叫用，如下：

> npm run proto:generate   # 轉換 .proto → .ts

§ 本例程式檔部局

一、我們統一把所有 *.proto 檔(此例 greet.proto) 放入 protos 目錄。

二、執行 `npm run proto:generate` 將會更新產生到 generated 目錄中。可以看到有 greet.ts 定義檔與 greet.clent.ts 用戶端模組。還有關聯到的 protobuf 共用的基礎定義檔。

三、為了更容易叫用 gRPC 服務端，主要是統一把連線組態集中。我們仍需再編寫 lib\grpc-greet-client.ts共用函式庫來操作 gRPC。

lib/grpc-greet-client.ts

/**
 * 包裝 gRPC 呼用程序。
 * for greet.proto
 */

import { Empty } from "@/generated/google/protobuf/empty";
import { HelloReply, HelloRequest, WeatherForecast } from "@/generated/greet";
import { GreeterClient } from "@/generated/greet.client";
import { ChannelCredentials } from "@grpc/grpc-js";
import { GrpcTransport } from "@protobuf-ts/grpc-transport";

const transportInsecure = new GrpcTransport({
  host: process.env.GREETER_HOST_INSECURE!, // 替換為你的 gRPC 服務地址
  channelCredentials: ChannelCredentials.createInsecure(), // 未加入安全機制
});

const transport = new GrpcTransport({
  host: process.env.GREETER_HOST!, // 替換為你的 gRPC 服務地址
  channelCredentials: ChannelCredentials.createSsl(), // 使用預設的憑證(但 docker 本身沒有憑證!需額外再配製)
});

console.info('grpc-greet-client', process.env.GREETER_HOST_INSECURE, process.env.GREETER_HOST)

// 創建客戶端實例
//const client = new GreeterClient(transport);
const client = new GreeterClient(transportInsecure); // 無SSL, 用於開發環境測試

export async function sayHelloAsync(request: HelloRequest): Promise<HelloReply> {
  const call = client.sayHello(request);
  const reply = await call.response;
  return reply;
}

export async function getWeatherForecastAsync(): Promise<WeatherForecast> {
  const call = client.getWeatherForecast(Empty);
  const reply = await call.response;
  return reply;
}

最終的應用程式碼如下：

actions.ts

"use server"

import { HelloRequest } from "@/generated/greet";
import * as client from "@/lib/grpc-greet-client";

export async function sayHello(name: string) {
  try {
    const request: HelloRequest = {
      name: name
    };

    const reply = await client.sayHelloAsync(request);
    return reply;
  } catch (error) {
    console.error('sayHello error →', error);
    throw error;
  }
}


export async function getWeatherForecast() {
  try {
    const reply = await client.getWeatherForecastAsync();
    return reply;
  } catch (error) {
    console.error('getWeatherForecast error →', error);
    throw error;
  }
}

(EOF)