Skip to content

Commit 313b385

Browse files
rraystrrayst
authored
junie guidelines (#2166)
1 parent a948f76 commit 313b385

File tree

1 file changed

+121
-0
lines changed

1 file changed

+121
-0
lines changed

‎.junie/guidelines.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
Membrane API Gateway — Project-specific Development Guidelines
2+
3+
Audience: Experienced Java developers working on this repository.
4+
5+
Last verified with: Java 21, Maven 3.9+, Windows dev environment. Date: 2025-09-22 09:55 local.
6+
7+
Overview
8+
- Repository layout: Maven multi-module project
9+
- Modules: annot, core, starter, distribution, war, test, maven-plugin
10+
- Java level: 21 (see root pom.xml properties javac.source/target)
11+
- Primary runtime module: distribution (contains router packaging and runnable artifacts)
12+
- Primary library code: core
13+
- Shared test utilities: test
14+
15+
Build and Configuration
16+
- Prerequisites:
17+
- JDK 21 on PATH (ensure java -version returns 21.x)
18+
- Maven 3.9+ (mvn -v)
19+
- Git LFS not required for build
20+
- Full build (all modules):
21+
- mvn -q -DskipTests package
22+
- Produces module artifacts under each module’s target directory. distribution assembles runnable bits.
23+
- Build one module only:
24+
- mvn -q -pl core -am -DskipTests package
25+
- -pl selects the module; -am builds required dependencies.
26+
- Useful flags:
27+
- -DskipTests skips unit tests (Surefire) and integration tests (Failsafe) entirely.
28+
- -DskipITs skips Failsafe integration tests only (if you want Surefire unit tests to run).
29+
- -Dtest=ClassName or -Dtest=ClassName#method for targeted unit tests.
30+
- -T 1C parallelizes the build per core.
31+
- Code generation and packaging:
32+
- core uses an annotation processor (service-proxy-annot) to generate router-conf.xsd; maven-antrun copies it into docs at package time.
33+
- CycloneDX SBOM is generated at package for core.
34+
35+
Running the Router (local):
36+
- Quick start with defaults:
37+
- After packaging distribution: distribution\target contains router binaries and scripts.
38+
- Configuration is under distribution\conf\proxies.xml (example provided). Edit/extend this file to add routes.
39+
- From IDE: Run com.predic8.membrane.core.RouterCLI with appropriate args, or use distribution scripts. RouterCLI reads configuration based on the working directory and arguments.
40+
41+
Testing
42+
- Frameworks:
43+
- JUnit 5 (Surefire). Integration tests via Maven Failsafe where applicable.
44+
- Shared testing utilities are provided by module test (artifactId service-proxy-test). Import as test scope in modules.
45+
- Run all unit tests (entire repo):
46+
- mvn -q test
47+
- Run unit tests for a specific module:
48+
- mvn -q -pl core -am test
49+
- Target a single test class:
50+
- mvn -q -pl core -Dtest=com.predic8.membrane.core.transport.http.HttpTransportTest test
51+
- Target a single test method:
52+
- mvn -q -pl core -Dtest=com.predic8.membrane.core.transport.http.HttpTransportTest#testOpenPortOK_NoSSL test
53+
- Run integration tests (if any configured in the module):
54+
- mvn -q -pl core -DskipTests -DskipITs=false verify
55+
- Failsafe runs during integration-test/verify phases. The default config in core binds it to look for IntegrationTestsWithInternet/IntegrationTestsWithoutInternet suites.
56+
- Windows path note: Always use backslashes for file paths when referencing resources; Maven parameters still use Java FQNs for -Dtest, not file paths.
57+
58+
Adding New Tests
59+
- Placement:
60+
- Unit tests go under <module>\src\test\java with package mirroring main sources.
61+
- If you need common helpers, depend on module test (service-proxy-test) with scope test.
62+
- Dependencies:
63+
- Most common test deps are already declared in core (JUnit Jupiter API/Engine, Mockito, Rest-Assured, XMLUnit, etc.). For other modules, add the same as needed, keeping scope test.
64+
- Naming/Discovery:
65+
- JUnit 5 doesn’t require naming conventions, but Surefire by default discovers any class with @Test methods on the JUnit Platform.
66+
- Integration tests executed by Failsafe are typically bound by pattern or explicit suite classes (see core/pom.xml) — don’t rely on the old *IT.java naming unless the module config specifies it.
67+
- Logging in tests:
68+
- Prefer SLF4J; enable additional logging via -Dorg.slf4j.simpleLogger.defaultLogLevel=debug or module-specific log4j configuration if present.
69+
70+
Demonstrated Example (verified now)
71+
The following minimal test was added temporarily under core and executed successfully to validate the workflow:
72+
- File created at: core\src\test\java\com\predic8\membrane\core\SanityTest.java
73+
- Contents:
74+
package com.predic8.membrane.core;
75+
76+
import org.junit.jupiter.api.Test;
77+
import static org.junit.jupiter.api.Assertions.*;
78+
79+
public class SanityTest {
80+
@Test
81+
void sumsWork() {
82+
int a = 2 + 2;
83+
assertEquals(4, a, "Basic arithmetic should work");
84+
}
85+
}
86+
- Command to run just this test class:
87+
mvn -q -pl core -Dtest=com.predic8.membrane.core.SanityTest test
88+
- Result: Passed (1/1). The file has been removed after verification to keep the repo clean.
89+
90+
Module-Specific Notes and Pitfalls
91+
- core:
92+
- Uses Java 21 language features; ensure IDE and toolchain are on 21.
93+
- Surefire in core explicitly sets argLine -Dfile.encoding=UTF-8 — do not remove; some tests and YAML parsing rely on UTF-8.
94+
- Integration suites are driven by specific class names (IntegrationTestsWithInternet/IntegrationTestsWithoutInternet). Avoid introducing external network dependencies into regular unit tests.
95+
- SpEL functions (com.predic8.membrane.core.lang.spel.functions.*): All built-in functions must be static and accept SpELExchangeEvaluationContext as last parameter. Keep these non-destructive. When adding functions, follow the documented constraints to auto-register via BuiltInFunctionResolver.
96+
- SecurityScheme scopes are surfaced via Exchange properties (SECURITY_SCHEMES). When writing tests touching scopes(), prefer setting Exchange properties rather than mocking deep router chains.
97+
- distribution:
98+
- Conf files under distribution\conf are used by RouterCLI and scripts. If you change schema in core, ensure router-conf.xsd copy step still functions and docs generation remains intact.
99+
- test (module):
100+
- Provides testing utilities (HTTP client helpers, common fixtures). Use as a test-scoped dependency from other modules to avoid duplication.
101+
102+
Code Style and Quality
103+
- Java style is standard; prefer immutability and Optional for nullable flows where already used in core.
104+
- Annotations:
105+
- org.jetbrains.annotations are available; use @NotNull/@Nullable for public APIs in core.
106+
- Static analysis:
107+
- SpotBugs reporting is configured at the parent level; run mvn -Pspotbugs site if needed (or check the reporting section in module poms).
108+
- Logging:
109+
- Use SLF4J (logback/log4j routing present). Avoid System.out in production code; in tests it’s acceptable for quick debug but prefer logger.
110+
111+
Quick Troubleshooting
112+
- Compilation fails due to Java version: Ensure JAVA_HOME points to JDK 21 and IDE uses language level 21.
113+
- Tests hang on network: Constrain to -Dtest=... for unit tests; avoid running Failsafe suites that require internet unless necessary.
114+
- Classpath or annotation processor errors: Clean build with mvn -q -U -e -X -DskipTests clean package to refresh dependencies and get detailed logs.
115+
116+
Release/Packaging
117+
- Full release artifacts are assembled under distribution\target after mvn package at the root. WAR packaging is in war module for servlet containers.
118+
119+
Contact/Upstream
120+
- Upstream: https://github.com/membrane/api-gateway
121+
- Issues: https://github.com/membrane/api-gateway/issues

0 commit comments

Comments
 (0)