调用API是数据分析工作里绕不开的一环，R语言早期依赖httr包完成HTTP请求，但请求参数一多，代码就容易变成层层嵌套的函数调用，可读性大打折扣。httr2是tidyverse生态中的新一代HTTP客户端，它把请求的构建过程拆成一个个独立的步骤，再用管道操作符串联起来，让整个请求逻辑一目了然。本文将从请求构建、错误处理、批量请求和实际案例几个角度，介绍httr2的链式调用实践。
一、httr2的核心设计：请求即对象
httr2最核心的理念是把HTTP请求看作一个可以逐步修改的对象。你先用request()函数创建一个基础请求，然后通过一系列req_开头的函数往这个对象上叠加信息，最后调用req_perform()真正发起网络请求。这种设计的好处是，请求的每个组成部分都能独立调整，调试时也可以随时用req_dry_run()预览将要发出的请求而不真正发送。
与httr包把所有参数塞进一个GET()调用的方式相比，httr2的链式写法更符合"做一件事的函数只做一件事"的原则。比如给请求添加查询参数用req_url_query()，添加请求头用req_headers()，设置超时用req_timeout()，函数名本身就是文档，读代码的人不需要翻帮助文档就能明白每一步在干什么。
一个典型的请求构建流程如下：
library(httr2)
# 构建一个访问公共API的请求
req <- request("https://api.github.com") |>
req_url_path("search/repositories") |>
req_url_query(q = "httr2", per_page = 5) |>
req_user_agent("my-r-app") |>
req_timeout(30)
# 预览请求内容，不真正发送
req_dry_run(req)这段代码从上到下读下来，就像在描述"我要访问GitHub，路径是search/repositories，查询关键词是httr2，每页5条结果"。这种接近自然语言的表达方式，正是链式调用的价值所在。注意httr2默认使用R 4.1以上的原生管道符|>，当然用magrittr的%>%也完全兼容。
二、认证与响应处理：把令牌和解析串成一条链
真实项目中几乎都要处理认证。httr2为常见的认证方式提供了专门函数：req_auth_bearer_token()用于Bearer令牌，req_auth_basic()用于基本认证，req_oauth()系列则封装了完整的OAuth 2.0流程，包括令牌的自动刷新。相比httr包需要自己管理令牌过期重取的逻辑，httr2的OAuth封装能自动缓存凭据并在过期时重新获取，省去了大量样板代码。
# 使用Bearer令牌认证并获取JSON响应
token <- Sys.getenv("MY_API_TOKEN")
resp <- request("https://api.ippipp.com") |>
req_url_path("v2/user/profile") |>
req_auth_bearer_token(token) |>
req_perform()
# 直接解析为R对象
profile <- resp_body_json(resp)
str(profile)响应处理同样有配套函数。resp_body_json()自动解析JSON，resp_body_string()获取原始文本，配合jsonify或tidyjson可以把结果进一步整理成tibble。解析函数会在Content-Type不匹配时直接报错，避免了手动判断响应类型带来的隐患。
一个值得养成的习惯是：永远不要把API密钥硬编码在脚本里。用Sys.getenv()配合.Renviron文件管理凭据，既安全又方便在不同环境间迁移代码。
三、错误处理与自动重试：httr2最有价值的部分
网络请求天然不稳定，超时、限流、服务器5xx错误随时可能发生。httr2内置了重试机制，通过req_retry()可以设置重试次数、重试间隔以及哪些状态码触发重试。它会自动遵循Retry-After响应头，对429限流这类场景尤其友好。
req <- request("https://api.ippipp.com") |>
req_url_path("data/latest") |>
req_retry(max_tries = 3, backoff = 1) |>
req_error(is_error = function(resp) {
# 自定义错误判定：只有5xx才算失败
resp_status(resp) >= 500
})
resp <- req_perform(req)req_error()允许自定义什么情况算错误，这在对接一些把业务错误编码在200响应里的接口时非常实用。此外，httr2的错误信息会包含请求URL和响应体摘要，排查问题时比httr的笼统报错高效得多。
还有一个容易被忽略的功能：req_cache()可以把响应缓存到本地文件，重复运行脚本时直接读取缓存，既加快速度又减少对API的请求量，做数据抓取任务时几乎是必备配置。
四、批量请求与并发：用req_perform_iterative提升吞吐
实际项目中经常需要循环请求多个分页或多个资源。httr2提供了req_perform_iterative()，配合req_url_path_template()可以优雅地处理分页遍历。更进一步，设置parallel = TRUE即可启用多会话并发请求，底层基于curl的multi接口，效率远高于自己写for循环加Sys.sleep。
# 遍历多个ID并收集结果
ids <- c(1, 2, 3, 4, 5)
# 为每个ID生成一个请求
reqs <- lapply(ids, function(id) {
request("https://api.ippipp.com") |>
req_url_path("v2/items", id) |>
req_throttle(rate = 2 / 1) # 每秒最多2个请求，遵守限流
})
# 并发执行所有请求
resps <- req_perform_iterative(reqs, parallel = TRUE)
# 批量解析为tibble
results <- dplyr::bind_rows(lapply(resps, resp_body_json))
print(results)req_throttle()是并发场景下的好帮手，它能限制全局请求速率，避免触发API的限流策略被拉黑。把限流配置和并发执行写在同一条链上，代码即文档，后续维护的人一眼就能看懂请求节奏是怎么控制的。
五、从httr迁移到httr2的几点建议
如果现有代码基于httr，迁移时不需要一步到位。可以先在新模块中使用httr2，老代码保持不动。两者可以共存于同一个脚本，只要注意不混用各自的请求对象即可。函数对应关系大致是：GET()换成request() + req_perform()，add_headers()换成req_headers()，content()换成resp_body_json()等具体类型的函数。
迁移的最大收益在可维护性上。httr2的请求对象是透明的，你可以随时打印它检查每一步叠加的信息；错误信息更详细；重试和缓存开箱即用。对于需要长期维护的数据管道，这些能力能显著降低运维成本。
总结一下，httr2通过请求对象加链式管道的设计，把HTTP调用从一堆参数堆叠变成了清晰的步骤流。掌握request、req_perform、req_retry这几个核心函数，再根据场景补充认证、限流和缓存配置，就能写出既健壮又好读的API调用代码。