From a993b23697d0aa04bccb48a870bebd3df35431c2 Mon Sep 17 00:00:00 2001
From: Tevin <tingquanren@163.com>
Date: Fri, 07 Mar 2025 12:26:55 +0800
Subject: [PATCH] 知识库，改写请求基类主要方法列表，放弃代码注释的表达方式，改用表格模式
---
@framework/201-请求层基类Fetcher.md | 271 +++++++++++++++++++++++++++++++++++++++++++----------
1 files changed, 218 insertions(+), 53 deletions(-)
diff --git "a/@framework/201-\350\257\267\346\261\202\345\261\202\345\237\272\347\261\273Fetcher.md" "b/@framework/201-\350\257\267\346\261\202\345\261\202\345\237\272\347\261\273Fetcher.md"
index 82cee2e..8415c1d 100644
--- "a/@framework/201-\350\257\267\346\261\202\345\261\202\345\237\272\347\261\273Fetcher.md"
+++ "b/@framework/201-\350\257\267\346\261\202\345\261\202\345\237\272\347\261\273Fetcher.md"
@@ -5,6 +5,17 @@
- [引用方法](#引用方法)
- [构造函数](#构造函数)
- [主要方法](#主要方法)
+ - [`spellURL(devSuffix, serSuffix)`](#spellurldevsuffix-sersuffix)
+ - [`get(url, data, options)`](#geturl-data-options)
+ - [`post(url, data, options)`](#posturl-data-options)
+ - [`query(type, url, data, options)`](#querytype-url-data-options)
+ - [`stringToCamel(str)`](#stringtocamelstr)
+ - [`stringToUnderline(str)`](#stringtounderlinestr)
+ - [`transKeyName(type, json)`](#transkeynametype-json)
+ - [`transImgPath(type, path)`](#transimgpathtype-path)
+ - [请求的 options 配置](#请求的-options-配置)
+ - [`hostType` 主机类型](#hosttype-主机类型)
+ - [`silence` 静音请求](#silence-静音请求)
- [响应处理](#响应处理)
- [处理流程](#处理流程)
- [前端统一响应数据格式](#前端统一响应数据格式)
@@ -43,77 +54,231 @@
## 主要方法
-```js
-/**
- * 拼写 URL 地址
- * @param {String} devSuffix - 开发环境URL后缀
- * @param {String} serSuffix - 服务器环境URL后缀
- * @return {String} 拼接后的 URL 地址（不含域名）
- */
-spellURL(devSuffix, serSuffix) {}
-/**
- * 发送 POST 请求，query 的简写
- * @param {String} url - 请求的 URL
- * @param {*} data - 请求参数
- * @param {Object} [options] - 请求选项
- * @return {Promise<any>} 返回一个 Promise 对象，解析为响应数据
- */
-post(url, data, options = {}) {}
+### `spellURL(devSuffix, serSuffix)`
-/**
- * 基础 AJAX 请求
- * @param {String} type - 请求类型（GET 或 POST）。
- * @param {String} url - 请求的 URL。
- * @param {*} [data] - 请求参数。
- * @param {Object} [options] - 请求选项。
- * @return {Promise<any>} 返回一个 Promise 对象，解析为响应数据。
- */
-query(type, url, data = null, options = {}) {}
+**功能**
+根据开发环境和生产环境拼接 URL 地址。
-/**
- * 下划线字符串转小驼峰
- * @param {String} str - 下划线字符串
- * @return {String} 转换后的驼峰字符串
- */
-stringToCamel(str) {}
+**参数**
+| 参数名 | 类型 | 说明 |
+| --------- | ------ | ------------------------- |
+| devSuffix | String | 开发环境 URL 后缀 |
+| serSuffix | String | 生产环境 URL 后缀（可选） |
-/**
- * 小驼峰字符串转下划线
- * @param {String} str - 小驼峰字符串
- * @return {String} 转换后的下划线字符串
- */
-stringToUnderline(str) {}
+**返回值**
+| 类型 | 说明 |
+| ------ | --------------------------------- |
+| String | 拼接后的完整 URL 地址（不含域名） |
-/**
- * 驼峰与下划线命名模式转换
- * @param {String} type - 'camel' 或 'underline'
- * @param {Object} json - JSON 对象
- * @return {Object} 转换后的 JSON 对象
- */
-transKeyName(type, json) {}
+**示例**
+```javascript
+class FCommon extends Fetcher {
+
+ getUserInfo(id) {
+ const url = this.spellURL('getUserInfo', 'user/user_info');
+ }
+}
```
-说明：
-* spellURL：拼接URL时，会根据是否处于本地开发场景，来选择不同的 URL 前缀
-* query：如果在小程序中，会自动存取 cookies
+**注意事项**
+- 如果启用了 Mock 模式（比如本地开发时），URL 会指向本地的 JSON 文件。
+- 支持处理路径中的 `../` 和多余的 `/`。
-例如：
+---
+### `get(url, data, options)`
+
+**功能**
+发起 GET 请求。
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------- | ------ | ---------------- |
+| url | String | 请求的 URL 地址 |
+| data | Object | 请求参数 |
+| options | Object | 请求配置（可选） |
+
+**返回值**
+| 类型 | 说明 |
+| ------- | ---------------------- |
+| Promise | 返回请求结果的 Promise |
+
+---
+
+### `post(url, data, options)`
+
+**功能**
+发起 POST 请求，query 方法的简写
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------- | ------ | ---------------- |
+| url | String | 请求的 URL 地址 |
+| data | Object | 请求参数 |
+| options | Object | 请求配置（可选） |
+
+**返回值**
+| 类型 | 说明 |
+| ------- | ---------------------- |
+| Promise | 返回请求结果的 Promise |
+
+**示例**
```js
class FCommon extends Fetcher {
- // 请求方法使用示例：获取用户基本信息（提供给数据控制层中调）
- getUserInfo(id) {
+ getUserInfo() {
const url = this.spellURL('getUserInfo', 'user/user_info');
- const send = {
- id
- };
+ const send = {};
return this.post(url, send);
}
}
```
+---
+
+### `query(type, url, data, options)`
+
+**功能**
+发起基础 AJAX 请求
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------- | ------ | -------------------------------- |
+| type | String | 请求类型（如 `'get'`、`'post'`） |
+| url | String | 请求的 URL 地址 |
+| data | Object | 请求参数（可选） |
+| options | Object | 请求配置（可选） |
+
+**返回值**
+| 类型 | 说明 |
+| ------- | ---------------------- |
+| Promise | 返回请求结果的 Promise |
+
+**注意事项**
+- 小程序环境下会自动处理 Cookie，无需手动设置
+
+---
+
+
+
+
+
+
+
+
+
+### `stringToCamel(str)`
+
+**功能**
+将下划线命名的字符串转换为小驼峰命名
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------ | ------ | ---------------- |
+| str | String | 需要转换的字符串 |
+
+**返回值**
+| 类型 | 说明 |
+| ------ | -------------------- |
+| String | 转换后的小驼峰字符串 |
+
+---
+
+### `stringToUnderline(str)`
+**功能**
+将小驼峰命名的字符串转换为下划线命名，如果没有大写字母，则返回原字符串
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------ | ------ | ---------------- |
+| str | String | 需要转换的字符串 |
+
+**返回值**
+| 类型 | 说明 |
+| ------ | -------------------- |
+| String | 转换后的下划线字符串 |
+
+---
+
+### `transKeyName(type, json)`
+**功能**
+将 JSON 对象的键名在驼峰与下划线命名模式之间转换
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------ | ------ | ------------------------------------ |
+| type | String | 转换类型：`'camel'` 或 `'underline'` |
+| json | Object | 需要转换的 JSON 对象 |
+
+**返回值**
+| 类型 | 说明 |
+| ------ | ------------------ |
+| Object | 转换后的 JSON 对象 |
+
+**示例**
+```js
+class FCommon extends Fetcher {
+
+ saveUserInfo() {
+ const json = { 'user_name': 'John' };
+ const result = this.transKeyName('camel', json); // 返回 { userName: 'John' }
+ }
+}
+```
+
+**注意事项**
+- 支持嵌套对象的递归转换
+
+---
+
+### `transImgPath(type, path)`
+**功能**
+转换图片路径，支持修复补齐或裁剪多余部分
+适用于处理旧版运营平台的图片路径，确保路径格式统一
+
+**参数**
+| 参数名 | 类型 | 说明 |
+| ------ | ------ | ---------------------------- |
+| type | String | 转换类型：`'fix'` 或 `'cut'` |
+| path | String | 需要转换的图片路径 |
+
+**返回值**
+| 类型 | 说明 |
+| ------ | ---------------- |
+| String | 转换后的图片路径 |
+
+**示例**
+```js
+
+class FCommon extends Fetcher {
+
+ saveUserInfo() {
+ const path = '4/5e56307c489c7.jpg';
+ const result = this.transImgPath('fix', path); // 返回 '/upload/4/5e56307c489c7.jpg'
+ }
+}
+```
+
+**注意事项**
+- 支持多路径（逗号分隔）的批量转换，即先分别处理每一项后再（逗号）合并
+
+
+## 请求的 options 配置
+
+### `hostType` 主机类型
+在混合 App 中，指定本次请求的主机类型（即域名）
+
+- `base` 基础主机（预登陆用）
+- `main` 默认主机，默认值，正常业务主机
+ - 优先由 java 层在 webview 的 URL 上指定
+ - 未指定时，按文件 project.config.json 的 host.buildHost 项值指定
+
+### `silence` 静音请求
+设为 true 时，如果请求失败，不显示提示
+
+
+
## 响应处理
### 处理流程
--
Gitblit v1.9.1