Easy HTTP SDK

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<String, String>                              │  │
│  │ queryParams: Map<String, List<String>>                    │  │
│  │ bodyType: RequestBodyType (NONE/RAW/FORM/MULTIPART)       │  │
│  │ body: String (RAW类型)                                     │  │
│  │ formParams: Map<String, String> (FORM类型)                 │  │
│  │ multipartBody: MultipartBody (MULTIPART类型)               │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌──────────────────────────────────────────────────────────────────┐
│  <<interface>>                                                   │
│                       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<String, String>                              │   │
│  │ bodyBytes: byte[] (统一存储)                               │   │
│  │                                                           │   │
│  │ + getBodyAsString(): String (UTF-8)                       │   │
│  │ + getBodyAsString(Charset): String                        │   │
│  │ + getBodyAsBytes(): byte[]                                │   │
│  │ + getContentLength(): long                                │   │
│  │ + isSuccessful(): boolean (2xx判断)                        │   │
│  └───────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘

🚀 快速开始

引入依赖

通过 JitPack 引入此库，将以下仓库和依赖添加到您的 pom.xml 中：

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
    <groupId>com.github.mr-box</groupId>
    <artifactId>easy-http</artifactId>
    <version>Tag</version> <!-- 请替换为最新的Release Tag, 例如 1.0.0 -->
</dependency>

使用示例

详细的使用示例请参考

• HttpClientExecutorExample.java
• IntegrationPropertyTest.java

⚙️ 配置说明

可以通过 HttpConfig 类进行各项配置，例如超时、连接池大小、重试策略、代理配置等。

详细的配置示例请参考 ConfigExample.java

🤝 贡献

欢迎通过 Pull Request 提交代码、报告 Bug 或提出建议。

请先阅读 贡献指南 了解详细的贡献流程和代码规范。

📄 许可证

本项目采用 Apache 2.0 许可证。

---

⭐ 如果这个项目对您有帮助，请给个 Star！