yunkss/ef-tool RCP 模块：ef_rcp
项目地址: https://gitcode.com/yunkss/ef-tool ef_rcp 模块是 eftool 中负责处理 RCP（Remote Communication Protocol）网络请求的核心组件。它提供了一系列功能强大的 API，支持多种网络操作，包括上传、下载、POST、GET、PUT、DELETE 等。通过统一的请求封装、全局配置管理、异常处理、文件操作和安全性配置，ef_rcp 为开发者提供了强大且灵活的 RCP 协议支持。
RCP 协议的核心功能
ef_rcp 模块是 eftool 中负责处理 RCP（Remote Communication Protocol）网络请求的核心组件。它提供了一系列功能强大的 API，支持多种网络操作，包括上传、下载、POST、GET、PUT、DELETE 等。以下是 RCP 协议的核心功能详解：
1. 请求与响应封装
ef_rcp 通过 efRcpClientApi 提供了统一的请求封装，支持以下操作：
- POST：发送数据到服务器。
- GET：从服务器获取数据。
- PUT：更新服务器上的数据。
- DELETE：删除服务器上的数据。
- Cancel：取消正在进行的请求。
代码示例
import { efRcpClientApi } from '@yunkss/ef_rcp';
// POST 请求示例
efRcpClientApi.post({
url: '/api/data',
query: { key: 'value' },
}).then((response) => {
console.log(response.data);
}).catch((error) => {
console.error(error);
});
2. 全局配置管理
通过 efRcpConfig，可以全局配置 RCP 请求的行为，包括超时设置、加解密、会话管理等。
配置项
| 配置项 | 描述 |
|---|---|
timeout | 设置连接和传输的超时时间。 |
cryptoEvent | 提供请求拦截的加解密功能。 |
sessionListener | 监听会话的关闭和取消事件。 |
loading | 全局加载动画的配置，支持自定义内容和动画类型。 |
代码示例
import { efRcpConfig } from '@yunkss/ef_rcp';
// 设置超时时间
efRcpConfig.timeout = {
connectMs: 5000,
transferMs: 10000,
};
// 启用全局加载动画
efRcpConfig.loading.enable = true;
efRcpConfig.loading.content = '加载中...';
3. 异常处理
EfRcpError 是统一的异常处理对象，内置 toString 方法，方便开发者快速定位问题。
代码示例
try {
await efRcpClientApi.get({ url: '/api/data' });
} catch (error) {
if (error instanceof EfRcpError) {
console.error(error.toString());
}
}
4. 文件上传与下载
ef_rcp 支持文件的上传和下载，并提供了进度监听功能。
上传示例
efRcpClientApi.upload({
url: '/api/upload',
fileInfo: { file: 'path/to/file' },
onUploadProgress: (progress) => {
console.log(`上传进度: ${progress}%`);
},
});
下载示例
efRcpClientApi.download({
url: '/api/download',
onDownloadProgress: (progress) => {
console.log(`下载进度: ${progress}%`);
},
});
5. 安全性配置
通过 securityCfg，可以配置证书和安全连接，确保数据传输的安全性。
代码示例
efRcpConfig.securityCfg = {
remoteValidation: 'system',
certificate: {
path: 'path/to/cert.pem',
},
};
6. 状态码处理
ef_rcp 支持系统级别和业务级别的状态码处理，开发者可以通过 codeEvent 自定义处理逻辑。
代码示例
efRcpConfig.codeEvent = {
businessCodeName: 'errorCode',
listener: (sysCode, busCode) => {
if (busCode === 404) {
console.error('资源未找到');
}
},
};
7. 流程图
以下是 RCP 请求的流程图：
8. 表格总结
| 功能 | 描述 |
|---|---|
| 请求封装 | 支持多种 HTTP 方法，统一异常处理。 |
| 全局配置 | 提供超时、加解密、会话管理等配置项。 |
| 文件操作 | 支持文件上传和下载，带进度监听。 |
| 安全性 | 支持证书配置和安全连接。 |
| 状态码处理 | 支持系统级别和业务级别的状态码自定义处理。 |
通过以上功能，ef_rcp 为开发者提供了强大且灵活的 RCP 协议支持，能够满足复杂的网络通信需求。
拦截器链的设计（如 EfCryptoInterceptor）
在 ef_rcp 模块中，拦截器链的设计是实现请求和响应处理的核心机制之一。通过拦截器链，开发者可以在请求发送前或响应返回后对数据进行统一的处理，例如加密、解密、日志记录等。EfCryptoInterceptor 是其中一个典型的拦截器实现，专门用于请求和响应的加解密操作。
拦截器的作用
拦截器在 ef_rcp 中扮演着重要角色，其主要功能包括：
- 请求拦截：在请求发送前对数据进行预处理，例如加密请求参数。
- 响应拦截：在响应返回后对数据进行后处理，例如解密响应数据。
- 统一处理：确保所有请求和响应都经过相同的逻辑处理，避免重复代码。
EfCryptoInterceptor 的实现
EfCryptoInterceptor 是一个内置的拦截器，实现了 rcp.Interceptor 接口。其主要功能是通过配置的加解密逻辑对请求和响应数据进行处理。
核心代码片段
export class EfCryptoInterceptor implements rcp.Interceptor {
private readonly requestEncoder: (request: rcp.RequestContext) => rcp.RequestContext;
private readonly responseDecoder: (response: rcp.Response) => rcp.Response;
constructor(cryptoEvent: {
requestEncoder: (request: rcp.RequestContext) => rcp.RequestContext;
responseDecoder: (response: rcp.Response) => rcp.Response;
}) {
this.requestEncoder = cryptoEvent.requestEncoder;
this.responseDecoder = cryptoEvent.responseDecoder;
}
intercept(chain: rcp.Chain): Promise<rcp.Response> {
const request = this.requestEncoder(chain.request());
return chain.proceed(request).then((response) => {
return this.responseDecoder(response);
});
}
}
功能说明
- 构造函数：接收一个
cryptoEvent对象，包含requestEncoder和responseDecoder两个回调函数，分别用于请求加密和响应解密。 - intercept 方法：
- 调用
requestEncoder对请求数据进行加密。 - 通过
chain.proceed将加密后的请求发送到服务器。 - 在响应返回后，调用
responseDecoder对响应数据进行解密。
- 调用
拦截器链的配置
拦截器链可以通过 efRcpConfig 进行配置。开发者可以根据需求添加多个拦截器，例如日志拦截器、加解密拦截器等。
示例配置
import { efRcpConfig, EfCryptoInterceptor } from '@yunkss/ef_rcp';
// 配置加解密拦截器
efRcpConfig.interceptors = [
new EfCryptoInterceptor({
requestEncoder: (request) => {
// 加密逻辑
return request;
},
responseDecoder: (response) => {
// 解密逻辑
return response;
},
}),
];
流程图
以下是通过 mermaid 绘制的拦截器链处理流程：
总结表格
| 功能 | 说明 |
|---|---|
| 请求加密 | 在请求发送前对数据进行加密处理。 |
| 响应解密 | 在响应返回后对数据进行解密处理。 |
| 可扩展性 | 支持通过配置添加多个拦截器，满足不同业务需求。 |
| 统一处理 | 确保所有请求和响应都经过相同的逻辑处理，避免代码重复。 |
通过 EfCryptoInterceptor 的设计，ef_rcp 模块为开发者提供了一种灵活且强大的方式来处理请求和响应的加解密需求。
错误处理与日志记录
在 ef_rcp 模块中，错误处理与日志记录是确保网络请求稳定性和可维护性的关键部分。通过统一的错误处理机制和灵活的日志配置，开发者可以快速定位问题并优化代码逻辑。本节将详细介绍 ef_rcp 中的错误处理与日志记录功能。
错误处理机制
ef_rcp 提供了统一的错误处理对象 EfRcpError，用于封装网络请求中的异常信息。其核心属性包括：
statusCode: HTTP 状态码。message: 错误描述信息。details: 可选的错误详情。
示例代码
import { EfRcpError } from '@yunkss/ef_rcp';
// 创建错误对象
const error = new EfRcpError(404, '资源未找到', '请求的URL不存在');
// 输出错误信息
console.error(error.toString());
错误拦截器
ef_rcp 内置了多种错误拦截器，用于处理不同类型的异常：
- 系统级错误拦截器 (
EfSysCodeInterceptor)：处理 HTTP 状态码异常。 - 业务级错误拦截器 (
EfBusinessCodeInterceptor)：处理业务逻辑中的自定义错误码。 - 通用错误拦截器 (
EfCodeInterceptor)：结合系统级和业务级错误处理。
流程图
日志记录功能
ef_rcp 通过 efRcpConfig.logger 提供灵活的日志记录功能，支持以下配置：
enable: 是否启用日志记录（默认为false）。level: 日志级别（debug、info、warn、error）。format: 自定义日志格式。
示例配置
import { efRcpConfig } from '@yunkss/ef_rcp';
// 启用日志记录
efRcpConfig.logger.enable = true;
efRcpConfig.logger.level = 'debug';
日志拦截器
RcpLogInterceptor 负责记录请求和响应的详细信息，包括：
- 请求 URL 和参数。
- 响应状态码和数据。
- 错误堆栈信息。
示例日志输出
[DEBUG] 请求 URL: /api/user
[DEBUG] 请求参数: { id: 123 }
[INFO] 响应状态码: 200
[ERROR] 错误信息: 资源未找到
错误与日志结合实践
通过结合错误处理和日志记录，可以快速定位和解决问题。以下是一个完整的示例：
import { efRcpClientApi, efRcpConfig } from '@yunkss/ef_rcp';
// 配置日志
efRcpConfig.logger.enable = true;
// 发起请求
efRcpClientApi.get('/api/user', { id: 123 })
.then(response => {
console.log('请求成功:', response.data);
})
.catch(error => {
console.error('请求失败:', error.toString());
});
状态图
注意事项
- 性能优化：在生产环境中，建议关闭
debug级别的日志记录。 - 自定义日志：可以通过扩展
RcpLogInterceptor实现自定义日志逻辑。 - 错误兜底：确保所有异常都被捕获并处理，避免应用崩溃。
通过以上功能，ef_rcp 为开发者提供了强大的错误处理和日志记录工具，帮助构建更健壮的网络请求模块。
RCP 与 Axios 的对比
在 yunkss/ef-tool 项目中，ef_rcp 和 ef_axios 是两个核心的网络请求模块，分别基于 RCP 和 Axios 进行了封装。以下从多个维度对两者进行对比，帮助开发者根据实际需求选择合适的模块。
1. 功能对比
| 功能特性 | ef_rcp (RCP) | ef_axios (Axios) |
|---|---|---|
| 请求方法支持 | 支持 GET、POST、PUT、DELETE 等 | 支持 GET、POST、PUT、DELETE 等 |
| 文件上传/下载 | 支持 | 支持 |
| 请求拦截与加解密 | 提供统一的请求拦截和加解密功能 | 提供整体和部分字段加解密功能 |
| 全局配置 | 支持超时、证书、会话监听等 | 支持全局请求头、加解密开关、日志等 |
| 异常处理 | 统一异常对象 EfRcpError | 统一异常对象 EfAxiosError |
| 进度监听 | 支持上传和下载进度监听 | 支持上传和下载进度监听 |
2. 代码示例对比
ef_rcp 示例
import { efRcpClientApi } from '@yunkss/ef_rcp';
// POST 请求
const response = await efRcpClientApi.post({
url: '/api/test',
query: { key: 'value' },
headers: { 'Content-Type': 'application/json' },
});
ef_axios 示例
import { efClientApi } from '@yunkss/ef_axios';
// POST 请求
const response = await efClientApi.post({
url: '/api/test',
query: { key: 'value' },
headers: { 'Content-Type': 'application/json' },
});
3. 性能与灵活性
| 维度 | ef_rcp (RCP) | ef_axios (Axios) |
|---|---|---|
| 性能优化 | 针对 HarmonyOS 优化 | 基于 Axios 的通用优化 |
| 灵活性 | 提供更多底层配置选项 | 提供更简洁的 API 设计 |
| 适用场景 | 适合复杂业务逻辑和高定制化需求 | 适合快速开发和轻量级需求 |
4. 加解密支持对比
ef_rcp
- 提供统一的请求拦截和加解密功能。
- 支持全局配置加解密开关和密钥。
ef_axios
- 支持整体传输加密和部分字段加密。
- 可通过
efAxiosParams配置加解密参数。
5. 总结
-
选择
ef_rcp：
适用于需要高度定制化、复杂业务逻辑或 HarmonyOS 深度集成的场景。 -
选择
ef_axios：
适用于快速开发、轻量级需求或需要灵活加解密的场景。
两者均提供了完善的文档和示例，开发者可根据项目需求灵活选择。
总结
ef_rcp 模块通过其丰富的功能和灵活的配置，为开发者提供了强大的 RCP 协议支持。无论是请求封装、全局配置、异常处理、文件操作还是安全性配置，ef_rcp 都能满足复杂的网络通信需求。与 ef_axios 相比，ef_rcp 更适合需要高度定制化和复杂业务逻辑的场景。通过统一的错误处理和日志记录，ef_rcp 进一步提升了网络请求的稳定性和可维护性。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
