java-guide（Java 指南）

Java Guide

Applies to: Java 17+, Spring Boot, Maven/Gradle, Enterprise Applications

Core Principles

1. Immutability by Default: Prefer records, final fields, and unmodifiable collections
2. Explicit Over Implicit: Clear type declarations, no raw types, no unchecked casts
3. Fail Fast: Validate inputs at boundaries, use Objects.requireNonNull liberally
4. Composition Over Inheritance: Favor delegation and interfaces over deep class hierarchies
5. Standard Library First: Use java.util, java.time, java.nio before adding dependencies

Guardrails

Version & Dependencies

• Use Java 17+ (LTS) with preview features disabled in production
• Manage dependencies with Maven (pom.xml) or Gradle (build.gradle.kts)
• Pin dependency versions explicitly (no dynamic versions like 1.+)
• Run mvn dependency:analyze or gradle dependencies to detect unused/undeclared deps
• Check for vulnerabilities: mvn org.owasp:dependency-check-maven:check

Code Style

• Follow Google Java Style Guide
• Classes: PascalCase | Methods/fields: camelCase | Constants: UPPER_SNAKE_CASE
• Packages: com.company.project.module (lowercase, no underscores)
• One top-level class per file (name matches filename)
• Use var for local variables only when the type is obvious from the right side
• No wildcard imports (import java.util.* is forbidden)

Records & Sealed Classes

• Use record for immutable data carriers instead of manual POJOs
• Use sealed classes/interfaces for restricted type hierarchies
• Add compact constructors for validation in records
• Sealed classes enable exhaustive switch expressions with pattern matching

public record UserId(String value) {
    public UserId {
        Objects.requireNonNull(value, "UserId must not be null");
        if (value.isBlank()) {
            throw new IllegalArgumentException("UserId must not be blank");
        }
    }
}

public sealed interface PaymentResult
        permits PaymentResult.Success, PaymentResult.Declined, PaymentResult.Error {
    record Success(String transactionId, BigDecimal amount) implements PaymentResult {}
    record Declined(String reason) implements PaymentResult {}
    record Error(Exception cause) implements PaymentResult {}
}

Streams & Optional

• Use streams for transformations, not for side effects
• Never call Optional.get() -- use orElseThrow(), orElse(), map(), flatMap()
• Do not use Optional as a method parameter or field type (only as a return type)
• Avoid parallel streams unless measured to be faster (overhead is real)
• Prefer toList() (Java 16+) over collect(Collectors.toList())

List<String> activeEmails = users.stream()
        .filter(User::isActive)
        .map(User::email)
        .toList();

String displayName = userRepository.findById(id)
        .map(User::displayName)
        .orElseThrow(() -> new UserNotFoundException(id));

Resource Management

• Always use try-with-resources for AutoCloseable types
• Never rely on finalize() (deprecated and unreliable)
• Close resources in reverse order of acquisition

try (var connection = dataSource.getConnection();
     var statement = connection.prepareStatement(sql);
     var resultSet = statement.executeQuery()) {
    while (resultSet.next()) {
        results.add(mapRow(resultSet));
    }
}

Project Structure

myproject/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/com/company/project/
│   │   │   ├── Application.java        # Entry point
│   │   │   ├── config/                  # Configuration classes
│   │   │   ├── controller/              # REST controllers / API layer
│   │   │   ├── service/                 # Business logic
│   │   │   ├── repository/              # Data access
│   │   │   ├── model/                   # Domain entities and records
│   │   │   ├── dto/                     # Data transfer objects (records)
│   │   │   └── exception/               # Custom exceptions
│   │   └── resources/
│   │       ├── application.yml
│   │       └── db/migration/            # Flyway/Liquibase migrations
│   └── test/java/com/company/project/   # Mirrors main structure
└── target/                              # Build output (gitignored)

• Packages map to bounded contexts (not technical layers at the top)
• Test structure mirrors source structure
• Keep resources/ flat; use db/migration/ for schema changes

Key Patterns

Sealed Classes with Pattern Matching

