HarmonyOS 开发中请求拦截器链：日志、认证、重试

一、为什么需要拦截器？

假设你正在开发一个需要登录的 App，每个接口都要带 token。你会怎么做，

方案A：每个请求手动加

 // 页面A
http.get;话说回来，// 页面B
http.get;// 页面C...

等到 token 过期要刷新时你发现要改 100 个地方。这时候你想砸键盘了，

方案B：拦截器自动注入

 // 认证拦截器：自动给每个请求加token
class AuthInterceptor {
beforeRequest {
config.headers = `Bearer ${getToken}`;return config;}
}

一次配置，全局生效。这就是拦截器的魅力，

拦截器能做什么？

1. 请求拦截
   • 注入认证 token
   • 添加公共参数
   • 请求日志记录
   • 请求签名/加密
2. 响应拦截
   • 统一错误处理
   • token 过期自动刷新
   • 响应数据转换
   • 响应日志记录
3. 高级能力
   • 请求重试
   • 缓存判断
   • 请求去重
   • Mock 数据注入

二、主要原理：责任链模式

从使用者痛点来看。如果不理解责任链，容易出现执行顺序混乱导致签名不包含 token 或错误处理失效。按理说，

flowchart LR
A --> B
B --> C
C --> D
D --> E
E --> F
F --> G
G --> H
H --> I
J -.-> B
classDef primary fill:#4A90E2,stroke:#2E5C8A,color:#fff
classDef warning fill:#F5A623,stroke:#C17D10,color:#fff
classDef error fill:#E74C3C,stroke:#C0392B,color:#fff
classDef info fill:#7ED321,stroke:#5BA318,color:#fff
class A,E,I primary
class B,C,D info
class F。G error
class H warning

• 执行顺序：

1. 请求拦截器按添加顺序正序执行
2. 发起实际网络请求
3. 响应拦截器按添加顺序逆序执行

三、代码实战：五大主要拦截器

再看示例1，日志拦截器 - 开发调试工具

// network/interceptors/LogInterceptor.ets
import { Interceptor,RequestConfig,Response } from '../types';老实说，/**
* 日志拦截器
* 功能：记录请求和响应的详细信息，方便调试
* 建议：仅在开发环境启用。生产环境关闭
*/
export class LogInterceptor implements Interceptor {
private enableLog:boolean;constructor {
this.enableLog = enableLog;}
/** 请求拦截：记录请求信息 */
async beforeRequest: Promise{
if return config;const timestamp = new Date.toISOString;console.info;console.info;console.info;console.info || 'GET'}`);console.info;if .length){
console.info}`);}
if {
console.info}`);}
if {
console.info}`);}
console.info;按理说，// 在配置中记录开始时间。用于计算耗时
.__startTime = Date.now;return config;}
/** 响应拦截：记录响应信息 */
async afterResponse : Promise{
if return response;const startTime =.__startTime || Date.now;const duration=Date.now-startTime;const timestamp=new Date.toISOString;console.info;console.info;console.info;console.info;说起来，console.info;console.info;if {
console.info;}else{
console.warn;}
console.info;return response;}
}

示例2的观点是。认证择阻击 - Token 自动注入与刷新

