nim-requests

概述

nim-requests 是 Python 著名 HTTP 库 requests 的 Nim 2 完整复刻， 提供完全一致的 API 风格，同时采用 Nim 原生风格实现。 支持 GET / POST / PUT / DELETE / HEAD / OPTIONS / PATCH 全部 HTTP 方法， 内置 Session 会话、Cookie 持久化、Basic / Bearer 认证、文件上传、流式下载等核心功能。

安装

环境要求

使用 nimble

nimble install nim-requests

本地使用

# 将 src/ 目录放入项目，直接 import
import requests

# 或通过 nimble 安装为本地包
nimble develop

编译选项

# 编译时启用 SSL
nim c -d:ssl your_app.nim

# nimble 测试
nimble test

快速开始

GET 请求

import requests

let r = get("https://httpbin.org/json")
echo r.code          # 200
echo r.body          # 响应体
echo r.json["slideshow"].getStr  # JSON 解析
echo r.headers["content-type"]   # 响应头

POST 请求

import requests, std/json

# 表单数据
let r1 = post("https://httpbin.org/post", data = "key=value")

# JSON 数据
let r2 = post("https://httpbin.org/post",
              jsonBody = %*{"name": "nim", "version": 2})

Session 会话

let s = session(timeout = 10)
s.headers["Authorization"] = "Bearer my-token"
let r = s.reqGet("https://httpbin.org/headers")
echo r.json
s.reqClose()

带参数请求

import std/tables

var params = {"page": "1", "size": "20"}.toTable
let r = get("https://httpbin.org/get", params = params)

顶层 API

与 Python requests 完全一致的便捷函数，每个调用创建独立客户端。

request() 通用方法

import requests

# 使用枚举指定方法
let r1 = request(rmGet, "https://httpbin.org/get")
let r2 = request(rmPost, "https://httpbin.org/post", data = "a=1")
let r3 = request(rmDelete, "https://httpbin.org/delete")

# 带参数
var params = {"q": "nim"}.toTable
let r4 = request(rmGet, "https://httpbin.org/get", params = params)

Session 会话

Session 维持跨请求的持久状态：Headers、Cookies、认证信息、代理设置等。 与 Python requests.Session 行为完全一致。

创建 Session

import requests

let s = session(
  headers = {"User-Agent": "MyApp/1.0"}.toTable,
  auth = ("username", "password"),
  timeout = 15,
  verify = true,
  maxRedirects = 5,
)

Session 方法

Cookie 持久化

let s = session()
discard s.reqGet("https://httpbin.org/cookies/set/token/abc123")
discard s.reqGet("https://httpbin.org/cookies/set/uid/42")
let r = s.reqGet("https://httpbin.org/cookies")
echo r.json  # {"cookies": {"token": "abc123", "uid": "42"}}
s.reqClose()

认证

let s = session(auth = ("user", "pass"))
let r = s.reqGet("https://httpbin.org/basic-auth/user/pass")
echo r.ok  # true
s.reqClose()

自定义 Headers 持久化

var hdrs = {"X-Session-Id": "my-session"}.toTable
let s = session(headers = hdrs)
let r = s.reqGet("https://httpbin.org/headers")
echo r.json["headers"]["X-Session-Id"].getStr  # "my-session"
s.reqClose()

RequestsClient 客户端

RequestsClient 是底层客户端对象，提供比顶层函数更精细的控制： 代理设置、Cookie 持久化、自定义超时等。

创建客户端

import requests

let client = newRequestsClient(
  timeout = 30,
  verify = true,
  maxRedirects = 10,
)

客户端方法

代理设置

let client = newRequestsClient()
client.setProxy("http://proxy.example.com:8080")
let r = client.reqGet("https://httpbin.org/ip")
echo r.json
client.reqClose()

Cookie 持久化

let client = newRequestsClient()
discard client.reqGet("https://httpbin.org/cookies/set/ckey/cval")
let r = client.reqGet("https://httpbin.org/cookies")
echo r.json["cookies"].getStr  # 包含 "ckey=cval"
client.reqClose()

数据模型

HttpResp — 响应对象

便捷方法

HttpReq — 请求对象

import requests

var req = newRequest("https://httpbin.org/post", rmPost)
req.data = "key=value"
req.headers["Content-Type"] = "application/x-www-form-urlencoded"
req.timeout = 10
req.allowRedirects = false
req.cookies.setCookie("session", "abc")

CaseInsensitiveTable — 大小写不敏感表

HTTP 头部专用数据结构，键名大小写不敏感。

let t = newCaseInsensitiveTable()
t["Content-Type"] = "application/json"
echo t["content-type"]   # "application/json"
echo t["CONTENT-TYPE"]   # "application/json"
echo t.containsKey("content-type")  # true
echo t.getVal("missing", "default")  # "default"

# 迭代
for k, v in t.items:
  echo k, " = ", v

CookieJar — Cookie 容器

let jar = newCookieJar()
jar.setCookie("session", "abc123", domain = "example.com",
              path = "/", secure = true, httpOnly = true)
echo jar.getCookie("session")  # "abc123"
echo jar.getCookieHeader()     # "session=abc123"

# 解析 Set-Cookie 头
jar.updateFromHeader("token=xyz; Path=/api; Secure; HttpOnly")
echo jar.getCookie("token")  # "xyz"

jar.clear()

认证模块

BasicAuth

import requests

let auth = newBasicAuth("username", "password")
let (key, val) = auth.applyAuth()
# key = "Authorization"
# val = "Basic dXNlcm5hbWU6cGFzc3dvcmQ="

BearerAuth

let auth = newBearerAuth("my-token-123")
let (key, val) = auth.applyAuth()
# key = "Authorization"
# val = "Bearer my-token-123"

多态派发

var auth: AuthBase = newBasicAuth("u", "p")
let (k1, v1) = auth.applyAuth()  # Basic ...

auth = newBearerAuth("tok")
let (k2, v2) = auth.applyAuth()  # Bearer tok

工具函数

URL 构建

var params = {"q": "hello world", "page": "1"}.toTable
echo buildURL("https://example.com/search", params)
# https://example.com/search?q=hello+world&page=1

echo buildURL("https://example.com?a=1", {"b": "2"}.toTable)
# https://example.com?a=1&b=2

编码检测

echo getEncodingFromHeaders("text/html; charset=utf-8")  # "utf-8"
echo getEncodingFromHeaders("application/json")            # "utf-8"
echo getEncodingFromHeaders("text/html; charset=gbk; x=y") # "gbk"

JSON 判断

echo guessJSON("""{"key": "value"}""")  # true
echo guessJSON("""[1, 2, 3]""")         # true
echo guessJSON("plain text")             # false
echo guessJSON("  {\"a\":1}")            # true

异常体系

异常处理示例

import requests

try:
  let r = get("https://httpbin.org/status/500")
  r.raiseForStatus()
except HTTPError as e:
  echo "HTTP 错误: ", e.msg  # "500 Internal Server Error"

try:
  let r = get("https://invalid-host.example.com")
except ConnectionError as e:
  echo "连接失败: ", e.msg

测试报告

全部 80+ 测试用例 通过，覆盖 17 个测试套件。

测试套件一览

运行测试

# 启动测试服务器
python3 tests/server.py &

# 运行测试
nimble test

# 或手动编译
nim c -d:ssl --path:src -r tests/test_all.nim