鸿蒙案例网络层对比:同一套 Appwrite 函数,两种封装差在哪
鸿蒙实践中心的 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 里。做到这六条,网络层就不再是接后端时的心病。
- 点赞
- 收藏
- 关注作者
评论(0)