// network/interceptors/AuthInterceptor.ets
import { Interceptor,RequestConfig,Response,ApiError,ErrorCode } from '../types';import { preferences } from '@kit.ArkData';话说回来，export class AuthInterceptor implements Interceptor {
private readonly tokenKey:string='auth_token';private readonly refreshTokenKey:string='refresh_token';private isRefreshing:boolean=false;// 防止并发刷新
private readonly refreshSubscribers:Array<=>void>=;// 等待刷新的队列
/** 请求前置 */
async beforeRequest:Promise{
const noAuth=;const needAuth=!noAuth.some);if return config;const token=await this.getToken;if {
config.headers={...,'Authorization':`Bearer ${token}`};}
return config;}
/** 响应后置 */
async afterResponse : Promise{
// 假设后端返回401表示 Token 已过期
if{
const newTok=await this.handleTokenExpired;if{
return this.retryRequest;其实，}else{
this.redirectToLogin;throw new ApiError;}
}
return res;按理说，}
/* 获取存储 Token */
private async getToken:Promise{
try{const p= await preferences.getPreferences;return await p.get as string;}
catch{console.error;return null，}
}
/* 刷新 Token 并同步等待队列 */
private async handleTokenExpired:Promise{
if{return new Promise);}
this.isRefreshing=true;try{
const p=await preferences.getPreferences;const rTok=await p.get as string;ifreturn null;const newTok=await this.callRefreshApi;await p.put，await p.flush;this.refreshSubscribers.forEach);this.refreshSubscribers=;说起来，return newTok;}catch{console.error;return null，}
finally{this.isRefreshing=false;}
}
/* 调用 Refresh 接口，避免循环 interceptors */
private async callRefreshApi:Promise{
const http=require;const req=http.createHttp;try{
const resp=req.request('https://api.myapp.com/v1/auth/refresh',{
至于method。http.RequestMethod.POST,header:{'Content-Type':'application/json'},extraData:{refreshToken:rt}});const r=JSON.parse;return r.data.token;}finally{req.destroy;}
}
/* 重试原始调用 */
private async retryRequest:Promise{
cfg.headers={...,'Authorization':`Bearer ${newT}`};老实说，throw new ApiError;// 抛异常让外层再发起调用，可根据项目实现修改
}
/* 跳转登录页提示 */
private redirectToLogin{
console.warn;}
}

至于示例3。重试 拒绝 网络抖动自动恢复

