鸿蒙案例网络层对比:同一套 Appwrite 函数,两种封装差在哪

举报
yd_241537561 发表于 2026/11/19 07:04:47 2026/11/19
【摘要】 word-check-in 和 account_book 两个开源案例都调 Appwrite functions 的 executions 接口:一个是 90 行极简版,一个多出配置解耦、环形日志与冷启动 504 判别。并排读下来,鸿蒙端上网络封装该补哪几块拼图一目了然。

鸿蒙实践中心的 word-check-in(单词打卡)和 account_book(个人记账本)两个案例,后端都选了自托管 Appwrite,端上网络层都走同一条路:POST /v1/functions/<函数ID>/executions。两份 HttpUtil 一份 90 行、一份 110 多行,多出来的部分恰恰是「能跑通的网络层」和「能上生产的网络层」之间的差距。先把共同骨架看了。

一、共同骨架:一律 POST,双层解包,finally 里 destroy

Appwrite 的 executions 接口有个绕不开的形态:无论业务是查还是写,统一 POST;返回 201,外层是 {status, responseBody},真正的业务响应是 responseBody 里再套一层的 JSON 字符串——所以要解两次包:

const resp = await httpRequest.request(url, {
  method: http.RequestMethod.POST,
  header: {
    'Content-Type': 'application/json',
    'X-Appwrite-Project': Config.APPWRITE_PROJECT_ID,   // 无需 API key
  },
  extraData: JSON.stringify({ body: JSON.stringify(dataObj), async: false }),
  connectTimeout: 10000,
  readTimeout: 30000
});
// Appwrite executions 返回 201 Created
const isOk = resp.responseCode === 200 || resp.responseCode === 201;
if (!isOk) {
  return { code: -1, message: 'HTTP ' + resp.responseCode.toString() };
}
let text = resp.result as string;
// 解包外层 {status, responseBody}
const outer = JSON.parse(text) as AppwriteExecution;
if (typeof outer.responseBody === 'string' && outer.responseBody.length > 0) text = outer.responseBody;
const r = JSON.parse(text) as ApiResult;   // 第二层才是 {code, message, data}

业务参数这边也有个统一约定:GET 参数和 POST body 全部合并进一个对象,整体 JSON.stringify 后塞进 {body: ..., async: false} 发出去。端侧不再区分方法语义,函数侧按 body 字段取参。这是函数计算类后端的常见简化,好处是端上只有一个请求模板;代价是丢失了 HTTP 语义,排障时只能靠日志补。

两份代码都把 request.destroy() 放在 finally 里——鸿蒙的 http.createHttp() 每次调用都新建连接对象,不销毁会累积占用,这一步无论封装薄厚都不能省。

二、配置怎么进来:硬编码常量 vs rawfile 惰性加载

word-check-in 的配置是两个空字符串常量,开源仓库里留白让使用者自己填;account_book 走了一层小设计——endpoint 和 projectId 不硬编码,首次请求时从 rawfile 的 app.config.json 同步读取:

let _endpoint: string = '';
let _projectId: string = '';
let _loaded: boolean = false;

function loadFromRawfile(): void {
  const context = getContext() as common.UIAbilityContext;
  const buf: Uint8Array = context.resourceManager.getRawFileContentSync('app.config.json');
  const text: string = util.TextDecoder.create('utf-8').decodeToString(buf);
  const cfg = JSON.parse(text) as AppConfig;
  _endpoint = cfg.endpoint;
  _projectId = cfg.projectId;
  _loaded = true;
}

export class Config {
  static ensureLoaded(): void {
    if (_loaded) return;
    loadFromRawfile();
  }
}

注释里交代了动机:rawfile 里的 json 用占位符入库,开发者填本机真实值后不入库,与后端仓库的 .env 同步。这样开源仓库里没有密钥,本地跑起来又有真配置——「配置文件入库占位、真值本地覆盖」是开源项目处理自托管后端的标准解法。

三、函数 ID 解耦层:端侧路由名不等于云函数名

account_book 还有一层映射:端侧路径末段是 camelCase 的路由键,云函数 ID 是连字符小写,函数改名只改映射,调用方零感知:

// 解耦层:端侧路由键 → Appwrite 云函数 ID;函数改名只改这里,不必动调用方。
static appwriteFnId(key: string): string {
  if (key === 'register') return 'register';
  if (key === 'login') return 'login';
  if (key === 'addTransaction') return 'add-transaction';
  if (key === 'listTransactions') return 'list-transactions';
  if (key === 'deleteTransaction') return 'delete-transaction';
  if (key === 'getStats') return 'get-stats';
  return key;
}

word-check-in 的对应物是两个镜像函数(路径转函数名、函数名转路径),没有独立成配置对象,调用方直接面对映射逻辑。差距不大,但每加一个接口要改两处,漏一处就是运行时「未知路径」。

四、httpLog 环形缓冲:把「网络问题」拆成三种病

account_book 最值得抄的一段:全局环形日志,界面上的调试面板直接读它。作者在注释里写明用途——区分冷启动 504 与配置/网络错误:

export const httpLog: string[] = [];
let seq: number = 0;

function pushLog(line: string): void {
  httpLog.push(`[${seq}] ${line}`);
  seq++;
  if (httpLog.length > 200) httpLog.splice(0, httpLog.length - 200);  // 只留最近 200 条
}

这 200 条日志解决的是真问题:函数计算平台冷启动偶发 504,表现和「endpoint 配错」「设备没网」一模一样,都是「请求失败了」。有逐条日志就能看出:URL 对不对(配置病)、状态码是多少(平台病)、异常长什么样(网络病)。word-check-in 的登录页也挂了日志面板,思路同源但只在登录页生效,出了登录页就瞎了——两相对比,全局环形缓冲是更对的形态。

五、收敛成一份清单

拿这两份代码当参照,鸿蒙端上网络封装的最小完备清单是六条:统一入口(一套 request 模板)、双层解包封进工具层不让业务碰、配置与代码分离且真值不入库、函数 ID 与路由名解耦、环形日志挂全局并在界面上有出口、destroy() 永远在 finally 里。做到这六条,网络层就不再是接后端时的心病。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。