Best Practice khi viết Common Library trong Java

mkdir audit-client && cd audit-client
gradle init --type java-library --dsl kotlin

plugins {
    `java-library`
    `maven-publish`
}

group = "com.example"
version = "0.1.0-SNAPSHOT"

java {
    toolchain { languageVersion = JavaLanguageVersion.of(17) }
    withSourcesJar()
}

repositories { mavenCentral() }

dependencies {
    compileOnly("org.slf4j:slf4j-api:2.0.13")
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
    testImplementation("org.slf4j:slf4j-simple:2.0.13")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test { useJUnitPlatform() }

publishing {
    publications {
        create<MavenPublication>("maven") { from(components["java"]) }
    }
}

// src/main/java/com/example/audit/AuditClient.java
public interface AuditClient {
    void send(AuditEvent event);
}

// src/main/java/com/example/audit/AuditEvent.java
public record AuditEvent(String actorId, String action, String resourceId) {}

// Nếu đây trông awkward khi viết, API cần redesign trước khi đi tiếp
AuditEvent event = new AuditEvent("user-1", "CREATE", "order-42");
client.send(event);

// src/main/java/com/example/audit/DefaultAuditClient.java
public class DefaultAuditClient implements AuditClient {
    private final String endpoint;
    private final HttpClient http = HttpClient.newHttpClient();
    private final ObjectMapper mapper = new ObjectMapper();

    public DefaultAuditClient(String endpoint) {
        this.endpoint = Objects.requireNonNull(endpoint, "endpoint must not be null");
    }

    @Override
    public void send(AuditEvent event) {
        try {
            var body = mapper.writeValueAsString(event);
            var request = HttpRequest.newBuilder()
                .uri(URI.create(endpoint + "/events"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();
            http.send(request, HttpResponse.BodyHandlers.discarding());
        } catch (Exception e) {
            throw new RuntimeException("Failed to send audit event", e);
        }
    }
}

class AuditClientTest {

    private MockWebServer server;
    private AuditClient client; // dùng interface, không dùng DefaultAuditClient

    @BeforeEach
    void setUp() throws IOException {
        server = new MockWebServer();
        server.start();
        client = new DefaultAuditClient(server.url("/").toString());
    }

    @AfterEach
    void tearDown() throws IOException { server.shutdown(); }

    @Test
    void sendsEventToEndpoint() throws InterruptedException {
        server.enqueue(new MockResponse().setResponseCode(200));

        client.send(new AuditEvent("user-1", "CREATE", "order-42"));

        RecordedRequest req = server.takeRequest();
        assertThat(req.getPath()).isEqualTo("/events");
        assertThat(req.getBody().readUtf8()).contains("user-1");
    }
}

./gradlew publishToMavenLocal

// build.gradle.kts của consumer
repositories {
    mavenLocal()  // tìm trong ~/.m2 trước
    mavenCentral()
}

dependencies {
    implementation("com.example:audit-client:0.1.0-SNAPSHOT")
}

audit-client/
├── audit-client-core/          # pure Java, zero framework dependency
├── audit-client-spring/        # Spring-specific adapters (optional dep on Spring)
├── audit-client-spring-boot-starter/ # auto-configuration
├── audit-client-quarkus/       # Quarkus CDI extension
└── audit-client-bom/           # Bill of Materials for version management

// build.gradle.kts của audit-client-core
dependencies {
    // API: nằm trong public signature, consumer cần compile dependency này
    api("com.fasterxml.jackson.core:jackson-databind:2.17.0")

    // Implementation: dùng nội bộ, không lộ ra public API
    // Consumer không thấy, không conflict
    implementation("org.apache.httpcomponents.client5:httpclient5:5.3.1")

    // CompileOnly: dùng lúc compile, không có trong runtime jar
    // Dùng cho annotation processors, annotation-only deps
    compileOnly("org.jetbrains:annotations:24.1.0")

    // Provided (Gradle: compileOnly + runtimeOnly của consumer)
    // Framework deps mà consumer đã có sẵn
    compileOnly("org.slf4j:slf4j-api:2.0.13") // consumer chọn implementation

    // Test dependencies không bao giờ leak ra production
    testImplementation("org.junit.jupiter:junit-jupiter:5.10.2")
    testImplementation("org.mockito:mockito-core:5.11.0")
}

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.13</version>
    <scope>provided</scope> <!-- không leak vào consumer -->
</dependency>

<dependency>
    <groupId>org.apache.httpcomponents.client5</groupId>
    <artifactId>httpclient5</artifactId>
    <version>5.3.1</version>
    <optional>true</optional> <!-- consumer phải opt-in explicitly -->
</dependency>

<!-- audit-client-bom/pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>audit-client-core</artifactId>
            <version>${project.version}</version>
        </dependency>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>audit-client-spring-boot-starter</artifactId>
            <version>${project.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

implementation(platform("com.example:audit-client-bom:1.2.0"))
implementation("com.example:audit-client-spring-boot-starter") // version tự động từ BOM

// audit-client-core/src/main/java/com/example/audit/
// ┣ AuditClient.java         ← public, đây là API
// ┣ AuditEvent.java          ← public, consumer tạo event
// ┣ AuditConfig.java         ← public, consumer configure
// ┗ internal/
//   ┣ HttpAuditSender.java   ← package-private, implementation detail
//   ┣ RetryPolicy.java       ← package-private
//   ┗ EventSerializer.java   ← package-private

// Internal class: package-private, consumer không thể depend vào
class HttpAuditSender implements AuditSender {
    // implementation detail, có thể thay đổi tự do
}

// Public API: interface, stable contract
public interface AuditClient {
    void send(AuditEvent event);
    CompletableFuture<Void> sendAsync(AuditEvent event);
}

// Public interface - consumer có thể mock trong tests, hoặc implement custom sender
public interface AuditClient {
    void send(AuditEvent event);
    CompletableFuture<Void> sendAsync(AuditEvent event);

    // Default method: thêm vào interface mà không break backward compat
    default void sendBatch(List<AuditEvent> events) {
        events.forEach(this::send);
    }
}

// AuditEvent là immutable - consumer không thể accidentally modify sau khi send
public record AuditEvent(
    String actorId,
    String action,
    String resourceType,
    String resourceId,
    Instant occurredAt,
    Map<String, String> metadata
) {
    // Compact constructor: validate tại đây, một lần, không phải ở mọi nơi dùng
    public AuditEvent {
        Objects.requireNonNull(actorId, "actorId must not be null");
        Objects.requireNonNull(action, "action must not be null");
        Objects.requireNonNull(resourceType, "resourceType must not be null");
        Objects.requireNonNull(resourceId, "resourceId must not be null");
        Objects.requireNonNull(occurredAt, "occurredAt must not be null");
        // Defensive copy của mutable map
        metadata = metadata != null
            ? Map.copyOf(metadata)
            : Map.of();
    }

    // Builder cho ergonomic API
    public static Builder builder() { return new Builder(); }

    public static final class Builder {
        private String actorId;
        private String action;
        private String resourceType;
        private String resourceId;
        private Instant occurredAt = Instant.now(); // sensible default
        private final Map<String, String> metadata = new LinkedHashMap<>();

        public Builder actorId(String actorId) {
            this.actorId = actorId; return this;
        }
        public Builder action(String action) {
            this.action = action; return this;
        }
        public Builder resourceType(String resourceType) {
            this.resourceType = resourceType; return this;
        }
        public Builder resourceId(String resourceId) {
            this.resourceId = resourceId; return this;
        }
        public Builder metadata(String key, String value) {
            this.metadata.put(key, value); return this;
        }
        public AuditEvent build() {
            return new AuditEvent(actorId, action, resourceType,
                resourceId, occurredAt, metadata);
        }
    }
}

// Exhaustive error hierarchy - consumer biết chính xác những lỗi có thể xảy ra
public sealed interface AuditException permits
    AuditException.ConnectionFailed,
    AuditException.EventRejected,
    AuditException.Unauthorized {

    record ConnectionFailed(String endpoint, Throwable cause) implements AuditException {}
    record EventRejected(String reason, AuditEvent event) implements AuditException {}
    record Unauthorized(String message) implements AuditException {}
}

try {
    auditClient.send(event);
} catch (AuditRuntimeException ex) {
    switch (ex.getError()) {
        case AuditException.ConnectionFailed cf ->
            log.warn("Audit service unreachable: {}", cf.endpoint());
        case AuditException.EventRejected er ->
            log.error("Invalid event: {}", er.reason());
        case AuditException.Unauthorized u ->
            alertSecurityTeam(u.message());
    }
}

// BAD: config được truyền vào nhưng không validate
public class DefaultAuditClient implements AuditClient {
    private final String endpoint;
    private final int timeoutMs;

    public DefaultAuditClient(String endpoint, int timeoutMs) {
        this.endpoint = endpoint; // null? empty? invalid URL?
        this.timeoutMs = timeoutMs; // negative? zero?
    }

    public void send(AuditEvent event) {
        // NullPointerException hoặc MalformedURLException xảy ra
        // khi send() được gọi lần đầu, không phải khi khởi tạo
        // Stack trace không chỉ ra lỗi ở đâu trong config
        httpClient.post(endpoint, event);
    }
}

public final class AuditConfig {
    private final URI endpoint;
    private final Duration connectTimeout;
    private final Duration requestTimeout;
    private final int maxRetries;
    private final boolean asyncMode;

    private AuditConfig(Builder builder) {
        this.endpoint       = builder.endpoint;
        this.connectTimeout = builder.connectTimeout;
        this.requestTimeout = builder.requestTimeout;
        this.maxRetries     = builder.maxRetries;
        this.asyncMode      = builder.asyncMode;
    }

    public static Builder builder(String endpoint) {
        return new Builder(endpoint);
    }

    public static final class Builder {
        private final URI endpoint;
        private Duration connectTimeout = Duration.ofSeconds(5);  // sensible default
        private Duration requestTimeout = Duration.ofSeconds(10); // sensible default
        private int maxRetries = 3;         // sensible default
        private boolean asyncMode = false;  // safe default

        public Builder(String endpoint) {
            // Validate ngay tại đây
            Objects.requireNonNull(endpoint, "endpoint must not be null");
            if (endpoint.isBlank()) throw new IllegalArgumentException("endpoint must not be blank");
            try {
                this.endpoint = URI.create(endpoint);
                if (!this.endpoint.isAbsolute()) {
                    throw new IllegalArgumentException("endpoint must be an absolute URI: " + endpoint);
                }
            } catch (IllegalArgumentException e) {
                throw new AuditConfigException("Invalid endpoint URI: " + endpoint, e);
            }
        }

        public Builder connectTimeout(Duration timeout) {
            if (timeout == null || timeout.isNegative() || timeout.isZero())
                throw new IllegalArgumentException("connectTimeout must be positive");
            this.connectTimeout = timeout;
            return this;
        }

        public Builder maxRetries(int retries) {
            if (retries < 0) throw new IllegalArgumentException("maxRetries must be >= 0");
            this.maxRetries = retries;
            return this;
        }

        public AuditConfig build() {
            // Cross-field validation
            if (connectTimeout.compareTo(requestTimeout) > 0) {
                throw new AuditConfigException(
                    "connectTimeout must not exceed requestTimeout");
            }
            return new AuditConfig(this);
        }
    }
}

// Exception xảy ra tại đây khi application khởi động
AuditConfig config = AuditConfig.builder("not-a-valid-url")
    .connectTimeout(Duration.ofSeconds(5))
    .build(); // AuditConfigException: Invalid endpoint URI

// CORRECT: SLF4J facade - không có implementation nào được chọn
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

class HttpAuditSender {
    private static final Logger log = LoggerFactory.getLogger(HttpAuditSender.class);

    public void send(AuditEvent event) {
        log.debug("Sending audit event: action={}, resource={}/{}",
            event.action(), event.resourceType(), event.resourceId());
        // ...
        log.info("Audit event sent successfully in {}ms", durationMs);
    }
}

// WRONG: library cấu hình logging của consumer
static {
    // Library không được làm điều này
    LoggerContext ctx = (LoggerContext) LogManager.getContext(false);
    ctx.getConfiguration().addAppender(new ConsoleAppender(...));
}

public final class DefaultAuditClient implements AuditClient {
    // HttpClient của Java 11+ là thread-safe
    private final HttpClient httpClient;
    // ObjectMapper của Jackson là thread-safe sau khi configured
    private final ObjectMapper objectMapper;
    // Immutable sau khi constructed
    private final AuditConfig config;
    // AtomicLong: thread-safe counter
    private final AtomicLong eventsSent = new AtomicLong();

    // Constructor: thiết lập xong là immutable. Thread-safe ngay từ đầu.
    public DefaultAuditClient(AuditConfig config) {
        this.config = Objects.requireNonNull(config);
        this.httpClient = HttpClient.newBuilder()
            .connectTimeout(config.connectTimeout())
            .build();
        this.objectMapper = new ObjectMapper()
            .registerModule(new JavaTimeModule())
            .configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
            // Sau configure xong, ObjectMapper là effectively immutable và thread-safe
    }

    @Override
    public void send(AuditEvent event) {
        // No shared mutable state modified here
        // Mọi state đều local hoặc thread-safe
        String body = serialize(event);
        executeWithRetry(body, config.maxRetries());
        eventsSent.incrementAndGet(); // AtomicLong: thread-safe
    }
}

/**
 * Thread-safe implementation of {@link AuditClient}.
 *
 * <p>Instances are safe for use by multiple concurrent threads.
 * A single instance should be created and reused for the lifetime of the application.
 *
 * <p>Creating multiple instances per request is wasteful and may exhaust
 * connection pool resources.
 */
public final class DefaultAuditClient implements AuditClient { ... }

audit-client-spring-boot-starter/
├── src/main/java/com/example/audit/autoconfigure/
│   ├── AuditClientAutoConfiguration.java
│   └── AuditClientProperties.java
└── src/main/resources/META-INF/spring/
    └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

com.example.audit.autoconfigure.AuditClientAutoConfiguration

@ConfigurationProperties(prefix = "audit.client")
@Validated
public class AuditClientProperties {

    @NotBlank
    private String endpoint;

    @DurationUnit(ChronoUnit.MILLIS)
    private Duration connectTimeout = Duration.ofSeconds(5);

    @DurationUnit(ChronoUnit.MILLIS)
    private Duration requestTimeout = Duration.ofSeconds(10);

    @Min(0) @Max(10)
    private int maxRetries = 3;

    private boolean enabled = true;

    // getters và setters
}

@AutoConfiguration
@ConditionalOnClass(AuditClient.class)          // chỉ activate khi library có trên classpath
@ConditionalOnProperty(
    prefix = "audit.client",
    name = "enabled",
    havingValue = "true",
    matchIfMissing = true                        // default enabled, opt-out với enabled=false
)
@EnableConfigurationProperties(AuditClientProperties.class)
public class AuditClientAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(AuditClient.class) // consumer có thể override
    public AuditClient auditClient(AuditClientProperties props) {
        AuditConfig config = AuditConfig.builder(props.getEndpoint())
            .connectTimeout(props.getConnectTimeout())
            .requestTimeout(props.getRequestTimeout())
            .maxRetries(props.getMaxRetries())
            .build();
        return new DefaultAuditClient(config);
    }

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnBean(AuditClient.class)
    public AuditEventPublisher auditEventPublisher(AuditClient auditClient) {
        return new DefaultAuditEventPublisher(auditClient);
    }
}

// src/main/resources/META-INF/spring-configuration-metadata.json
{
  "properties": [
    {
      "name": "audit.client.endpoint",
      "type": "java.lang.String",
      "description": "URL of the audit service. Example: https://audit.internal.example.com"
    },
    {
      "name": "audit.client.max-retries",
      "type": "java.lang.Integer",
      "description": "Maximum number of retry attempts on transient failure.",
      "defaultValue": 3
    }
  ]
}

// audit-client-quarkus/src/main/java/com/example/audit/quarkus/
// AuditClientProducer.java
@ApplicationScoped
public class AuditClientProducer {

    @ConfigProperty(name = "audit.client.endpoint")
    String endpoint;

    @ConfigProperty(name = "audit.client.connect-timeout", defaultValue = "PT5S")
    Duration connectTimeout;

    @ConfigProperty(name = "audit.client.max-retries", defaultValue = "3")
    int maxRetries;

    @Produces
    @ApplicationScoped
    @DefaultBean // consumer override bằng cách inject @Alternative bean
    public AuditClient produceAuditClient() {
        AuditConfig config = AuditConfig.builder(endpoint)
            .connectTimeout(connectTimeout)
            .maxRetries(maxRetries)
            .build();
        return new DefaultAuditClient(config);
    }

    public void dispose(@Disposes AuditClient client) {
        if (client instanceof Closeable c) {
            try { c.close(); }
            catch (IOException e) { log.warn("Error closing AuditClient", e); }
        }
    }
}

audit.client.endpoint=https://audit.internal.example.com
audit.client.connect-timeout=PT5S
audit.client.max-retries=3

@QuarkusTest
class AuditClientIntegrationTest {

    @Inject
    AuditClient auditClient; // CDI inject

    @Test
    void shouldSendEvent() {
        AuditEvent event = AuditEvent.builder()
            .actorId("user-42")
            .action("CREATE")
            .resourceType("Order")
            .resourceId("ORD-001")
            .build();

        assertDoesNotThrow(() -> auditClient.send(event));
    }
}

// Dùng annotation để register class cần reflection
@RegisterForReflection(targets = {
    AuditEvent.class,
    AuditException.ConnectionFailed.class,
    AuditException.EventRejected.class,
    AuditException.Unauthorized.class
})
public class AuditClientReflectionConfig {}

// src/main/resources/META-INF/native-image/com.example/audit-client-core/reflect-config.json
[
  {
    "name": "com.example.audit.AuditEvent",
    "allDeclaredConstructors": true,
    "allDeclaredMethods": true,
    "allDeclaredFields": true
  }
]

// resource-config.json
{
  "resources": {
    "includes": [
      { "pattern": "audit-client.version" }
    ]
  }
}

@ImportRuntimeHints(AuditClientRuntimeHints.class)
public class AuditClientAutoConfiguration { ... }

class AuditClientRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection()
            .registerType(AuditEvent.class, MemberCategory.values())
            .registerType(AuditConfig.class, MemberCategory.values());
        hints.resources()
            .registerPattern("audit-client.version");
    }
}

@SpringBootTest
@EnabledIfSystemProperty(named = "spring.aot.processing", matches = "true")
class AuditClientNativeTest {
    @Test
    void contextLoads() { } // nếu context load được trong native, hints đúng
}

/**
 * @deprecated since 1.3.0, use {@link #sendAsync(AuditEvent)} instead.
 *             This method will be removed in 2.0.0.
 *             Migration: replace {@code send(event)} with
 *             {@code sendAsync(event).join()} for equivalent blocking behavior.
 */
@Deprecated(since = "1.3.0", forRemoval = true)
public void sendSync(AuditEvent event) {
    sendAsync(event).join();
}

// module-info.java trong audit-client-core
module com.example.audit.core {
    // Export package nào consumer được dùng
    exports com.example.audit;

    // Internal packages không export
    // com.example.audit.internal → không visible cho consumer

    requires org.slf4j;                    // compile-time và runtime
    requires static com.fasterxml.jackson; // optional, chỉ khi có trên classpath
}

// CORRECT: test qua public interface như consumer sẽ làm
class AuditClientTest {

    private MockWebServer mockServer; // WireMock hoặc MockWebServer
    private AuditClient client;

    @BeforeEach
    void setup() throws IOException {
        mockServer = new MockWebServer();
        mockServer.start();

        AuditConfig config = AuditConfig.builder(mockServer.url("/").toString())
            .maxRetries(1)
            .build();
        client = new DefaultAuditClient(config);
    }

    @Test
    void shouldRetryOnTransientFailure() throws InterruptedException {
        // Server trả về 503 lần đầu, 200 lần hai
        mockServer.enqueue(new MockResponse().setResponseCode(503));
        mockServer.enqueue(new MockResponse().setResponseCode(200));

        AuditEvent event = AuditEvent.builder()
            .actorId("user-1")
            .action("DELETE")
            .resourceType("Product")
            .resourceId("prod-42")
            .build();

        // Consumer không cần biết về retry internals
        assertDoesNotThrow(() -> client.send(event));
        assertThat(mockServer.getRequestCount()).isEqualTo(2);
    }
}

// Consumer test: mock AuditClient dễ dàng
@ExtendWith(MockitoExtension.class)
class OrderServiceTest {

    @Mock
    AuditClient auditClient; // mock interface, không phải concrete class

    @InjectMocks
    OrderService orderService;

    @Test
    void shouldAuditOrderCreation() {
        orderService.createOrder(orderRequest);
        verify(auditClient).send(argThat(event ->
            event.action().equals("CREATE") &&
            event.resourceType().equals("Order")
        ));
    }
}