以下是为提供的 `OAuthClient` 类编写的 **Markdown 格式技术文档**，涵盖了类的功能、设计思想、使用方式、参数说明及示例等内容。

---

# `OAuthClient` 技术文档

`OAuthClient` 是一个基于 HTTP(S) 的异步客户端工具类，用于调用由第三方服务发布的 RESTful API 接口。它通过预定义的接口描述（`desc`）动态构建请求，并解析响应数据，支持自定义数据转换、错误判断逻辑和返回结构处理。

该类广泛应用于需要与 OAuth 认证或标准 JSON API 交互的服务中，具有良好的可配置性和扩展性。

---

## 📦 模块依赖

```python
import json
from appPublic.httpclient import HttpClient, RESPONSE_TEXT, RESPONSE_JSON, RESPONSE_BIN, RESPONSE_FILE, RESPONSE_STREAM, HttpError
from appPublic.argsConvert import ArgsConvert
from appPublic.dictObject import DictObject
```

- `HttpClient`: 异步 HTTP 客户端，支持多种响应类型。
- `ArgsConvert`: 用于模板字符串替换（如 `${key}`）。
- `DictObject`: 支持通过属性访问字典键值的对象封装。

---

## 🧱 类定义

```python
class OAuthClient:
    def __init__(self, desc, converters={})
```

### 构造函数参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `desc` | `dict` | 接口描述对象，必须包含 `data` 字段，定义了基础数据和各 API 方法的配置。详见下方“接口描述格式”章节。 |
| `converters` | `dict[str, callable]` | 可选的数据转换函数映射表，键为转换器名称，值为函数引用。 |

> ⚠️ 注意：`desc['data']` 必须存在，否则会抛出断言错误。

---

## 🔧 接口描述格式 (`desc`)

`desc` 是一个字典，其结构如下：

```json
{
  "data": { /* 基础共享数据，可在请求时被引用 */ },
  "method_name": {
    "path": "/api/v1/users/${userId}",
    "method": "GET",  // 可选，默认 GET
    "headers": [ ... ],
    "params": [ ... ],
    "data": [ ... ],  // 请求体中的数据
    "resp": [
      {
        "name": "result",
        "resp_keys": ["user", "name"],
        "converter": "to_upper"  // 可选
      }
    ],
    "error_if": {
      "error_keys": ["status"],
      "op": "==",           // 比较操作符：'==' 或 '!='
      "value": "fail",
      "code_keys": ["code"], // 错误码路径
      "msg_keys": ["message"] // 错误信息路径
    }
  }
}
```

### 字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `data` | `dict` | 全局上下文数据，可用于模板替换。 |
| `method_name` | `dict` | 每个 API 接口的配置项，方法名作为 key。 |
|   `path` | `str` | 接口路径，支持 `${}` 占位符变量。 |
|   `method` | `str` | HTTP 方法（GET/POST/PUT/DELETE 等），默认为 `GET`。 |
|   `headers` | `list[dict]` | 请求头列表，每个元素形如 `{name: "Header-Key", value: "HeaderValue", converter?: "funcName"}` |
|   `params` | `list[dict]` | URL 查询参数，格式同上。 |
|   `data` | `list[dict]` | 请求体数据（JSON 格式），格式同上。 |
|   `resp` | `list[dict]` | 响应数据提取规则。 |
|     `name` | `str` | 返回结果中字段的名称。 |
|     `resp_keys` | `list[str]` | 在响应 JSON 中获取数据的路径（嵌套键）。 |
|     `converter` | `str` | 转换函数名（需在 `converters` 中注册）。 |
|   `error_if` | `dict` | 自定义错误判断条件。 |
|     `error_keys` | `list[str]` | 提取用于比较的响应字段路径。 |
|     `op` | `str` | 比较操作符：`==` 或 `!=`。 |
|     `value` | any | 期望值，用于对比。 |
|     `code_keys` | `list[str]` | 错误码字段路径（可选）。 |
|     `msg_keys` | `list[str]` | 错误消息字段路径（可选）。 |

---

## 🧩 核心方法

### `__call__(self, host, mapi, params) -> dict`

发起一次 API 调用。

#### 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `host` | `str` | 服务主机地址，例如 `"https://api.example.com"` |
| `mapi` | `str` | 接口方法名，对应 `desc` 中的键名。 |
| `params` | `dict` | 动态传入的参数，用于替换模板和构造请求。 |

#### 返回值

成功时：
```json
{
  "status": "ok",
  "data": { /* 根据 resp 配置提取的数据 */ }
}
```

失败时：
```json
{
  "status": "error",
  "code": "400",
  "message": "Bad Request"
}
```

#### 流程说明

1. 查找 `desc[mapi]` 是否存在；
2. 使用 `datalize()` 替换路径中的 `${}` 变量；
3. 构造完整 URL；
4. 处理 headers、params、data（应用转换器）；
5. 发起异步 HTTP 请求；
6. 解析响应为 `DictObject`；
7. 检查是否符合 `error_if` 条件；
8. 按照 `resp` 规则提取并转换返回数据。

> 📌 日志输出：请求详情（URL、method、params 等）将打印到控制台。

---

### `setup_req_data(data, ns) -> dict or None`

