第59篇｜gRPC 客户端库适配 HarmonyOS

第59篇｜gRPC 客户端库适配 HarmonyOS

图 1：gRPC客户端适配封面图，用来概括本文主题、适配对象和工程边界。

gRPC 类库适配要同时看 HTTP2、证书、超时和流式回调，不适合只写一个请求示例。

本文围绕 RPC 请求 和 流式回调 展开，目标不是把库接进工程后截图结束，而是把来源、版本、配置、封装、运行和验收写成一条读者可以复现的链路。

图 2：gRPC客户端适配流程图，用来说明从需求拆解、依赖接入、封装实现到回归验收的主要步骤。

图 3：gRPC客户端适配结构图，用来说明配置层、适配层、服务层、页面层和排错记录之间的职责。

1. 这类库先解决哪个工程问题

gRPC客户端适配不能从 API 名称开始讲，要先说清楚它解决什么工程问题。实际接入时，读者最关心的是库进入项目后由哪一层调用、失败以后看哪里、版本升级时哪些地方需要回归。

本文把问题收敛到 RPC 请求 的输入、流式回调 的执行和 latencyMs 的验收指标。这样写的好处是范围明确，读者不会把选型、封装、页面和发布说明混成一团。

2. 源码和资料定位

适配前先建立源码地图。即使没有真实项目目录，也要把建议位置写清楚，让读者知道每段代码应该放在哪一层。

3. 环境和版本边界

版本边界需要写在正文前半部分。HarmonyOS API、DevEco Studio、ohpm 包版本、Native ABI、设备能力都会影响结果，不能默认读者的环境和作者一致。

4. 配置入口先收口

配置层只负责让依赖进入工程，不要混入业务判断。包管理类库固定版本，Native 类库固定 include、lib 和 ABI，涉及权限的库还要补模块声明。

{
"name": "grpc-client-sample",
"version": "1.0.0",
"dependencies": {
"@demo/grpc-client": "1.0.0"
},
"metadata": {
"verifiedApi": "API 12+",
"entry": "GrpcClientService"
}
}

这段配置的边界是“可追踪”。它让读者知道依赖从哪里来、版本是什么、入口服务是哪一个。真正的业务规则放到服务层，不放在配置里。

5. 适配层负责输入和错误

适配层不要只包一层同名方法。它要处理空输入、格式归一化、错误转换和返回结构。这样页面拿到的结果才稳定。

export interface GrpcClientServiceResult {
ok: boolean;
message: string;
latencyMs: number;
}

export class GrpcClientAdapter {
normalize(raw: string): string {
const value = raw.trim();
if (value.length === 0) {
throw new Error('RPC 请求不能为空');
}
return value;
}

execute(raw: string): GrpcClientServiceResult {
const value = this.normalize(raw);
return {
ok: true,
message: '流式回调完成: ' + value,
latencyMs: value.length
};
}
}

这段代码保护的是业务边界。三方库可以变化，但页面和上层服务只依赖 GrpcClientServiceResult，不会被底层参数结构拖着改。

6. 服务层承接业务语义

服务层要把适配层结果变成业务能直接消费的状态。它可以记录来源、补默认值、控制重试，但不要把页面状态和三方库细节混在一起。

import { GrpcClientAdapter, GrpcClientServiceResult } from '../adapter/GrpcClientAdapter';

export class GrpcClientService {
private adapter = new GrpcClientAdapter();

run(raw: string): GrpcClientServiceResult {
try {
return this.adapter.execute(raw);
} catch (err) {
return {
ok: false,
message: (err as Error).message,
latencyMs: 0
};
}
}
}

服务层的输入来自页面或业务流程，输出用于展示、缓存或提交。后续替换三方库时，只要服务层契约稳定，业务调用方就不用大面积改动。

7. 页面验收入口要可重复

示例页是文章可信度的一部分。读者需要看到输入、按钮、结果和异常信息如何串起来，而不是只看到一段孤立代码。

import { GrpcClientService } from '../service/GrpcClientService';

@Entry
@Component
struct GrpcClientServicePage {
@State input: string = 'grpc-client-input';
@State output: string = '等待运行';
private service = new GrpcClientService();

build() {
Column({ space: 12 }) {
TextInput({ text: this.input, placeholder: '输入RPC 请求' })
.onChange((value: string) => this.input = value)
Button('执行流式回调')
.onClick(() => {
const result = this.service.run(this.input);
this.output = `${result.ok} / ${result.message} / latencyMs=${result.latencyMs}`;
})
Text(this.output).fontSize(14)
}
.padding(20)
}
}

页面验收要覆盖正常输入和空输入。空输入能否被明确提示，能直接反映适配层是否真正承担了边界保护。

8. Native 或底层调用边界

如果库有 Native、SDK 或系统能力调用，需要再单独写一层底层包装。底层包装只负责调用 callUnary、转换结果和释放资源，不承担页面逻辑。

#include <string>

struct NativeResult {
bool ok;
int value;
std::string message;
};

NativeResult RunGrpcClientService(const std::string &input)
{
if (input.empty()) {
return { false, 0, "empty input" };
}
int value = static_cast<int>(input.size());
return { true, value, "callUnary completed" };
}

这段代码的重点是边界清晰。Native 层不直接返回裸指针、不让页面处理错误码、不把资源释放交给调用方猜测。

9. 命令行验证要给读者路径

文章里的命令不需要多，但要能帮读者定位问题。包管理、构建产物、运行日志是三类最常用证据。

ohpm list –all

hvigorw –mode module -p module=entry assembleHap

hdc hilog | findstr grpc_client

执行后建议记录三项结果：依赖版本是否符合预期、HAP 是否能构建、示例页触发时是否有明确日志。这样后续换版本时可以直接对比。

10. 常见问题排查

排查顺序固定为配置、构建、适配层、页面层。这个顺序能避免一开始就改 UI，最后才发现是依赖版本错了。

11. 验收断言

验收断言把“能看见效果”变成“结果满足契约”。下面的断言可以放在 smoke 流程里，也可以在示例页触发后手动核对。

export function assertGrpcClientServiceReady(result: GrpcClientServiceResult): void {
if (!result.ok) {
throw new Error(`gRPC客户端适配执行失败: ${result.message}`);
}
if (result.latencyMs <= 0) {
throw new Error(`latencyMs 不符合预期: ${result.latencyMs}`);
}
}

这段断言的价值在升级时更明显。只要返回结构或关键指标变了，问题会在验收阶段暴露，而不是等到业务页面上线后才发现。

12. 完成前清单

• 依赖来源、版本和许可证已记录。
• 配置入口、适配层、服务层和页面层职责分开。
• 示例页能重复触发 流式回调。
• 空输入、异常输入和正常输入都有明确结果。
• 命令行验证能定位依赖、构建和日志。
• 常见问题表能覆盖读者最可能遇到的失败。
• 图片、图注和结构说明能帮助读者复现。

这份清单建议每次升级库版本后重新执行。尤其是涉及 RPC 请求 和 流式回调 的场景，不能只看构建是否成功，还要确认页面状态、日志输出和错误兜底都保持一致。

13. 小结

gRPC客户端适配的适配重点是把库能力变成项目可维护能力。源码、配置、封装、页面、命令和验收都写清楚，读者才能把文章内容迁移到自己的工程里，而不是只得到一个无法复现的示例。

参考资料

• OpenHarmony 三方库中心仓
• HarmonyOS 开发文档
• HarmonyOS Native 开发与三方库集成 FAQ

参考资料用于核对 API、平台能力和构建链路。正式接入前，应结合当前 SDK、三方库 README、Release 记录和项目权限配置重新确认边界。