@zqlc/ucard-proto

UCard gRPC Proto 文件定义包

简介

这是一个独立的 npm 包，包含了 UCard 项目所有的 gRPC proto 文件定义。通过这个包，服务端和客户端可以共享相同的接口定义。

安装

本地开发（使用 pnpm link）

# 在 proto 包目录
cd /path/to/proto_project
pnpm link --global

# 在服务端项目
cd /path/to/your_project
pnpm link --global @zqlc/ucard-proto

优势: 修改 proto 文件后会实时生效,无需重新安装。适合频繁修改调试。

本地开发（使用 file 关联）

# 在服务端项目中直接引用本地路径
cd /path/to/your_project
pnpm add ../proto_project

# 或者在 package.json 中手动添加
# "dependencies": {
#   "@zqlc/ucard-proto": "file:../proto_project"
# }
# 然后执行 pnpm install

注意: 使用 file: 协议时,每次修改 proto 文件后需要重新执行 pnpm install 来同步更改。适合偶尔修改的场景。

生产环境（发布后）

pnpm add @zqlc/ucard-proto

使用方法

方式一：使用路径对象

const { protoPath } = require('@zqlc/ucard-proto');

// 在 NestJS 中使用
{
  transport: Transport.GRPC,
  options: {
    package: ['auth', 'kyc'],
    protoPath: [protoPath.auth, protoPath.kyc],
    url: '0.0.0.0:50051',
  }
}

方式二：使用所有 proto 文件

const { allProtoFiles, packages } = require('@zqlc/ucard-proto');

// 加载所有 proto 文件
{
  transport: Transport.GRPC,
  options: {
    package: packages,
    protoPath: allProtoFiles,
    url: '0.0.0.0:50051',
  }
}

方式三：使用 proto 目录

const { protoDir } = require('@zqlc/ucard-proto');
const path = require('path');

// 手动指定文件
const protoPath = path.join(protoDir, 'auth.proto');

Proto 文件列表

• auth.proto - 双因素认证服务
• kyc.proto - KYC 验证服务
• email.proto - 邮件验证服务

版本管理

当修改 proto 文件时：

1. 向后兼容的改动（小版本更新）：

   • 添加新的字段（使用新的字段编号）
   • 添加新的 RPC 方法
   • 添加新的 message 类型

2. 破坏性改动（大版本更新）：

   • 删除或重命名字段
   • 更改字段类型
   • 更改字段编号

客户端使用示例

Node.js 客户端

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');
const { protoPath } = require('@zqlc/ucard-proto');

// 加载 proto
const packageDefinition = protoLoader.loadSync(protoPath.auth, {
  keepCase: true,
  longs: String,
  enums: String,
});

const authProto = grpc.loadPackageDefinition(packageDefinition).auth;

// 创建客户端
const client = new authProto.TwoFactorService(
  'localhost:50051',
  grpc.credentials.createInsecure()
);

// 调用方法
client.EnableTwoFactor({ user_id: '123', username: 'test' }, (err, response) => {
  if (err) {
    console.error('Error:', err);
    return;
  }
  console.log('Secret:', response.secret);
});

许可证

MIT