// network/interceptors/RetryInterceptor.ets
import { Interceptor,RequestConfig,Response,ApiError } from '../types';export class RetryInterceptor implements Interceptor{
private maxRetries:number;老实说，private retryDelay:number;// ms
private retryableStatuses:number;constructor{
this.maxRetries=cfg?.maxRetries，?
5，this.retryDelay=cfg?.retryDelay，?5000，this.retryableStatuses=cfg?.retryableStatuses?，;}
async afterResponse:Promise{
ifreturn res;if)return res;按理说，let cnt=.__retryCount ||0;if{console.warn放弃`);return res，}
.__retryCount=cnt+1;await this.delay);// 指数退避
throw new ApiError(
`网络异常 `。-1,res.status );}
private delay:Promise{return new Promise);}
}

示例4这方面。签名 拒绝 接口安全加固

// network/interceptors/SignatureInterceptor.ets
import { Interceptor,RequestConfig} from '../types';import { cryptoFramework } from '@kit.CryptoArchitectureKit';export class SignatureInterceptor implements Interceptor{
private secretKey:string;private appId:string;constructor{
this.secretKey=cfg.secretKey;this.appId=cfg.appId;}
async beforeRequest:Promise{
const methods=;if.toUpperCase))return cfg;不过，const ts=Date.now.toString;const nonce=this.genNonce;let allParams={...,...,_appId:this.appId。_timestamp:ts,_nonce:nonce};const sign=await this.genSign;cfg.headers={...,'X-App-Id':this.appId。'X-Timestamp':ts,'X-Nonce':nonce,'X-Signature':sign};return cfg，}
private async genSign:Promise{
let keys=Object.keys.sort;let str=keys.map.join;try{
const mac=cryptoFramework.createMac;const keyBlob:{data:any}= {data:new Uint8Array)};const symkey=await cryptoFramework.createSymKey;await mac.init;const dataBlob:{data:any}= {data:new Uint8Array)};await mac.update;let result=).data!，return Array.from.map.padStart).join;}catch{console.error;throw e，}
}
private genNonce:string{
const chars='A娱乐DEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';let s=''，fors+=chars.charAt*chars.length));话说回来，return s;怎么说呢，}
}

示例5的观点是。错误处理 拒绝 -统一异常处理 与 UI 提示

// network/interceptors/ErrorInterceptor.ets
import { Interceptor,Response,ApiError,ErrorCode } from '../types';import { promptAction } from '@kit.ArkUI';export class ErrorInterceptor implements Interceptor{
constructor{}
async afterResponse:Promise{
ifreturn res;const err=this.parseErr;ifthis.showMsg;throw err，}
private parseErr:ApiError{
let msg='网络异常';let code=-1，switch{
case404:{msg:'未找到资源';break，}case401:{msg:'未登录';break，按理说，}
case403:{msg:'无访问权限';break，}case500:{msg:'服务器错误';break，}
};return new ApiError||ErrorCode.SERVER_ERROR。res.status,res.data);}
private showMsg{promptAction.showToast;}
}

四、踩坑与注意事项——常见痛点分析 & 对策

坑1️⃣ 拿错执行顺序导致签名不包含 Token 或错误处理失效

• Pain Point: User frequently encounters “signature invalid” errors because signature interceptor runs before auth interceptor.
• Solve: ;按依赖关系排序：

// ✅ 正确顺序
httpClient.use);// 日志
httpClient.use);// 签名
httpClient.use);// 身份验证
httpClient.use);// 错误处理

坑2️⃣ 并发刷新导致多次无效 Token 刷新尝试 💢 💬 ⚠️ ⚡️ 🚨️🛑️🗑️🧨️⏰️🕰️🌪️🐞👾👹🐶🐱🐵🙈🙉🙊🏴‍☠️🏃‍♂️🏃‍♀️🚂🚀🚁🛰️🤖🧪🔬🔭💻⌨📱💡🌟🎯🥇💎📈📉🎉🔥🔥🔥🔥🔥🔥🔥🔥 🔥🔥 🔥 🔥 🔥 💣 💣 💣 💣 💣 💣 💣 💣 🧨 🧨 🧨 🧨 🧨 🚫 ❌ ❌ ❌ ❌ ❌ ❌ ⛔ ⛔ ⛔ ⛔ ⛔ ⚠ ⚠ ⚠ ⚠ ⚠ ⚠ ⚠︎︎︎︎ ⚑ 🌐 🌐 🌐 🌐 🌐 👀 👀 👀 👀 👀 🎯 🎯 🎯 🎯 🎯 🚩 🚩 🚩 🚩 🚩 🏁 📚 📚 📚 📚 📚 🍺 🍺 🍺 🍺 🍺 🍹 🍹🍹🍹🍹🍹🍭🍭🍭🍭🍭

• 原因 ：多个接口同时检测到 Token 超时都会触发刷新；如果没有同步机制，会造成“刷多次”甚至死循环。

• 解决 ：使用 isRefreshing 标记 + refreshSubscribers 队列；只允许一个刷新操作，其余等待结果再继续。

ts if{ waitForNewToken; } // else startRefresh; 话说回来，

坑3️⃣ 重试 拒绝死循环 – 无限递归或卡死 UI 😵😵😵😵😵😵😵😵 😱😭😭😭😭😭😭😭😭 😤🤬🤬 🤮🤮 🤮 🤮 😴🥱🥱🥱🥱🥱

• 原因 ：一直抛出异常或重新发送。

• 解决 ：设置 maxRetries，并采用指数退避；保证每一次失败都能正确停止。

ts if break;// 延迟时间 = base * pow

坑4️⃣ 异步操作没 await —— 阻塞与报错 🚫❌⚡

• 原因 ：因为 interceptor 的 beforeRequest / afterResponse 返回的是 Promise。但调用方可能忘记 await，导致异步操作被忽略。怎么说呢，

• 解决 ：确保所有 interceptor 调用都是异步等待。

ts for{ config = await inter.beforeRequest;// 正确写法 } // 错误写法： inter.beforeRequest;// 忘记 await，

---

五、HarmonyOS 专属适配要点—API 与细节差异说明

• 加密 API 改变 | 从 @ohos.security.cryptoFramework 到 @kit.CryptoArchitectureKit | 推荐直接引用新版 SDK 并更新代码方法。

​

…话说回来，

​​

  🦃  

- 每次改动都可能影响整个项目；难以追踪哪个模块引入了哪些依赖。‑ 在高并发场景下的 Token 刷新往往出现 race condition。‑ 冗余或忘记注销某些 interceptor 导致安全漏洞。‑ 在生产环境里开启 Log 很容易泄露敏感信息。‑ 一旦 interceptor 顺序搞错，所有业务接口都可能崩溃。

  💡  

- 在发布前一定把 Log 拒绝关掉或通过环境变量控制。‑ 对于关键字段如 Token、签名等，一定不要输出到控制台。‑ 使用可配置化方式，让业务侧可自由决定是否启用某个 interceptor。

---

---