How vizaizai/easy-http works
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