# vizaizai/easy-http architecture

> Architecture diagram of the GitHub repository vizaizai/easy-http, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vizaizai/easy-http
- Repository: https://github.com/vizaizai/easy-http

## Overview

##### Project Type & Purpose
- This is a Java-based, annotation-driven HTTP client library (“easy-http”) offering:
- A declarative interface/annotation layer for defining REST calls
- Pluggable HTTP client implementations (Java URL, Apache HttpClient, custom)
- Pluggable encoders/decoders, interceptors, retry logic, async support

##### High-Level Architecture Components
a. Client Facade & Builder
- EasyHttp.builder(): collects configuration (base URL, client impl, encoder, decoder, retry rules, interceptors)
- Produces a dynamic proxy instance of the user’s annotated interface (e.g., BookHttpService)
b. Annotation & Parser Layer
- Com.github.vizaizai.annotation: declares @Get, @Post, @Var, @Param, @Body, @Headers, etc.
- com.github.vizaizai.parser (InterfaceParser, MethodParser, ArgsParser): introspects interface and method annotations at runtime to build MappingInfo
c. Proxy & Invocation Handling
- com.github.vizaizai.proxy.JDKProxy + ProxyHandler: intercepts method calls, looks up MappingInfo, assembles HttpRequest
d. Request/Response Entity Model
- com.github.vizaizai.entity.HttpRequest, HttpResponse, HttpRequestConfig, MappingInfo, RetrySettings
- com.github.vizaizai.entity.body and form packages for multipart, binary, form-data
e. Handler Chain (Chain-of-Responsibility)
- com.github.vizaizai.hander: sequence of handlers (RequestHandler, MappingProcessor, RetryHandler, AsyncHttpHandler, ResponseHandler)
- Each handler takes Context (carries HttpRequest/HttpResponse)
f. Interceptor Layer
- com.github.vizaizai.interceptor.HttpInterceptor, ErrorInterceptor, LogInterceptor, custom interceptors
- InterceptorExecutor applies preHandle/postHandle around the handler chain
g. Codec Strategy (Strategy Pattern)
- com.github.vizaizai.codec.Encoder/Decoder interfaces with built-in JacksonEncoder/Decoder or custom implementations
h. HTTP Client Adapter (Adapter Pattern)
- AbstractClient → DefaultURLClient, ApacheHttpClient (and nested apache BodyEntity, HttpDeleteWithBody)
- Responsible for actual network I/O (synchronous or asynchronous via CompletableFuture)
i. Retry Mechanism
- com.github.vizaizai.retry.DefaultRule, RetryLimiter, RetryTrigger: controls retry policy and triggers
j. Utilities & Exceptions
- com.github.vizaizai.util for common helpers; com.github.vizaizai.exception for error handling

##### Relationships & Data Flow
1. Client code calls proxy instance of annotated service interface
2. JDKProxy/ProxyHandler uses parser output (MappingInfo) + method arguments to build HttpRequest
3. Interceptor preHandle chain
4. Handler chain:
- MappingProcessor → populates URL, path variables, query params, headers
- Encoder → serializes @Body or @Param into request body
- RetryHandler → applies retry logic if configured
- AsyncHttpHandler (if return type is Future/CompletableFuture)
- Underlying client adapter sends request → returns raw HttpResponse
- Decoder → deserializes response into return type
- ResponseHandler → final processing
5. Interceptor postHandle chain
6. Return final object to client code or Future

##### Architectural Patterns & Principles
- Builder Pattern (EasyHttp.builder())
- Proxy Pattern (dynamic JDK proxy implementing user interface)
- Strategy Pattern (Encoder/Decoder, RetryTrigger, HttpInterceptor)
- Chain-of-Responsibility (handler chain, interceptor chain)
- Adapter Pattern (AbstractClient to multiple HTTP implementations)
- Single Responsibility & Open-Closed for extensibility (clients, codecs, interceptors, retry rules)

##### Detailed Element Checklist
- Interfaces and extension points clearly marked (Encoder, Decoder, HttpInterceptor, AbstractClient)
- The builder façade shown at top connecting to proxy generator
- Handler chain & interceptor chain drawn sequentially
- Client adapter branching into multiple implementations
- External HTTP server depicted as the remote endpoint

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        AnnotationLayer["Annotation Layer"]:::blue
    end

    subgraph "Client Facade & Proxy"
        Builder["EasyHttp.builder()"]:::blue
        Proxy["JDKProxy & ProxyHandler"]:::blue
    end

    subgraph "Parser Layer"
        Parser["Parser Layer"]:::green
    end

    subgraph "Handler & Interceptor Layer"
        Interceptor["Interceptor Chain"]:::green
        HandlerChain["Handler Chain"]:::green
    end

    subgraph "Client Adapter Layer"
        Adapter["AbstractClient"]:::orange
        URLClient["DefaultURLClient"]:::orange
        ApacheClient["ApacheHttpClient"]:::orange
    end

    subgraph "Network & External"
        HTTPServer[(Remote HTTP Server)]:::orange
    end

    subgraph "Entity/Model & Extensions"
        Entity["HttpRequest/HttpResponse Model"]:::purple
        Codec["Codec Strategy"]:::purple
        Retry["Retry Mechanism"]:::purple
        Util["Utilities"]:::purple
        Excep["Exceptions"]:::purple
    end

    AnnotationLayer -->|"define annotations"| Parser
    Builder -->|"configure & build proxy"| Proxy
    Proxy -->|"invoke methods"| Parser
    Parser -->|"build MappingInfo"| Entity
    Entity -->|"create HttpRequest"| HandlerChain
    HandlerChain -->|"apply pre/postHandle"| Interceptor
    Interceptor -->|"proceed to handlers"| HandlerChain
    HandlerChain -->|"serialize body"| Codec
    HandlerChain -->|"check retry rules"| Retry
    HandlerChain -->|"dispatch request"| Adapter
    Adapter -->|"send HTTP"| HTTPServer
    HTTPServer -->|"return raw response"| Adapter
    Adapter -->|"wrap response"| HandlerChain
    HandlerChain -->|"deserialize response"| Codec
    HandlerChain -->|"finalize response"| Entity
    Entity -->|"return result"| Proxy

    URLClient --> Adapter
    ApacheClient --> Adapter

    click Builder "https://github.com/vizaizai/easy-http/blob/master/src/main/java/com/github/vizaizai/EasyHttp.java"
    click AnnotationLayer "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/annotation"
    click Parser "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/parser"
    click Proxy "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/proxy"
    click Entity "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/entity"
    click HandlerChain "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/hander"
    click Interceptor "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/interceptor"
    click Codec "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/codec"
    click Adapter "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/client"
    click ApacheClient "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/client/apache"
    click Retry "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/retry"
    click Util "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/util"
    click Excep "https://github.com/vizaizai/easy-http/tree/master/src/main/java/com/github/vizaizai/exception"

    classDef blue fill:#cce5ff,stroke:#004085,color:#004085
    classDef green fill:#d4edda,stroke:#155724,color:#155724
    classDef orange fill:#fff3cd,stroke:#856404,color:#856404
    classDef purple fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
