67db2ee5b2
- 移除 docs/ 和 Release CI，文档维护点收归 mipu-api 子模块 - 新增 sdk/mipu_requests Python SDK（构造参数传入凭据） - 新增 CLAUDE.md 标注文档维护路径 - 精简 README Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
176 lines
4.2 KiB
Markdown
176 lines
4.2 KiB
Markdown
# mipu_requests — 从 requests 迁移指南
|
||
|
||
## 快速对比
|
||
|
||
```python
|
||
# ── requests ──────────────────────────────────────
|
||
import requests
|
||
|
||
s = requests.Session()
|
||
s.proxies = {"https": "http://proxy:8080"}
|
||
resp = s.get("https://example.com/page")
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
|
||
# ── mipu_requests ─────────────────────────────────
|
||
import mipu_requests
|
||
|
||
s = mipu_requests.session(
|
||
base_url="https://api-eu.mipuyun.com",
|
||
client_key="your_client_key",
|
||
client_secret="your_client_secret",
|
||
agent="JQ",
|
||
)
|
||
s.proxies = "res_mipu_bookxWdyg"
|
||
resp = s.get("https://example.com/page")
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
```
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
pip install mipu-requests
|
||
```
|
||
|
||
## 创建 Session
|
||
|
||
```python
|
||
import mipu_requests
|
||
|
||
# Agent 模式 — 通过指定 agent 走 /unlocker/agent 端点
|
||
s = mipu_requests.session(
|
||
base_url="https://api-eu.mipuyun.com",
|
||
client_key="your_key",
|
||
client_secret="your_secret",
|
||
agent="JQ",
|
||
)
|
||
|
||
# Request 模式 — 走 /unlocker/request 端点（无需 agent）
|
||
s = mipu_requests.session(
|
||
base_url="https://api-eu.mipuyun.com",
|
||
client_key="your_key",
|
||
client_secret="your_secret",
|
||
mode="request",
|
||
)
|
||
```
|
||
|
||
## 设置代理
|
||
|
||
与 `requests` 唯一**必须修改**的地方：
|
||
|
||
```python
|
||
# requests — 传 dict
|
||
s.proxies = {"http": "http://proxy:8080", "https": "http://proxy:8080"}
|
||
|
||
# mipu_requests — 传字符串（米普 proxy 标识）
|
||
s.proxies = "res_mipu_bookxWdyg"
|
||
|
||
# 单次请求覆盖代理
|
||
resp = s.get(url, proxy="another_proxy")
|
||
```
|
||
|
||
## 请求方法
|
||
|
||
完全一致，无需改动：
|
||
|
||
```python
|
||
resp = s.get(url, params={"key": "value"}, headers={...})
|
||
resp = s.post(url, data={"key": "value"}, headers={...})
|
||
resp = s.post(url, json={"key": "value"}, headers={...})
|
||
resp = s.put(url, data=body, headers={...})
|
||
resp = s.delete(url, headers={...})
|
||
```
|
||
|
||
## Response 对象
|
||
|
||
属性和方法与 `requests.Response` 一致：
|
||
|
||
```python
|
||
resp.status_code # int HTTP 状态码
|
||
resp.text # str 响应体文本
|
||
resp.content # bytes 响应体字节
|
||
resp.headers # dict 响应头
|
||
resp.ok # bool status_code 在 200-399
|
||
resp.url # str 请求 URL
|
||
resp.encoding # str 编码（默认 utf-8）
|
||
resp.cookies # dict 空 dict（兼容属性）
|
||
resp.reason # str 状态码原因短语
|
||
|
||
resp.json() # 解析 JSON
|
||
resp.raise_for_status() # >=400 抛异常
|
||
resp.iter_content(chunk_size) # 按块迭代
|
||
```
|
||
|
||
## 异常处理
|
||
|
||
```python
|
||
try:
|
||
resp = s.get(url)
|
||
resp.raise_for_status()
|
||
except mipu_requests.HTTPError as e:
|
||
print(f"目标站错误: {e.response.status_code}")
|
||
except mipu_requests.APIError as e:
|
||
print(f"API 错误: {e}")
|
||
except mipu_requests.RequestException as e:
|
||
print(f"请求异常: {e}")
|
||
```
|
||
|
||
## 异步模式
|
||
|
||
默认开启异步轮询防止长连接断连：
|
||
|
||
```python
|
||
# 默认异步
|
||
s = mipu_requests.session(...)
|
||
|
||
# 关闭异步
|
||
s = mipu_requests.session(..., async_mode=False)
|
||
|
||
# 自定义参数
|
||
s = mipu_requests.session(
|
||
...,
|
||
poll_interval=3,
|
||
poll_max=20,
|
||
submit_timeout=60,
|
||
poll_timeout=(5, 30),
|
||
)
|
||
```
|
||
|
||
## 完整迁移示例
|
||
|
||
```python
|
||
# ── 迁移前 (requests) ────────────────────────────
|
||
import requests
|
||
|
||
s = requests.Session()
|
||
s.headers.update({"user-agent": "Mozilla/5.0"})
|
||
s.proxies = {"https": "http://proxy:8080"}
|
||
|
||
resp = s.get("https://example.com/api", params={"page": 1})
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
|
||
# ── 迁移后 (mipu_requests) ───────────────────────
|
||
import mipu_requests
|
||
|
||
s = mipu_requests.session(
|
||
base_url="https://api-eu.mipuyun.com",
|
||
client_key="your_key",
|
||
client_secret="your_secret",
|
||
agent="JQ",
|
||
)
|
||
s.headers = {"user-agent": "Mozilla/5.0"}
|
||
s.proxies = "res_mipu_bookxWdyg"
|
||
|
||
resp = s.get("https://example.com/api", params={"page": 1})
|
||
resp.raise_for_status()
|
||
data = resp.json()
|
||
```
|
||
|
||
**迁移只需 2 步：**
|
||
1. 构造 `mipu_requests.session()` 时传入 `base_url`/`client_key`/`client_secret`/`agent`
|
||
2. `s.proxies = {...}` → `s.proxies = "proxy_name"`
|
||
|
||
其余代码无需改动。
|