public static double area(Shape shape) {
    return switch (shape) {
        case Shape.Circle c -> Math.PI * c.radius() * c.radius();
        case Shape.Rectangle r -> r.width() * r.height();
        case Shape.Triangle t -> 0.5 * t.base() * t.height();
    };
}

Immutable Collections

List<String> roles = List.of("ADMIN", "USER", "GUEST");
Map<String, String> config = Map.ofEntries(
        Map.entry("host", "localhost"),
        Map.entry("port", "8080"));
List<Item> snapshot = List.copyOf(mutableList);

Text Blocks

String query = """
        SELECT u.id, u.email, u.created_at
        FROM users u
        WHERE u.active = true
        ORDER BY u.created_at DESC
        LIMIT ?
        """;

Optional Chaining

// Fallback chain: cache -> database -> remote
User user = cache.findUser(id)
        .or(() -> database.findUser(id))
        .or(() -> remoteService.fetchUser(id))
        .orElseThrow(() -> new UserNotFoundException(id));

// Conditional execution without get()
userRepository.findById(userId)
        .ifPresentOrElse(
            u -> log.info("Found user: {}", u.name()),
            () -> log.warn("User {} not found", userId));

Testing

Standards

• Test files mirror source under src/test/java
• Test class names: ClassNameTest (not TestClassName)
• Test methods: @Test void shouldDescribeBehavior()
• Use @DisplayName for complex scenarios, @Nested to group related tests
• Coverage target: >80% for business logic, >60% overall
• Prefer AssertJ over JUnit assertions for readability

Basic Test Structure

class UserServiceTest {

    private UserRepository userRepository;
    private UserService userService;

    @BeforeEach
    void setUp() {
        userRepository = mock(UserRepository.class);
        userService = new UserService(userRepository);
    }

    @Test
    void shouldReturnUserWhenFound() {
        var expected = new User("1", "alice@example.com", "Alice");
        when(userRepository.findById("1")).thenReturn(Optional.of(expected));

        User result = userService.getUser("1");

        assertThat(result).isEqualTo(expected);
        verify(userRepository).findById("1");
    }

    @Test
    void shouldThrowWhenUserNotFound() {
        when(userRepository.findById("999")).thenReturn(Optional.empty());

        assertThatThrownBy(() -> userService.getUser("999"))
                .isInstanceOf(UserNotFoundException.class)
                .hasMessageContaining("999");
    }
}

Parameterized Tests

@ParameterizedTest
@CsvSource({
    "alice@example.com, true",
    "bob@test.org, true",
    "invalid-email, false",
    "'', false",
})
void shouldValidateEmail(String email, boolean expected) {
    assertThat(EmailValidator.isValid(email)).isEqualTo(expected);
}

@ParameterizedTest
@MethodSource("provideMoneyAdditions")
void shouldAddMoneySameCurrency(Money a, Money b, Money expected) {
    assertThat(a.add(b)).isEqualTo(expected);
}

static Stream<Arguments> provideMoneyAdditions() {
    var usd = Currency.getInstance("USD");
    return Stream.of(
        Arguments.of(new Money(BigDecimal.ONE, usd),
                      new Money(BigDecimal.TEN, usd),
                      new Money(new BigDecimal("11"), usd))
    );
}

Tooling

Maven Commands

mvn clean install              # Build and install locally
mvn test                       # Run all tests
mvn verify                     # Run tests + integration tests
mvn dependency:tree            # Show dependency tree
mvn dependency:analyze         # Find unused/undeclared deps
mvn spotbugs:check             # Static analysis
mvn checkstyle:check           # Style check

Gradle Commands

./gradlew build                # Full build with tests
./gradlew test                 # Run unit tests
./gradlew check                # Run all verification tasks
./gradlew dependencies         # Show dependency tree
./gradlew jacocoTestReport     # Generate coverage report

References

For detailed patterns and examples, see:

• references/patterns.md -- Spring patterns, Stream API recipes, Optional chaining, builder patterns

External References

• Google Java Style Guide
• Effective Java (3rd Edition) -- Joshua Bloch
• Java Records (JEP 395)
• Sealed Classes (JEP 409)
• Pattern Matching for switch (JEP 441)
• JUnit 5 User Guide
• AssertJ Documentation
• SpotBugs
• Checkstyle