将一组 `{name, value, converter}` 结构的数据根据命名空间 `ns` 进行模板替换和转换。

#### 参数

- `data`: 数据项列表（如 headers、params）
- `ns`: 命名空间（通常是 `params`）

#### 内部调用

- `setup_req_kv()`: 处理单个键值对，执行模板替换和转换。

---

### `datalize(dic, data={}) -> dict`

执行模板替换（`${key}` → 实际值）。

#### 说明

- 合并 `self.data`（全局数据）与传入的 `data`；
- 使用 `ArgsConvert('${', '}')` 执行替换；
- 支持嵌套字典和字符串。

#### 示例

```python
self.data = {'token': 'abc123'}
dic = {'url': '/api?tk=${token}'}
result = self.datalize(dic)  # {'url': '/api?tk=abc123'}
```

---

### `get_resp_data(resp, keys, converter=None)`

从响应对象中按 `keys` 路径提取数据，并可选地进行转换。

#### 参数

- `resp`: `DictObject` 类型的响应体；
- `keys`: 键路径列表，如 `['data', 'user', 'id']`；
- `converter`: 转换函数名。

#### 示例

```python
resp = DictObject(data={"user": {"name": "alice"}})
value = get_resp_data(resp, ['data', 'user', 'name'])  # "alice"
```

---

### `setup_return_data(resp) -> dict`

根据 `api.resp` 配置，构建最终返回的 `data` 对象。

#### 示例配置

```json
"resp": [
  {
    "name": "username",
    "resp_keys": ["data", "user", "name"],
    "converter": "to_upper"
  }
]
```

#### 输出

```json
{
  "status": "ok",
  "data": {
    "username": "ALICE"
  }
}
```

---

### `check_if_error(resp) -> dict or None`

检查响应是否满足预设的错误条件。

#### 判断逻辑

```python
v = resp.get_data_by_keys(ei.error_keys)
if ei.op == '==' and v == ei.value → 触发错误
if ei.op == '!=' and v != ei.value → 触发错误
```

#### 成功返回

- `None` 表示无错误。

#### 失败返回

```json
{
  "status": "error",
  "code": "...",
  "message": "..."
}
```

> 💡 支持从响应中提取 `code` 和 `message`。

---

### `set_data(resp_data, data_desc)`

将响应中的某些字段保存回 `self.data`，用于后续请求共享状态（如 token 刷新）。

#### 参数

- `resp_data`: 原始响应数据（dict）
- `data_desc`: 描述如何映射字段

```python
data_desc = [
    {'field': 'access_token', 'name': 'token'},
    {'field': 'expires_in', 'name': 'expires'}
]
```

执行后：
```python
self.data['token'] = resp_data['access_token']
self.data['expires'] = resp_data['expires_in']
```

---

## ✅ 使用示例

### 1. 定义接口描述

```python
desc = {
    "data": {
        "client_id": "your_client_id",
        "client_secret": "your_secret"
    },
    "get_user": {
        "path": "/users/${user_id}",
        "method": "GET",
        "headers": [
            {"name": "Authorization", "value": "Bearer ${token}"}
        ],
        "resp": [
            {
                "name": "userInfo",
                "resp_keys": ["data"],
                "converter": "strip_data"
            }
        ],
        "error_if": {
            "error_keys": ["status"],
            "op": "==",
            "value": "error",
            "code_keys": ["error_code"],
            "msg_keys": ["error_msg"]
        }
    }
}
```

### 2. 定义转换器

```python
def to_upper(s):
    return s.upper() if isinstance(s, str) else s

converters = {
    "to_upper": to_upper,
    "strip_data": lambda x: x.get('data') if isinstance(x, dict) else x
}
```

### 3. 创建并调用客户端

```python
client = OAuthClient(desc, converters=converters)

result = await client(
    host="https://api.example.com",
    mapi="get_user",
    params={
        "user_id": "123",
        "token": "xyz987"
    }
)

print(result)
# 输出:
# {
#   "status": "ok",
#   "data": {
#     "userInfo": { ... }
#   }
# }
```

---

## 🛠️ 调试信息

所有请求细节将通过 `print()` 输出：

```python
print(f'{url=}, {method=}, {myparams=}, {mydata=}, {myheaders=}')
```

建议在生产环境中移除或替换为日志记录。

---

## ❗ 异常处理

- 若指定的 `mapi` 未在 `desc` 中定义，抛出 `Exception`；
- HTTP 请求异常捕获为 `HttpError`，返回标准错误结构；
- 网络级错误（如连接超时）也会被捕获并返回 `"https error"`。

---

## 🧩 扩展建议

- 添加日志模块替代 `print()`；
- 支持更多响应类型（如文件下载）；
- 增加中间件钩子（before_request / after_response）；
- 支持分页自动迭代。

---

## 📚 总结

`OAuthClient` 是一个灵活、声明式的 API 客户端封装，适用于微服务间通信、第三方接口集成等场景。通过配置驱动的方式，实现了解耦与复用，适合构建统一的外部服务网关层。

--- 

> 📎 版本：1.0  
> 📅 最后更新：2025年4月5日  
> © 2025 Your Company. All rights reserved.