1. 從零搭建 Nestjs gRPC 微服務(wù)為什么你的第一個(gè)服務(wù)總是跑不起來(lái)如果你正在搜「Nestjs 微服務(wù) gRPC 配置」大概率已經(jīng)踩過(guò)這幾個(gè)坑nest new出來(lái)的項(xiàng)目默認(rèn)是 HTTP 應(yīng)用直接加nestjs/microservices后啟動(dòng)報(bào)No transport definedproto 文件路徑寫相對(duì)路徑本地能跑、打包后ENOENTSWC 編譯加速開了之后GrpcMethod裝飾器元數(shù)據(jù)丟失服務(wù)端注冊(cè)不上方法。這些問(wèn)題不是 Nestjs 本身的問(wèn)題而是微服務(wù)項(xiàng)目的初始化順序和配置規(guī)范沒(méi)定好。這篇內(nèi)容聚焦一條完整鏈路從空目錄開始用 pnpm workspace 隔離多個(gè)微服務(wù)用 SWC 做編譯加速用 proto 文件約定服務(wù)間接口最后通過(guò) TaoToken 統(tǒng)一 Key 完成一次端到端的 gRPC 調(diào)用驗(yàn)證。適合已經(jīng)會(huì)寫 Nestjs 控制器、但第一次把單體拆成微服務(wù)的開發(fā)者。整套流程我按「能復(fù)制、能跑通、能排錯(cuò)」的標(biāo)準(zhǔn)寫每一步都給出可粘貼的配置和命令。先說(shuō)結(jié)論性的結(jié)構(gòu)一個(gè) user-service 負(fù)責(zé)用戶注冊(cè)登錄一個(gè) gateway 負(fù)責(zé)對(duì)外 HTTP 并調(diào)用 user-service 的 gRPC 接口。proto 文件獨(dú)立放在/proto目錄兩個(gè)服務(wù)共享同一份接口定義。鑒權(quán)相關(guān)的模型調(diào)用走 TaoToken 的 OpenAI 兼容通道Key 通過(guò)環(huán)境變量注入不硬編碼。下面從項(xiàng)目結(jié)構(gòu)開始。2. TaoToken 前置準(zhǔn)備統(tǒng)一 Key 與 API 通道配置在寫 gRPC 代碼之前先把模型調(diào)用的鑒權(quán)通道準(zhǔn)備好。微服務(wù)里經(jīng)常需要在用戶注冊(cè)時(shí)做一次內(nèi)容合規(guī)檢查或者在登錄時(shí)調(diào)用模型做風(fēng)控判斷這類調(diào)用如果每個(gè)服務(wù)各自維護(hù)一套 Key后期輪換會(huì)非常痛苦。TaoToken 提供的是 OpenAI 兼容的統(tǒng)一入口一個(gè) Key 可以覆蓋多個(gè)模型適合放在微服務(wù)的公共配置層。你需要先拿到 Key。訪問(wèn) API Keys 管理頁(yè)創(chuàng)建https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。創(chuàng)建后復(fù)制sk-開頭的字符串只顯示一次建議直接寫進(jìn).env而不是代碼里。Base URL 統(tǒng)一用https://taotoken.net/api注意這個(gè)地址不帶任何查詢參數(shù)。模型 ID 按你實(shí)際要用的填比如gpt-4o-mini或claude-3-5-sonnet具體可用列表在模型對(duì)話頁(yè)可以查到https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。在 user-service 根目錄建.env# user-service/.env TAOTOKEN_API_KEYsk-你的實(shí)際Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini GRPC_USER_URLlocalhost:4001然后在app.module.ts里用nestjs/config加載確保微服務(wù)啟動(dòng)時(shí)環(huán)境變量已就緒。這里有個(gè)細(xì)節(jié)ConfigModule.forRoot({ isGlobal: true })要放在ClientsModule.register之前否則 gRPC 客戶端注冊(cè)時(shí)讀不到GRPC_USER_URL會(huì)拿到 undefined 然后連接失敗。如果你打算長(zhǎng)期跑多個(gè)微服務(wù)、頻繁調(diào)用模型做 Agent 類任務(wù)可以看下 Coding Plan 的額度方案https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。單次驗(yàn)證用按量 Key 就夠了不用一上來(lái)就上套餐。3. 可復(fù)制配置nest-cli.json、proto 目錄與 gRPC 注冊(cè)代碼這一節(jié)是全文的核心所有配置都可以直接復(fù)制。先建目錄結(jié)構(gòu)mkdir -p nest-grpc-demo/proto cd nest-grpc-demo pnpm initpnpm-workspace.yaml內(nèi)容packages: - user-service - gatewayproto 文件放在根目錄/proto/user.proto兩個(gè)服務(wù)通過(guò)相對(duì)路徑引用。注意 proto 的 package 名和 Nestjs 里GrpcMethod的第一個(gè)參數(shù)必須一致否則報(bào)method not found。// proto/user.proto syntax proto3; package user; service UserService { rpc FindOne (FindOneRequest) returns (FindOneResponse); rpc Create (CreateRequest) returns (CreateResponse); } message FindOneRequest { string username 1; string password 2; } message FindOneResponse { uint32 code 1; string message 2; uint32 id 3; string username 4; string accessToken 5; } message CreateRequest { string username 1; string password 2; } message CreateResponse { uint32 code 1; string message 2; uint32 id 3; string username 4; repeated UserRole userRole 5; } message UserRole { uint32 roleId 1; uint32 userId 2; }user-service 的nest-cli.json啟用 SWC{ $schema: https://json.schemastore.org/nest-cli, collection: nestjs/schematics, sourceRoot: src, compilerOptions: { builder: swc, typeCheck: true, deleteOutDir: true, assets: [ { include: ../proto/**/*.proto, outDir: dist/proto } ] } }assets這段是關(guān)鍵SWC 編譯不會(huì)自動(dòng)拷貝 proto 文件不配的話dist里沒(méi)有 proto運(yùn)行時(shí)報(bào)ENOENT: no such file or directory。outDir設(shè)成dist/proto代碼里用join(__dirname, proto/user.proto)就能找到。main.ts啟動(dòng) gRPC 微服務(wù)// user-service/src/main.ts import { NestFactory } from nestjs/core; import { MicroserviceOptions, Transport } from nestjs/microservices; import { join } from path; import { AppModule } from ./app.module; async function bootstrap() { const app await NestFactory.create(AppModule); app.connectMicroserviceMicroserviceOptions({ transport: Transport.GRPC, options: { url: process.env.GRPC_USER_URL || localhost:4001, package: user, protoPath: join(__dirname, proto/user.proto), loader: { keepCase: true, longs: Number, enums: String, defaults: false, }, }, }); await app.startAllMicroservices(); await app.listen(3000); console.log(user-service gRPC on 4001, HTTP on 3000); } bootstrap();控制器里注冊(cè)方法注意GrpcMethod(UserService, FindOne)兩個(gè)參數(shù)分別是 service 名和方法名和 proto 完全對(duì)應(yīng)// user-service/src/user.controller.ts import { Controller } from nestjs/common; import { GrpcMethod } from nestjs/microservices; Controller() export class UserController { GrpcMethod(UserService, FindOne) findOne(data: { username: string; password: string }) { if (!data.username) { return { code: 10001, message: username required }; } return { code: 0, message: ok, id: 1, username: data.username, accessToken: mock-token- Date.now(), }; } GrpcMethod(UserService, Create) create(data: { username: string; password: string }) { return { code: 0, message: created, id: 2, username: data.username, userRole: [{ roleId: 1, userId: 2 }], }; } }gateway 側(cè)注冊(cè) gRPC 客戶端ClientsModule.register里的name后面注入時(shí)要用// gateway/src/app.module.ts import { Module } from nestjs/common; import { ClientsModule, Transport } from nestjs/microservices; import { ConfigModule } from nestjs/config; import { join } from path; import { GatewayController } from ./gateway.controller; Module({ imports: [ ConfigModule.forRoot({ isGlobal: true }), ClientsModule.register([ { name: USER_PACKAGE, transport: Transport.GRPC, options: { url: process.env.GRPC_USER_URL || localhost:4001, package: user, protoPath: join(__dirname, proto/user.proto), }, }, ]), ], controllers: [GatewayController], }) export class AppModule {}gateway 控制器調(diào)用// gateway/src/gateway.controller.ts import { Controller, Get, Inject, OnModuleInit } from nestjs/common; import { ClientGrpc } from nestjs/microservices; import { Observable } from rxjs; interface UserService { findOne(data: { username: string; password: string }): Observableany; } Controller(user) export class GatewayController implements OnModuleInit { private userService: UserService; constructor(Inject(USER_PACKAGE) private client: ClientGrpc) {} onModuleInit() { this.userService this.client.getServiceUserService(UserService); } Get(find) find() { return this.userService.findOne({ username: test, password: 123 }); } }到這里配置部分結(jié)束。SWC 版本建議鎖swc/core1.6.7新版本在某些 Node 版本下和nestjs/microservices的元數(shù)據(jù)反射有兼容問(wèn)題表現(xiàn)為getService返回 undefined。4. 驗(yàn)證請(qǐng)求grpcurl 與 HTTP 網(wǎng)關(guān)雙通道確認(rèn)成功配置寫完必須驗(yàn)證否則你不知道是 proto 路徑錯(cuò)了還是端口沒(méi)通。分兩步先用 grpcurl 直連 gRPC 端口確認(rèn)服務(wù)端本身正常再通過(guò) gateway 的 HTTP 接口確認(rèn)客戶端注冊(cè)正常。啟動(dòng) user-servicecd user-service pnpm add nestjs/microservices grpc/grpc-js grpc/proto-loader nestjs/config pnpm add -D swc/cli1.6.7 swc/core1.6.7 pnpm start:dev看到user-service gRPC on 4001說(shuō)明微服務(wù)已監(jiān)聽。另開終端用 grpcurl 測(cè)試grpcurl -plaintext -import-path ./proto -proto user.proto \ -d {username:test,password:123} \ localhost:4001 user.UserService/FindOne預(yù)期返回{ code: 0, message: ok, id: 1, username: test, accessToken: mock-token-1720000000000 }如果返回Failed to dial target host檢查 4001 是否被占用返回method not found檢查 proto 里 service 名和GrpcMethod是否一致返回code: 10001說(shuō)明請(qǐng)求體沒(méi)傳進(jìn)去檢查-d的 JSON 字段名和 proto 是否匹配。再啟動(dòng) gatewaycd gateway pnpm start:dev curl http://localhost:3000/user/find返回同樣的 JSON 就說(shuō)明客戶端注冊(cè)成功。這一步能過(guò)說(shuō)明 proto 路徑、package 名、服務(wù)名、方法名四者全部對(duì)齊。如果你在 gateway 里還要調(diào)用 TaoToken 做一次模型校驗(yàn)可以在find方法里加一段const res await fetch(${process.env.TAOTOKEN_BASE_URL}/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${process.env.TAOTOKEN_API_KEY}, }, body: JSON.stringify({ model: process.env.TAOTOKEN_MODEL, messages: [{ role: user, content: ping }], }), });返回 200 且 body 里有choices數(shù)組說(shuō)明統(tǒng)一 Key 通道正常。這一步的報(bào)錯(cuò)排查見下一節(jié)。5. 本篇常見錯(cuò)排查401、local proxy failed 與 reading choices微服務(wù) 模型調(diào)用組合起來(lái)報(bào)錯(cuò)會(huì)集中在幾個(gè)固定位置。下面按真實(shí)報(bào)錯(cuò)對(duì)照處理。401 UnauthorizedTaoToken 返回 401九成是 Key 沒(méi)讀到。檢查.env是否在 gateway 根目錄、ConfigModule.forRoot是否在ClientsModule之前、process.env.TAOTOKEN_API_KEY打印出來(lái)是不是 undefined。注意.env不要提交到 git.gitignore加上。如果 Key 確認(rèn)正確仍 401去 API Keys 頁(yè)確認(rèn)這個(gè) Key 是否被禁用或額度耗盡。local proxy failed / connection refusedgateway 調(diào) user-service 時(shí)報(bào)這個(gè)說(shuō)明 gRPC 客戶端連不上 4001。先lsof -i :4001看端口是否被占用再確認(rèn) user-service 的startAllMicroservices()是否在listen()之前調(diào)用。順序反了會(huì)導(dǎo)致微服務(wù)沒(méi)起來(lái)但 HTTP 端口已監(jiān)聽客戶端連接被拒。Cannot read properties of undefined (reading choices)這是模型返回體解析錯(cuò)誤。常見原因是 Base URL 寫成了https://taotoken.net/api/帶尾斜杠拼接后變成//chat/completions部分網(wǎng)關(guān)會(huì) 404 返回 HTMLres.json()解析后沒(méi)有choices。統(tǒng)一用https://taotoken.net/api不帶尾斜杠。另一個(gè)原因是模型 ID 寫錯(cuò)返回體里是error字段而不是choices打印完整 response 就能看到。OAuth / token expired 類報(bào)錯(cuò)如果你用的是 Claude Code 或 Codex 這類工具接入報(bào) OAuth 相關(guān)錯(cuò)誤通常是本地憑證緩存過(guò)期。這類工具建議直接走 API Key 模式而不是 OAuth配置三件套Base URL 填https://taotoken.net/apiKey 填sk-開頭字符串Model ID 填實(shí)際模型名。三者在同一處配置缺一個(gè)都會(huì)鑒權(quán)失敗。proto 路徑 ENOENT打包后運(yùn)行報(bào)找不到 proto檢查nest-cli.json的assets是否包含../proto/**/*.protooutDir是否和代碼里join(__dirname, ...)的相對(duì)層級(jí)一致。SWC 模式下__dirname指向dist所以 proto 要拷到dist/proto下。字段 ID 重復(fù)導(dǎo)致序列化異常proto 里兩個(gè)字段用了同一個(gè)編號(hào)編譯不報(bào)錯(cuò)但運(yùn)行時(shí)數(shù)據(jù)錯(cuò)亂。用 VS Code 的 protobuf-helper 插件執(zhí)行Reset Field IDs自動(dòng)排序或者手動(dòng)檢查每個(gè) message 內(nèi)編號(hào)唯一。排障時(shí)優(yōu)先看服務(wù)端日志gRPC 的錯(cuò)誤信息比 HTTP 詳細(xì)得多。nestjs/microservices默認(rèn)會(huì)把異常轉(zhuǎn)成 gRPC status codeUNKNOWN通常是控制器拋了未捕獲異常NOT_FOUND是方法沒(méi)注冊(cè)。6. 語(yǔ)義一致 CTA把統(tǒng)一 Key 接進(jìn)你的微服務(wù)鏈路整套流程跑通后你手上有一個(gè)可獨(dú)立運(yùn)行的 user-service、一個(gè) gateway、一份共享 proto以及一條通過(guò) TaoToken 統(tǒng)一 Key 調(diào)模型的通道。后續(xù)擴(kuò)展新服務(wù)時(shí)復(fù)制 user-service 目錄、改 proto 里的 service 名、在 gateway 的ClientsModule.register里加一個(gè)客戶端即可不需要重新設(shè)計(jì)鑒權(quán)層。需要繼續(xù)深入的話接入文檔里有完整的參數(shù)說(shuō)明和錯(cuò)誤碼對(duì)照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。想先在網(wǎng)頁(yè)上驗(yàn)證模型 ID 和返回格式用模型對(duì)話頁(yè)最快https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。如果你的微服務(wù)里要跑長(zhǎng)鏈路的 Agent 任務(wù)Coding Plan 的額度比按量更劃算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。最后留一個(gè)實(shí)操建議proto 文件用 git submodule 或者獨(dú)立 npm 包管理不要讓兩個(gè)服務(wù)各自復(fù)制一份。接口一改兩邊不同步gRPC 報(bào)的錯(cuò)會(huì)非常難定位。我試過(guò)在 gateway 里手動(dòng)改 proto 字段名而 user-service 沒(méi)改結(jié)果客戶端一直超時(shí)查了兩小時(shí)才發(fā)現(xiàn)是字段編號(hào)對(duì)不上。proto 單一來(lái)源是微服務(wù)接口約定里最省事的一條規(guī)則。