Copilot instructions

1---
2applyTo: "**/src/main/java/**/*.java"
3---
4 
5## Context
6 
7This instruction file applies to all Spring Boot Java source files. The project uses Spring Boot 3.x as its baseline, which requires Java 17+ and the Jakarta EE namespace (`jakarta.*`). New microservices target Java 21 and should leverage virtual threads and modern language features where appropriate. This context layer does not apply to legacy Spring MVC modules — see `java-legacy.instructions.md` for those.
8 
9---
10 
11## Coding Standards
12 
13- **Java version baseline:** Java 17 minimum; prefer Java 21 features where the runtime supports them
14- **Namespace:** Always `jakarta.*` — never `javax.*` in Spring Boot 3.x code
15- **Records over POJOs:** Use Java records for immutable DTOs and value objects; reserve classes for mutable entities
16- **Text blocks:** Use `"""..."""` for multi-line SQL, JSON, or HTML strings
17- **Pattern matching:** Use `instanceof` pattern matching (`if (obj instanceof MyType t)`) — no explicit cast
18- **Sealed types:** Use sealed interfaces/classes to model closed domain hierarchies
19- **Switch expressions:** Use `switch` expressions with arrow syntax over `switch` statements
20- **Constructor injection only:** All Spring-managed beans use constructor injection; mark injected fields `final`
21- **No field `@Autowired`:** Never inject via `@Autowired` on a field — it hides dependencies and breaks testability
22- **`@ConfigurationProperties`:** All externalized config must use a typed `@ConfigurationProperties` class — no `@Value` on individual fields for grouped config
23- **`application.yml`:** Always YAML, never `.properties` format — structure config hierarchically
24 
25---
26 
27## Google Java Style Guide
28 
29All Java code must conform to the **Google Java Style Guide** (https://google.github.io/styleguide/javaguide.html). Key rules:
30 
31- **Indentation:** 2 spaces (not 4, not tabs) for Google style; continuation lines indented +4
32- **Column limit:** 100 characters per line
33- **Braces:** Egyptian style — opening brace on the same line, always use braces even for single-line `if`/`for`/`while` blocks
34- **Blank lines:** One blank line between class members; no blank lines after opening brace or before closing brace
35- **Import ordering:** Static imports first, then grouped by package, no wildcard imports
36- **Variable declarations:** One declaration per line; `var` is allowed for local variables where the type is obvious
37- **Annotations:** One annotation per line for class/method declarations
38- **Javadoc:** All `public` and `protected` members must have Javadoc; use `@param`, `@return`, `@throws`
39- **Naming:** See the naming rules in the global `copilot-instructions.md`; additionally: acronyms treated as words (`HttpUrl`, not `HTTPUrl`)
40- **`@Override`:** Always include `@Override` when a method overrides or implements
41 
42```java
43// CORRECT: Google Java Style
44public final class OrderService {
45 
46  private static final Logger log = LoggerFactory.getLogger(OrderService.class);
47 
48  private final OrderRepository orderRepository;
49  private final OrderMapper orderMapper;
50 
51  public OrderService(OrderRepository orderRepository, OrderMapper orderMapper) {
52    this.orderRepository = orderRepository;
53    this.orderMapper = orderMapper;
54  }
55 
56  /**
57   * Retrieves an order by its unique identifier.
58   *
59   * @param id the order UUID
60   * @return the order response DTO
61   * @throws OrderNotFoundException if no order exists with the given ID
62   */
63  public OrderResponse findById(UUID id) {
64    return orderRepository
65        .findById(id)
66        .map(orderMapper::toResponse)
67        .orElseThrow(() -> new OrderNotFoundException(id));
68  }
69}
70```
71 
72---
73 
74## Maven Best Practices
75 
76All Maven projects must follow these conventions:
77 
78### POM Structure
79 
80```xml
81<project xmlns="http://maven.apache.org/POM/4.0.0"
82    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
83    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
84  <modelVersion>4.0.0</modelVersion>
85 
86  <!-- Inherit Spring Boot BOM for dependency version management -->
87  <parent>
88    <groupId>org.springframework.boot</groupId>
89    <artifactId>spring-boot-starter-parent</artifactId>
90    <version>3.2.x</version>
91    <relativePath/>
92  </parent>
93 
94  <groupId>com.example</groupId>
95  <artifactId>my-service</artifactId>
96  <version>1.0.0-SNAPSHOT</version>
97  <packaging>jar</packaging>
98 
99  <properties>
100    <!-- Always pin Java version explicitly -->
101    <java.version>21</java.version>
102    <maven.compiler.source>${java.version}</maven.compiler.source>
103    <maven.compiler.target>${java.version}</maven.compiler.target>
104    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
105    <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
106    <!-- Library versions not managed by Spring BOM go here -->
107    <mapstruct.version>1.5.5.Final</mapstruct.version>
108    <testcontainers.version>1.19.x</testcontainers.version>
109  </properties>
110</project>
111```
112 
113### Dependency Rules
114 
115- **Use Spring Boot BOM** — never declare `<version>` for Spring Boot-managed dependencies
116- **No version in child modules** — all versions declared in parent's `<dependencyManagement>`
117- **Scope everything correctly:** `test` scope for test-only libs, `provided` for servlet-api in WAR
118- **No `LATEST` or `RELEASE` versions** — always pin exact versions
119- **Bill of Materials (BOM) imports** for multi-library stacks (Testcontainers, etc.)
120- **Dependency hygiene:** Run `mvn dependency:analyze` to find unused declared and undeclared used dependencies
121 
122### Required Maven Plugins
123 
124```xml
125<build>
126  <plugins>
127    <!-- Enforce minimum Maven and Java versions -->
128    <plugin>
129      <groupId>org.apache.maven.plugins</groupId>
130      <artifactId>maven-enforcer-plugin</artifactId>
131      <executions>
132        <execution>
133          <id>enforce</id>
134          <goals><goal>enforce</goal></goals>
135          <configuration>
136            <rules>
137              <requireMavenVersion><version>[3.9,)</version></requireMavenVersion>
138              <requireJavaVersion><version>[17,)</version></requireJavaVersion>
139              <dependencyConvergence/>
140              <banDuplicatePomDependencyVersions/>
141            </rules>
142          </configuration>
143        </execution>
144      </executions>
145    </plugin>
146 
147    <!-- Code coverage — enforce minimums -->
148    <plugin>
149      <groupId>org.jacoco</groupId>
150      <artifactId>jacoco-maven-plugin</artifactId>
151      <executions>
152        <execution>
153          <id>prepare-agent</id>
154          <goals><goal>prepare-agent</goal></goals>
155        </execution>
156        <execution>
157          <id>check</id>
158          <goals><goal>check</goal></goals>
159          <configuration>
160            <rules>
161              <rule>
162                <element>BUNDLE</element>
163                <limits>
164                  <limit>
165                    <counter>LINE</counter>
166                    <value>COVEREDRATIO</value>
167                    <minimum>0.80</minimum>
168                  </limit>
169                  <limit>
170                    <counter>BRANCH</counter>
171                    <value>COVEREDRATIO</value>
172                    <minimum>0.70</minimum>
173                  </limit>
174                </limits>
175              </rule>
176            </rules>
177          </configuration>
178        </execution>
179        <execution>
180          <id>report</id>
181          <goals><goal>report</goal></goals>
182        </execution>
183      </executions>
184    </plugin>
185 
186    <!-- SpotBugs static analysis -->
187    <plugin>
188      <groupId>com.github.spotbugs</groupId>
189      <artifactId>spotbugs-maven-plugin</artifactId>
190      <version>4.8.x</version>
191      <executions>
192        <execution>
193          <goals><goal>check</goal></goals>
194        </execution>
195      </executions>
196    </plugin>
197 
198    <!-- Checkstyle — enforce Google Java Style -->
199    <plugin>
200      <groupId>org.apache.maven.plugins</groupId>
201      <artifactId>maven-checkstyle-plugin</artifactId>
202      <version>3.3.x</version>
203      <configuration>
204        <configLocation>google_checks.xml</configLocation>
205        <failOnViolation>true</failOnViolation>
206        <violationSeverity>warning</violationSeverity>
207      </configuration>
208      <executions>
209        <execution>
210          <id>checkstyle</id>
211          <phase>verify</phase>
212          <goals><goal>check</goal></goals>
213        </execution>
214      </executions>
215    </plugin>
216 
217    <!-- OWASP Dependency-Check — flag known CVEs in dependencies -->
218    <plugin>
219      <groupId>org.owasp</groupId>
220      <artifactId>dependency-check-maven</artifactId>
221      <version>9.x</version>
222      <configuration>
223        <failBuildOnCVSS>7</failBuildOnCVSS>
224      </configuration>
225    </plugin>
226  </plugins>
227</build>
228```
229 
230### Maven Profiles
231 
232```xml
233<profiles>
234  <!-- Integration tests run separately from unit tests -->
235  <profile>
236    <id>integration-tests</id>
237    <build>
238      <plugins>
239        <plugin>
240          <groupId>org.apache.maven.plugins</groupId>
241          <artifactId>maven-failsafe-plugin</artifactId>
242          <executions>
243            <execution>
244              <goals>
245                <goal>integration-test</goal>
246                <goal>verify</goal>
247              </goals>
248            </execution>
249          </executions>
250        </plugin>
251      </plugins>
252    </build>
253  </profile>
254</profiles>
255```
256 
257---
258 
259## SonarLint / SonarQube Integration
260 
261All Java code is validated by SonarLint locally and SonarQube/SonarCloud in CI.
262 
263### SonarLint Local (VS Code)
264 
265The `sonarsource.sonarlint-vscode` extension is included in `.vscode/extensions.json`. SonarLint runs in real time. Rules to always resolve before committing:
266 
267- **Blocker / Critical rules:** Must be resolved — never suppress without written justification
268- **Major rules:** Resolve or create a ticket before PR
269- **`// NOSONAR`:** Only with a trailing comment explaining the rationale; never used to hide real defects
270 
271### SonarQube Maven Integration
272 
273```xml
274<!-- Add to parent pom.xml properties -->
275<sonar.java.source>21</sonar.java.source>
276<sonar.coverage.jacoco.xmlReportPaths>
277  ${project.build.directory}/site/jacoco/jacoco.xml
278</sonar.coverage.jacoco.xmlReportPaths>
279<sonar.exclusions>
280  **/generated/**,
281  **/*MapperImpl.java,
282  **/config/**
283</sonar.exclusions>
284```
285 
286Run local analysis:
287```bash
288mvn sonar:sonar \
289  -Dsonar.host.url=http://localhost:9000 \
290  -Dsonar.token=${SONAR_TOKEN}
291```
292 
293### SonarQube Quality Gate Thresholds (enforce in CI)
294 
295| Metric | Minimum |
296|--------|---------|
297| New code coverage | 80% |
298| New code duplications | < 3% |
299| New bugs | 0 |
300| New vulnerabilities | 0 |
301| New code smells (blocker/critical) | 0 |
302| Security hotspots reviewed | 100% |
303 
304---
305 
306## Preferred Patterns
307 
308### REST Controller
309 
310```java
311@RestController
312@RequestMapping("/api/v1/orders")
313@Tag(name = "Orders", description = "Order management endpoints")
314@RequiredArgsConstructor  // if Lombok is already on classpath; else write constructor manually
315public class OrderController {
316 
317    private final OrderService orderService;
318 
319    @GetMapping("/{id}")
320    @Operation(summary = "Retrieve an order by ID")
321    public ResponseEntity<OrderResponse> getOrder(@PathVariable UUID id) {
322        return ResponseEntity.ok(orderService.findById(id));
323    }
324 
325    @PostMapping
326    @ResponseStatus(HttpStatus.CREATED)
327    public OrderResponse createOrder(@Valid @RequestBody CreateOrderRequest request) {
328        return orderService.create(request);
329    }
330}
331```
332 
333### Exception Handling (RFC 7807 ProblemDetail)
334 
335```java
336@RestControllerAdvice
337public class GlobalExceptionHandler {
338 
339    @ExceptionHandler(OrderNotFoundException.class)
340    public ProblemDetail handleOrderNotFound(OrderNotFoundException ex) {
341        ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
342        problem.setTitle("Order Not Found");
343        return problem;
344    }
345 
346    @ExceptionHandler(MethodArgumentNotValidException.class)
347    public ProblemDetail handleValidation(MethodArgumentNotValidException ex) {
348        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.UNPROCESSABLE_ENTITY);
349        problem.setTitle("Validation Failed");
350        problem.setProperty("violations", ex.getBindingResult().getFieldErrors()
351            .stream().map(e -> e.getField() + ": " + e.getDefaultMessage()).toList());
352        return problem;
353    }
354}
355```
356 
357### Spring Data JPA Repository
358 
359```java
360public interface OrderRepository extends JpaRepository<Order, UUID> {
361 
362    List<Order> findByCustomerIdAndStatus(UUID customerId, OrderStatus status);
363 
364    @Query("SELECT o FROM Order o JOIN FETCH o.lineItems WHERE o.id = :id")
365    Optional<Order> findByIdWithLineItems(@Param("id") UUID id);
366 
367    Page<Order> findByCreatedAtAfter(Instant cutoff, Pageable pageable);
368}
369```
370 
371### Spring Security 6.x Configuration
372 
373```java
374@Configuration
375@EnableMethodSecurity
376public class SecurityConfig {
377 
378    @Bean
379    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
380        return http
381            .csrf(AbstractHttpConfigurer::disable)
382            .authorizeHttpRequests(auth -> auth
383                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
384                .requestMatchers("/api/**").authenticated()
385                .anyRequest().denyAll()
386            )
387            .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
388            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
389            .build();
390    }
391}
392```
393 
394### Typed Configuration Properties
395 
396```java
397@ConfigurationProperties(prefix = "app.payment")
398public record PaymentProperties(
399    String gatewayUrl,
400    Duration timeout,
401    int maxRetries
402) {}
403```
404 
405```yaml
406# application.yml
407app:
408  payment:
409    gateway-url: https://payment.example.com
410    timeout: 30s
411    max-retries: 3
412```
413 
414### Java 21 Virtual Threads
415 
416```java
417@Bean
418public TomcatProtocolHandlerCustomizer<?> virtualThreadsCustomizer() {
419    return handler -> handler.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
420}
421```
422 
423---
424 
425## Anti-Patterns — Do NOT Generate
426 
427```java
428// WRONG: field injection
429@Autowired
430private OrderService orderService;
431 
432// WRONG: javax namespace in Spring Boot 3
433import javax.persistence.Entity;
434 
435// WRONG: WebSecurityConfigurerAdapter (removed in Spring Security 6)
436public class SecurityConfig extends WebSecurityConfigurerAdapter { ... }
437 
438// WRONG: @Value on individual fields for grouped config
439@Value("${app.payment.gateway-url}")
440private String gatewayUrl;
441 
442// WRONG: returning null from service methods — use Optional or throw
443public Order findOrder(UUID id) {
444    return repository.findById(id).orElse(null);
445}
446 
447// WRONG: catching and swallowing exceptions
448try {
449    processPayment(order);
450} catch (Exception e) {
451    // silent swallow
452}
453 
454// WRONG: application.properties file
455# app.payment.gateway-url=https://...
456```
457 
458---
459 
460## Dependencies & Versions
461 
462| Library | Version | Import Style |
463|---------|---------|-------------|
464| Spring Boot | 3.2.x+ | `org.springframework.boot` |
465| Spring Security | 6.x | `org.springframework.security` |
466| Spring Data JPA | 3.x | `org.springframework.data.jpa` |
467| springdoc-openapi | 2.x | `org.springdoc` |
468| MapStruct | 1.5.x | `org.mapstruct` |
469| Jakarta EE | 10 | `jakarta.*` |
470| Java | 17 / 21 | — |
471 
472---
473 
474## Test Conventions
475 
476- Use `@WebMvcTest(MyController.class)` for controller layer tests — not full `@SpringBootTest`
477- Use `@DataJpaTest` for repository tests — auto-configures H2 or Testcontainers
478- Use `@MockBean` to inject mocked dependencies in slice tests
479- Use `MockMvc` with `ObjectMapper` for controller request/response verification
480- Name integration test classes with suffix `IT` — they run in a separate Maven phase
481- Use `@Testcontainers` + `@Container` for tests requiring a real database or message broker
482