Proto Loader API

Loader 侧 API 参考。构造函数、init() 与 metadata / credentials 辅助函数都挂在同一个 ProtoLoader 实例上、共享同一份状态。大多数用户只调那三个入口（new ProtoLoader、loader.init、loader.initServer / initClients / initReflection），下面的低层 helper 兜底其余情况。

ProtoLoader


import { ProtoLoader } from 'grpcity'
 
const loader = new ProtoLoader(protoFileOptions)

protoFileOptions 说明如下:

Option	Type	Description
single	Object	{ location, files }
array	Object Array	[ { location, files } ]

{ location, files } 说明如下:

Option	Type	Description
location	Path String	必填，如: path.join(__dirname, './proto')
files	Path String Array	必填，如: ['path/to/service-a.proto', 'path/to/service-b.proto']

下面将会展示 loader 里的 API。

init()


await loader.init({ isDev, packagePrefix, loadOptions })

功能说明:

加载 proto 文件，按参数生成 proto 定义。
幂等且并发安全：再次调用（包括首次未完成时的并发调用）会共享同一个进行中的 Promise。initServer、initClients、initReflection 在你没调过的情况下会自动 init()。

参数说明:

Option	Type	Description
isDev	Boolean	可选。开发模式开关，自身无可见效果，用于启用 packagePrefix。默认 false。
packagePrefix	String	可选。仅当 isDev: true 生效。把所有 service/type 重新挂到 <prefix>.<原名>；wire 上的方法路径变成 /<prefix>.<package>.<Service>/...
loadOptions	LoadOptions	可选。原样透传给 @grpc/proto-loader。默认：keepCase: true、longs: String、enums: String、defaults: false、oneofs: true。

返回值:

Promise<void>。

initClients()


const clients = await loader.initClients({ services, channelOptions, credentials })

功能说明:

初始化客户端，绑定 services 里的服务端地址与 proto 定义，并返回 clients 实例。

参数说明:

Option	Type	Description
services	Object	必填，service 和地址
channelOptions	ChannelOptions	可选，proto channel options，默认使用内置 channelOptions
credentials	ChannelCredentials	可选，证书链，使用 `loader.makeCredentials()` 获取

services详细说明：


await loader.initClients({
  services: {
    'test.path.service': '192.168.1.33:5001',
    'dev.path.service': { host: '192.168.1.33', port: 5002 }
  }
})

Option	Type	Description
services.key	String	service name, 包含完整的包名, 如 'test.helloworld.Greeter'
services.value	String	ip/domain + port 格式，如 '192.168.1.33:5001'
services.value	Object	{ host, port } 格式，`host`: 字符串，支持 ip 和域名; `port`: 数字，最小值为0，最大值为65535

返回值:

clients: 包含 clients 一系列的 API。更多相关 API 请查看 Client Side。

makeClientCredentials()


const credentials = loader.makeClientCredentials(rootCerts, privateKey, certChain, verifyOptions)

功能说明:

生成可供客户端使用的证书实例。

参数说明:

Option	Type	Description
rootCerts	Buffer	可选，一般为读 ca 文件
privateKey	Buffer	可选，一般为读 key 文件
certChain	Buffer	可选，一般为读 crt 文件
verifyOptions	Object	可选，{ checkServerIdentity: (hostname, cert) => { } }

返回值:

如果有完整的参数，则返回:grpc.credentials.createSsl()；
如果没有参数，则返回: grpc.credentials.createInsecure()；

initServer()


const server = await loader.initServer(channelOptions)

功能说明:

创建 gRPC server 实例，并提供一系列 server API。

参数说明:

Option	Type	Description
channelOptions	ChannelOptions	可选，proto channel options，默认使用内置 channelOptions
credentials	ServerCredentials	可选，证书链，使用 `loader.makeServerCredentials()` 获取

返回值:

Server: 包含 server 一系列的 API。更多相关 API 请查看 Server Side

makeServerCredentials()


const credentials = server.makeServerCredentials(rootCerts, keyCertPairs, checkClientCertificate)

功能说明:

生成可供服务端使用的证书实例。

参数说明:

Option	Type	Description
rootCerts	Buffer	可选，一般为读 ca 文件
keyCertPairs	Object[]	可选，{ private_key: Buffer, cert_chain: Buffer }，证书对， key 和 crt
checkClientCertificate	Boolean	可选，是否检查客户端证书

返回值:

如果有完整的参数，则返回:grpc.ServerCredentials.createSsl()；
如果没有参数，则返回: grpc.ServerCredentials.createInsecure()；

makeMetadata()


const meta = loader.makeMetadata({ key: value })

功能说明:

创建供客户端使用的的 metadata 实例。参数可为空。

参数说明:

Option	Type	Description
key	String	key 值
value	any / any[]	一般为字符串或字符串数组，非字符串场合会在内部转 Buffer

返回值:

Metadata 实例。

service()


const service = loader.service(name)

功能说明:

获取proto中的service定义。

参数说明:

Option	Type	Description
name	String	必填，指 `proto` 文件路由，具体是到 `service` 的位置

name: ;

返回值:

proto 中的 service 定义。

type()


const type = loader.type(name)

功能说明:

获取proto中的type定义;
能力上包含了service();

参数说明:

Option	Type	Description
name	String	必填，指 `proto` 文件路由，包名到`service`，或到`model`，或到`message`

返回值:

proto 中的 type 定义。