|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build Commands |
| 6 | + |
| 7 | +### Essential Build Commands |
| 8 | +- `mvn clean install` - Default build command (installs all modules) |
| 9 | +- `mvn clean install -Pdev` - **ALWAYS use this profile for development** - enables code formatting and other dev tools |
| 10 | +- `mvn clean install -Pquickbuild` - Skip tests and validation for faster builds |
| 11 | +- `mvn test` - Run all tests |
| 12 | +- `mvn test -Dtest=ClassName` - Run specific test class |
| 13 | + |
| 14 | +### Module-specific Commands |
| 15 | +- `mvn clean install -pl core` - Build only the core module |
| 16 | +- `mvn clean install -pl core,gson` - Build specific modules |
| 17 | +- `mvn clean test -pl core -Dtest=FeignTest` - Run specific test in specific module |
| 18 | + |
| 19 | +### Code Quality |
| 20 | +- Code is automatically formatted using Google Java Format via git hooks |
| 21 | +- License headers are enforced via maven-license-plugin |
| 22 | +- Use `mvn validate` to check formatting and license compliance |
| 23 | + |
| 24 | +## Project Architecture |
| 25 | + |
| 26 | +### Core Architecture |
| 27 | +Feign is a declarative HTTP client library with a modular design: |
| 28 | + |
| 29 | +**Core Module (`core/`)**: Contains the main Feign API and implementation |
| 30 | +- `Feign.java` - Main factory class for creating HTTP clients |
| 31 | +- `Client.java` - HTTP client abstraction (default implementation + pluggable alternatives) |
| 32 | +- `Contract.java` - Annotation processing interface (Default, JAX-RS, Spring contracts) |
| 33 | +- `Encoder/Decoder.java` - Request/response serialization interfaces |
| 34 | +- `Target.java` - Represents the remote HTTP service to invoke |
| 35 | +- `RequestTemplate.java` - Template for building HTTP requests with parameter substitution |
| 36 | +- `MethodMetadata.java` - Metadata about interface methods and their annotations |
| 37 | + |
| 38 | +**Integration Modules**: Each module provides integration with specific libraries: |
| 39 | +- `gson/`, `jackson/`, `fastjson2/` - JSON serialization |
| 40 | +- `okhttp/`, `httpclient/`, `hc5/`, `java11/` - HTTP client implementations |
| 41 | +- `jaxrs/`, `jaxrs2/`, `jaxrs3/` - JAX-RS annotation support |
| 42 | +- `spring/` - Spring MVC annotation support |
| 43 | +- `hystrix/` - Circuit breaker integration |
| 44 | +- `micrometer/`, `dropwizard-metrics4/5/` - Metrics integration |
| 45 | + |
| 46 | +### Key Design Patterns |
| 47 | +- **Builder Pattern**: `Feign.builder()` for configuring clients |
| 48 | +- **Factory Pattern**: `Feign.newInstance(Target)` creates proxy instances |
| 49 | +- **Strategy Pattern**: Pluggable `Client`, `Encoder`, `Decoder`, `Contract` implementations |
| 50 | +- **Template Method**: `RequestTemplate` for building HTTP requests with parameter substitution |
| 51 | +- **Proxy Pattern**: Dynamic proxies created for interface-based clients |
| 52 | + |
| 53 | +### Multi-module Maven Structure |
| 54 | +- Parent POM manages dependencies and common configuration |
| 55 | +- Each integration is a separate Maven module |
| 56 | +- Modules can be built independently: `mvn clean install -pl module-name` |
| 57 | +- Example modules depend on `feign-core` and their respective 3rd party libraries |
| 58 | + |
| 59 | +### Testing Strategy |
| 60 | +- `feign-core` contains `AbstractClientTest` base class for testing HTTP clients |
| 61 | +- Each module has its own test suite |
| 62 | +- Integration tests use MockWebServer for HTTP mocking |
| 63 | +- Tests are run with JUnit 5 and AssertJ assertions |
| 64 | + |
| 65 | +## Development Notes |
| 66 | + |
| 67 | +### Code Style |
| 68 | +- Google Java Format is enforced via git hooks |
| 69 | +- Code is formatted automatically on commit |
| 70 | +- Package-private visibility is preferred over public when possible |
| 71 | +- 3rd party dependencies are minimized in core module |
| 72 | + |
| 73 | +### Module Dependencies |
| 74 | +- Core module: Minimal dependencies (only what's needed for HTTP client abstraction) |
| 75 | +- Integration modules: Add specific 3rd party libraries (Jackson, OkHttp, etc.) |
| 76 | +- BOM (Bill of Materials) manages version consistency across modules |
| 77 | + |
| 78 | +### Java Version Support |
| 79 | +- Source/target: Java 8 (for `src/main`) |
| 80 | +- Tests: Java 21 (for `src/test`) |
| 81 | +- Maintains backwards compatibility with Java 8 in main codebase |
0 commit comments