HTTPie CLI 深度实战指南面向 API 时代的命令行 HTTP 客户端【免费下载链接】cli HTTPie CLI — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins more.项目地址: https://gitcode.com/gh_mirrors/cl/cliHTTPie读作aitch-tee-tee-pie是一款以「对人类友好」为核心设计目标的开源命令行 HTTP 客户端专为测试、调试以及与 API、HTTP 服务器交互而打造。它提供http与https两个命令用简单自然且表达力极强的语法构造和发送任意 HTTP 请求并输出经过格式化与着色处理的响应。本篇文章以本仓库 README.md 为骨架结合源码深入讲解 HTTPie 的请求项语法、JSON/表单/文件上传、认证与会话、下载与离线模式、输出控制、网络与 SSL 配置等核心能力读完你既能熟练上手日常 API 调试也能理解其底层参数解析与请求构建原理。项目定位与核心能力总览HTTPie 的核心价值在于把「构造一个 HTTP 请求」这件事从繁琐的底层细节中解放出来。仓库 README.md 明确列出了它的主要特性富有表现力且直观的语法用:、、:、、等符号区分不同类型的请求数据项格式化且着色的终端输出默认对响应头与响应体进行格式化与语法高亮内置 JSON 支持默认将命令行数据序列化为 JSON并自动设置Content-Type与Accept头表单与文件上传支持application/x-www-form-urlencoded与multipart/form-dataHTTPS、代理与认证内置 Basic、Digest 等认证类型支持 SSL 校验、客户端证书与代理任意请求数据既可用结构化键值对也可用--raw或 stdin 传递原始数据自定义请求头可随意覆盖、追加任意 HTTP 头持久化会话跨请求复用 Cookie、请求头与认证信息wget 式下载--download支持断点续传。当前仓库的版本信息记录在 httpie/init.py版本号为3.2.4发布于2024-11-01作者为 Jakub Roztocil采用 BSD 许可证。下图演示了 HTTPie 在终端中的实际运行效果快速上手Hello World 与三个典型示例安装完成后安装方式可参考 docs/installation/README.md仓库还提供了 brew、snap、Debian、Fedora、Arch、macPorts、Chocolatey 等各平台打包脚本见 docs/packaging/即可使用http/https命令发起请求。1. Hello World——最简单的一次 GET 请求https httpie.io/hello2. 自定义 HTTP 方法、请求头与 JSON 数据——一次 PUT 请求携带自定义头X-API-Token:123与 JSON 字段nameJohnhttp PUT pie.dev/put X-API-Token:123 nameJohn3. 离线模式offline mode——只构建并打印请求不真正发送适合调试请求构造过程http --offline pie.dev/post hellooffline4. 带认证调用 GitHub API——为指定 Issue 发布一条评论-a USERNAME使用 Basic 认证未提供密码时 HTTPie 会交互式提示输入http -a USERNAME POST https://api.github.com/repos/httpie/cli/issues/83/comments bodyHTTPie is awesome! :heart:这四个例子覆盖了 HTTPie 的核心用法方法、URL、请求头、JSON 数据、认证与离线模式。下面逐一深入。请求项语法理解分隔符体系HTTPie 最核心的设计是REQUEST_ITEM位置参数语法——用不同的分隔符告诉 HTTPie 一个键值对应该被解析成什么。所有分隔符统一定义在 httpie/cli/constants.py完整清单如下分隔符含义示例:自定义 HTTP 头X-API-Token:123;显式置空的 HTTP 头Header;Cookie;表示发送空 Cookie 头:从文件嵌入 HTTP 头值X-Source:file.txt追加到 URL 的查询参数searchhttpie从文件内容嵌入查询参数qquery.txt数据字段默认序列化为 JSON 对象配合--json配合--form则为表单字段nameHTTPie:非字符串 JSON 数据字段仅--json下可用awesome:true、amount:42、colors:[red,green,blue]表单文件上传字段仅--form/--multipartcv~/Documents/CV.pdf同但将指定文件的内容嵌入为字段值essayDocuments/essay.txt:同:但将指定文件内容解析为 JSON 后嵌入package:./package.json各分隔符的完整说明可以在 httpie/cli/definition.py 中REQUEST_ITEM参数的帮助文本里找到。源码级解析原理从源码结构看请求项的解析遵循「最短优先匹配、最长分隔符优先」的规则。在 httpie/cli/argtypes.py 的KeyValueArgType.__call__中先对原始字符串做分词tokenize反斜杠转义的分隔符不会被视为分隔符的一部分将分隔符按长度排序在 token 中查找位置最早同位置则取最长的分隔符分隔符左侧拼接为 key右侧拼接为 value构造出KeyValueArg。tokenize的实现细节见 argtypes.py决定了一条重要规则如果字段名本身包含与分隔符冲突的字符用反斜杠转义例如http pie.dev/post field-name-with\:colonvalue而KeyValueArgType的转义处理会保留反斜杠本身r\\保证字面量安全。与:、这类多字符分隔符能被正确区分正是因为解析器按「最长优先」匹配。请求项的分发与序列化解析出的每一项会在 httpie/cli/requestitems.py 的RequestItems.from_args中按分隔符分发到不同的目标容器头部 →HTTPHeadersDict支持重复头见process_header_arg查询参数 →RequestQueryParamsDict数据字段 →RequestJSONDataDictJSON 模式或RequestDataDict表单模式文件 →RequestFilesDictmultipart 字段 →MultipartRequestDataDict用于保持文件上传时字段的原始顺序。JSON 模式下嵌套 JSON 项、:、、:会先被单独拆分出来统一交给interpret_nested_json见 httpie/cli/nested_json/interpret.py构造嵌套对象其余项再按规则逐一分发。这就是为什么可以写出person[name]John这样的嵌套字段语法。数据序列化JSON、表单与 multipartHTTPie 默认使用 JSON 模式。在 definition.py 中定义了三类预定义内容类型参数--json/-j默认命令行数据项序列化为 JSON 对象若未显式指定Content-Type与Accept都会被设为application/json--form/-f数据项序列化为表单字段Content-Type设为application/x-www-form-urlencoded一旦出现文件字段请求自动切换为multipart/form-data--multipart与--form类似但即使没有文件也始终发送multipart/form-data并可配合--boundary指定自定义边界字符串。--json与--form在底层通过RequestType枚举见 constants.py映射RequestType.FORM、RequestType.MULTIPART、RequestType.JSON。在 argparser.py 的_process_request_type中解析出的类型被转换为三个布尔标记json、multipart、form后续逻辑据此选择序列化路径。实际序列化发生在 httpie/client.py 的make_request_kwargs中JSON 模式会把数据字典交给json_dict_to_request_bodyjson.dumps序列化并处理顶层列表展开与空数据的情况表单 文件或显式--multipart则调用get_multipart_data_and_content_type生成 multipart 载荷与对应的Content-Type。发送原始数据--raw 与 stdin--raw允许不经过请求项语法处理直接传递原始请求体见 definition.py# 通过 --raw http --rawdata pie.dev/post # 通过 stdin 管道效果相同 echo data | http pie.dev/post # 从文件读取原始数据 http pie.dev/post data.txt--raw、stdin 与keyvalue数据项三者互斥。在 argparser.py 的_ensure_one_data_source中会校验请求体来源stdin、--raw或file不能与keyvalue数据混用如需以键值对优先可加--ignore-stdin。内容压缩--compress/-x用 Deflate 算法压缩请求体并设置Content-Encoding: deflate见 definition.py。它默认在压缩率可能为负时自动跳过重复使用该参数如-xx可强制压缩。底层实现在 httpie/uploads.py 的compress_request且 argparser.py 会拒绝--compress与--chunked、--multipart的组合。输出控制打印什么、怎么格式化--print精确控制输出内容--print/-p用一个字符串指定输出内容五个字母分别对应定义见 constants.py 与 definition.py字符含义H请求头B请求体h响应头b响应体m响应元数据默认行为与终端状态相关逻辑见 argparser.py 的_process_output_options输出到终端TTY默认hb即打印响应头与响应体输出被重定向管道、文件默认只打印响应体b离线模式默认打印请求头与请求体HB。快捷参数-h--headers只打印响应头、-b--body只打印响应体、-m--meta只打印响应元数据分别等价于-p h、-p b、-p m。详细模式与中间请求--verbose/-v是计数型参数见 definition.py一级-v等价于--all --printBHbh打印完整请求与响应同时显示重定向等中间请求/响应二级及以上-vv额外打印响应元数据等价于--all --printBHbhm。--all用于单独开启「显示中间请求/响应」默认只展示最终一次交换。典型场景包括--follow跟随重定向、Digest 认证的首次未授权请求等见 definition.py。美化与着色--pretty取值none不美化重定向输出的默认值、all着色 格式化终端输出的默认值、colors仅着色、format仅格式化。映射关系在 constants.py 的PRETTY_MAP中定义TTY 判定逻辑在 argparser.py。--style/-s选择输出着色样式默认样式与可用样式由 httpie/output/formatters/colors.py 提供auto样式会跟随终端 ANSI 颜色主题。--sorted/--unsorted快捷开关输出排序内部等价于--format-options headers.sort:true,json.sort_keys:true及其反义定义于 definition.py。--format-options细粒度控制格式化可多次使用、逗号分隔。默认值见 constants.pyheaders.sort:true json.format:true json.indent:4 json.sort_keys:true xml.format:true xml.indent:2例如关闭 JSON key 排序并把缩进改为 2http --format-options json.sort_keys:false,json.indent:2 pie.dev/get--format-options的解析与类型校验在 argtypes.py 的parse_format_options中完成每个选项形如section.key:value布尔值与整数值会被自动转换且值类型必须与默认值一致否则报错——这种设计保证用户不会意外把json.indent配成非整数。此外还有两个针对终端展示的覆盖参数--response-charset覆盖响应编码如--response-charsetutf8/big5与--response-mime覆盖响应的 MIME 类型以决定着色与格式化方式如--response-mimeapplication/json定义与校验分别在 definition.py 与 argtypes.py。认证Basic、Digest 与 netrc认证参数集中在 definition.py--auth/-a USER[:PASS] | TOKEN凭据。只给用户名时-a usernameHTTPie 会交互式提示输入密码AuthCredentials.prompt_password见 argtypes.py--auth-type/-A认证机制默认值为basic。可用类型由认证插件注册表提供见 httpie/plugins/registry.py内置插件定义在 httpie/plugins/builtin.py第三方插件可通过插件系统扩展如digest等--ignore-netrc忽略~/.netrc中的凭据。认证的完整处理流程在 argparser.py 的_process_auth中若 URL 中嵌入了http://username:passwordhostname/自动提取为凭据未显式指定凭据时尝试从.netrc读取通过 requests 的get_netrc_auth若凭据缺少密码且认证插件允许提示则在终端交互式请求密码最终交由认证插件构造auth对象注入请求。一个典型的带认证请求http -a USERNAME POST https://api.github.com/repos/httpie/cli/issues/83/comments bodyHTTPie is awesome! :heart:持久化会话跨请求复用状态--session SESSION_NAME_OR_PATH与--session-read-only互斥组见 definition.py实现了持久化会话会话内的自定义请求头、认证凭据以及服务器下发的 Cookie 会在多次请求间持续保留。会话文件默认存储位置为[HTTPIE_CONFIG_DIR]/sessions/HOST/SESSION_NAME.json其中HOST会把host:port中的冒号替换为下划线见 sessions.py。若会话名包含路径分隔符如/tmp/my-session.json则视为匿名会话直接使用该路径。从源码看sessions.py 与 client.py 的collect_messages会话机制的工作方式是请求前从会话文件加载已持久化的请求头与 Cookie请求中CLI 显式指定的头与数据覆盖会话中的值请求后--session模式用最新响应更新 Cookie 并回写会话文件--session-read-only则只读不复用更新。会话存储会跳过Content-与If-前缀的请求头见 sessions.py因为它们与单次请求强相关不应被持久化。Cookie 仅保存name、expires、path、value、domain、secure六个关键字段。仓库还专门提供了旧版本会话格式的兼容迁移httpie/legacy/并有完整的会话格式测试用例tests/test_sessions.py 及 tests/fixtures/session_data/。下载与输出到文件--download/-d提供 wget 式的下载体验定义见 definition.py响应体不打印到 stdout而是保存到文件文件名自动推断基于Content-Disposition或 URL也可用--output FILE显式指定--continue/-c支持断点续传但必须同时指定--output校验见 argparser.py 的_process_download_options下载模式下原本输出到 stdout 的内容会改写到 stderr响应体则走独立的下载管线。下载时--download会隐式开启--follow见 core.py。底层由 httpie/downloads.py 的Downloader负责pre_request检查已下载大小与Range头支持、start打开下载流、finish收尾中断时报告已下载字节数并给出非零退出码见 core.py。--output/-o也可以脱离下载模式单独使用把整体输出保存到文件而非 stdout且以追加写模式打开后先截断见 argparser.py。离线模式与脚本化--offline允许构建并打印请求但不真正发送见 definition.py。在离线模式下输出默认变为请求头与请求体HB--download相关选项会被强制关闭见 argparser.py若同时指定--chunked会直接写入Transfer-Encoding: chunked头以便验证分块逻辑见 client.py。离线模式是调试请求构造的利器也适合在 CI 中做请求格式的断言。脚本化场景中 stdin 扮演重要角色HTTPie 会把管道输入非 TTY 的 stdin当作请求体。--ignore-stdin/-I用于禁止读取 stdin这在需要以键值对优先、且 stdin 可能被占用如某些 CI 环境时非常有用。请求体判定逻辑见 argparser.py。网络与 SSL代理、重定向、超时与证书网络控制网络相关参数定义于 definition.py--proxy PROTOCOL:PROXY_URL按协议指定代理可多次如http:http://foo.bar:3128同时支持环境变量$ALL_PROXY、$HTTP_PROXY、$HTTPS_PROXY--follow/-F跟随 30x 重定向--max-redirects默认上限 30 次超出抛TooManyRedirects见 client.py--timeout SECONDS连接超时默认 0 即不限时。注意它并非整个下载的时限而是「在timeout秒内底层 socket 未收到任何字节」才报错--check-status默认 HTTPie 在无网络或致命错误时退出码为 0开启后4xx 退出码为 45xx 为 5未跟随的 3xx 为 3同时向 stderr 写错误信息详见 tests/test_exit_status.py--max-headers限制读取的响应头数量上限默认 0 表示不限制实现见 client.py通过临时修改http.client._MAXHEADERS--path-as-is跳过/../、/./这类点段的 URL 规范化实现见 client.py--chunked启用分块传输编码设置Transfer-Encoding: chunked。SSL 控制SSL 参数definition.py--verifyyes/true默认校验证书、no/false跳过校验、或传入 CA bundle 文件路径也可以用环境变量REQUESTS_CA_BUNDLE--ssl指定 TLS 协议版本可用项取决于本机 OpenSSL见 httpie/ssl_.py 的AVAILABLE_SSL_VERSION_ARG_MAPPING--ciphersOpenSSL 密码套件列表格式字符串默认值由本机 OpenSSL 决定--cert、--cert-key、--cert-key-pass客户端证书、私钥与私钥口令。若私钥加密而未提供口令HTTPie 会交互式提示见 argparser.py 与 argtypes.py。配置config.json 与 default_optionsHTTPie 的配置目录查找遵循 XDG Base Directory 规范完整优先级在 httpie/config.py 中环境变量HTTPIE_CONFIG_DIR显式指定最高优先级Windows 下为%APPDATA%\httpie传统目录~/.httpie若已存在默认的 XDG 路径$XDG_CONFIG_HOME/httpie未设置XDG_CONFIG_HOME时为~/.config/httpie。配置文件为config.json见 config.py支持的关键项default_options预置默认命令行参数每次运行都会先注入等价于在命令最前面追加这些参数见 core.py 的raw_main。典型用途是把--format-options、--timeout等全局偏好写进去plugins_dir第三方插件目录默认config_dir/pluginsversion_info_file版本检查信息文件路径developer_mode开发环境专用开关。与default_options配套的是--no-OPTION机制对每一个--OPTION都存在对应的--no-OPTION用于将其恢复为默认值见 definition.py 的 epilog 与 argparser.py 的_apply_no_options。这一设计让配置文件中设定的默认值可以被命令行临时关闭例如配置里设了--stylemonokai执行http --no-style ...即可临时还原默认样式。退出码约定HTTPie 的退出码语义集中在 httpie/status.py 与 tests/test_exit_status.py0成功未开启--check-status时即使服务端返回 4xx/5xx 也算成功1一般错误解析失败、连接失败等2参数解析错误3、4、5开启--check-status后对应未跟随的 3xx、4xx、5xx 响应6请求超时--timeout触发见 core.py7重定向次数超过--max-redirects见 core.py130用户按下 CtrlC 中断。在 core.py 的raw_main中可以看到超时、过多重定向、DNS 解析失败EAI_AGAIN/EAI_NONAME会给出针对性提示等都被映射为独立的退出状态并附带清晰的错误信息。从命令行到请求发出一次完整的调用链理解了上述功能后可以串起 HTTPie 的完整执行流程主入口在 httpie/core.py 的main加载插件与默认选项raw_main先加载插件目录并把config.json中的default_options注入参数列表core.py参数解析HTTPieArgumentParser.parse_args依次执行请求类型处理、下载选项处理、标准流设置、输出选项处理、美化选项处理、格式化选项处理、方法推断、请求项解析、URL 处理、认证处理与 SSL 证书处理argparser.py。_guess_method按「有数据则 POST无数据则 GET」推断 HTTP 方法argparser.py并且支持省略 URL 的快捷写法http :3000等价于http://localhost:3000见 definition.py构造请求collect_messages加载会话、构建requests.Request并 prepare应用头转换、路径保持、压缩等变换client.py发送与输出program逐条消费消息请求、中间响应、最终响应按输出选项写出下载模式走Downloader管线core.py。整个过程配合--debug可以在 stderr 输出 HTTPie/Requests/Pygments/Python 版本等诊断信息core.py--traceback则在出错时打印完整异常堆栈--manual展示完整手册。测试与质量保障仓库在 tests/ 下提供了极其完备的测试覆盖可作为学习 HTTPie 行为的活文档tests/test_httpie.py、tests/test_json.py请求项语法与 JSON 序列化行为tests/test_output.py--print、--pretty、--format-options等输出控制tests/test_auth.py、tests/test_auth_plugins.py认证流程与插件扩展tests/test_sessions.py会话持久化与兼容迁移tests/test_downloads.py下载与断点续传tests/test_exit_status.py退出码语义tests/test_offline.py、tests/test_redirects.py、tests/test_ssl.py、tests/test_uploads.py 等分别覆盖对应模块。结合这些测试阅读源码可以快速验证某个参数的真实行为与边界情况。如果你希望参与贡献可以参考 CONTRIBUTING.md 中的流程命令行参数的手册页源文件位于 extras/man/Shell 补全脚本见 extras/httpie-completion.bash 与 extras/httpie-completion.fish。【免费下载链接】cli HTTPie CLI — modern, user-friendly command-line HTTP client for the API era. JSON support, colors, sessions, downloads, plugins more.项目地址: https://gitcode.com/gh_mirrors/cl/cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考