# easy-http **Repository Path**: mrbox/easy-http ## Basic Information - **Project Name**: easy-http - **Description**: Easy HTTP is a lightweight Java HTTP client SDK with a unified, clean API. It supports various HTTP methods, flexible configuration (timeout, proxy, connection pool), file upload/download, and non-standard GET with Body requests. 是一个轻量级 Java HTTP 客户端 SDK，提供统一简洁的 API。支持多种 HTTP 方法、灵活配置（超时、代理、连接池）、文件上传/下载，以及非标准的 GET with Body 请求。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-02-18 - **Last Updated**: 2026-02-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: Java, http-client, http-sdk, file-upload, file-download ## README # Easy HTTP SDK [![Build Status](https://github.com/mr-box/easy-http/actions/workflows/maven.yml/badge.svg)](https://github.com/mr-box/easy-http/actions) [![GitHub release](https://img.shields.io/github/release/mr-box/easy-http.svg)](https://github.com/mr-box/easy-http/releases) [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) [![JitPack](https://jitpack.io/v/mr-box/easy-http.svg)](https://jitpack.io/#mr-box/easy-http) Easy HTTP 是一个轻量级、易于使用的 Java HTTP 客户端 SDK，提供统一、简洁的 API 接口，旨在简化 Java 应用中的 HTTP 请求操作。支持多种底层 HTTP 客户端实现，具有灵活的配置选项，包括代理支持、超时设置、连接池管理等功能。 ## 💡 项目缘起 在对接三方系统接口时，部分接口要求通过 GET 方式请求 Body 发送数据，由于此方式为非标准用法，主流 HTTP 客户端对此支持有限，为此开发了 Easy HTTP SDK，在满足这一特定需求的同时，提供一个可在多个项目中复用的统一请求解决方案。 ## ✨ 特性 - **统一 API**: 针对不同的底层 HTTP 客户端提供一致的请求和响应处理 API。 - **多客户端支持**: 支持 Apache HttpClient (当前版本已实现)，未来可扩展 Jetty, OkHttp 等。 - **灵活配置**: 提供丰富的配置选项，包括连接超时、读取超时、代理设置、SSL/TLS 配置等。 - **代理支持**: 支持 HTTP 代理配置，包括代理主机、端口和认证信息。 - **请求构建器**: 链式调用构建 HTTP 请求，支持 GET, POST, PUT, DELETE 等多种方法。 - **响应处理**: 方便地获取响应状态码、头部、正文内容。 - **文件上传**: 支持 Multipart 文件上传。 - **文件流式下载**: 支持将响应内容流式保存到文件或输出流，适用于大文件下载。 - **异常处理**: 统一的 HTTP 异常体系，方便捕获和处理。 ## 📦 模块结构 ``` easyhttp ├── client # 各种HTTP客户端的具体实现，如Apache HttpClient, Jetty, OkHttp等 │ ├── apache # 基于Apache HttpClient的实现 │ ├── jetty # 基于Jetty HttpClient的实现（待实现） │ └── okhttp # 基于OkHttp的实现（待实现） ├── config # 配置相关的类，定义了HTTP客户端的各项配置 ├── core # 核心接口和抽象，定义了HTTP请求、响应及执行器的核心概念 └── exception # 自定义的HTTP异常类，用于统一处理请求过程中可能出现的错误 ``` ## 🏗️ 架构设计 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Client Code │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ HttpRequest.Builder │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ │ │ header() │ │ queryParam │ │ body() │ │ │ │ headers() │ │ queryParams │ │ formParam() │ │ │ │ method() │ │ │ │ formParams() │ │ │ │ url() │ │ │ │ multipartBody() │ │ │ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ │ │ │ │ build() 校验互斥 │ │ • body/formParams/multipartBody 只能设置其一 │ │ • 自动确定 bodyType (NONE/RAW/FORM/MULTIPART) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ HttpRequest (Immutable) │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ method: HttpMethod │ │ │ │ url: String │ │ │ │ headers: Map │ │ │ │ queryParams: Map> │ │ │ │ bodyType: RequestBodyType (NONE/RAW/FORM/MULTIPART) │ │ │ │ body: String (RAW类型) │ │ │ │ formParams: Map (FORM类型) │ │ │ │ multipartBody: MultipartBody (MULTIPART类型) │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ <> │ │ HttpExecutor │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ + execute(HttpRequest): HttpResponse │ │ │ │ + executeAndSaveTo(HttpRequest, File): HttpResponse │ │ │ │ + executeAndWriteTo(HttpRequest, OutputStream): HttpResponse ││ │ │ + close(): void │ │ │ └───────────────────────────────────────────────────────────┘ │ │ △ │ │ │ │ │ AbstractHttpClientExecutor │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ buildUrlWithQueryParams() - 拼接 query params │ │ │ │ buildHttpRequest() - 构建 Apache HttpClient 请求 │ │ │ │ buildHttpEntity() - 根据 bodyType 构建 Entity │ │ │ │ • RAW: StringEntity │ │ │ │ • FORM: UrlEncodedFormEntity │ │ │ │ • MULTIPART: MultipartEntity │ │ │ │ convertResponse() - 转换为 HttpResponse │ │ │ │ createRetryHandler() - IO异常重试策略 │ │ │ │ createServiceRetryStrategy() - 5xx错误重试策略 │ │ │ └───────────────────────────────────────────────────────────┘ │ │ △ │ │ ┌───────────────┴───────────────┐ │ │ │ │ │ │ PoolingHttpClientExecutor PoolingHttpClientPlusExecutor │ └──────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ HttpResponse (Immutable) │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ statusCode: int │ │ │ │ headers: Map │ │ │ │ bodyBytes: byte[] (统一存储) │ │ │ │ │ │ │ │ + getBodyAsString(): String (UTF-8) │ │ │ │ + getBodyAsString(Charset): String │ │ │ │ + getBodyAsBytes(): byte[] │ │ │ │ + getContentLength(): long │ │ │ │ + isSuccessful(): boolean (2xx判断) │ │ │ └───────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────┘ ``` ## 🚀 快速开始 ### 引入依赖 通过 JitPack 引入此库，将以下仓库和依赖添加到您的 `pom.xml` 中： ```xml jitpack.io https://jitpack.io com.github.mr-box easy-http Tag ``` ### 使用示例 详细的使用示例请参考 - [HttpClientExecutorExample.java](src/test/java/com/github/mrbox/easyhttp/example/HttpClientExecutorExample.java) - [IntegrationPropertyTest.java](src/test/java/com/github/mrbox/easyhttp/client/httpclient/IntegrationPropertyTest.java) ## ⚙️ 配置说明 可以通过 `HttpConfig` 类进行各项配置，例如超时、连接池大小、重试策略、代理配置等。 详细的配置示例请参考 [ConfigExample.java](src/test/java/com/github/mrbox/easyhttp/example/ConfigExample.java) ## 🤝 贡献 欢迎通过 Pull Request 提交代码、报告 Bug 或提出建议。 请先阅读 [贡献指南](CONTRIBUTING.md) 了解详细的贡献流程和代码规范。 ## 📄 许可证 本项目采用 [Apache 2.0 许可证](LICENSE)。 --- **⭐ 如果这个项目对您有帮助，请给个 Star！**