feat: add five example modules, fix the async example, and fix a runtime-only -parameters bug

[houko]

Two things: five new example modules for scenarios the collection was missing, and a rewrite of the async module so it actually demonstrates what it claims to. Also fixes a runtime-only bug the new tests uncovered.

The -parameters bug

Worth reading first, because it affects existing code rather than anything added here.

Spring Framework 6.1 removed LocalVariableTableParameterNameDiscoverer, which used to recover parameter names from debug symbols. Without the -parameters compiler flag, a @PathVariable/@RequestParam that does not spell out its name now fails at request time with:

IllegalArgumentException: Name for argument of type [int] not specified, and parameter
name information not available via reflection. Ensure that the compiler uses the '-parameters' flag.

There are 40 such declarations in this repository — BaseController, AuthOperate, and several controllers under website. Every one of those endpoints returns 500 on Spring Boot 4. Nothing fails at compile time, which is exactly why #41 passed its build and its smoke test without catching this: the smoke test exercised order, whose path variables happen to be explicitly named.

spring-boot-starter-parent sets this flag by default. This project imports the spring-boot-dependencies BOM instead of inheriting from the parent, so it has to configure it itself. Added to maven-compiler-plugin, with a comment explaining why it must not be removed.

This surfaced only because the new validation module has a test that hits an unnamed path variable. It is the clearest argument I can offer for the tests in this PR.

New modules

None of them require an external service, so all five ship with tests that run in CI. The tests double as executable documentation for each technique.

Module	Demonstrates
validation	@Valid on request bodies, @Validated on path parameters, and a @RestControllerAdvice that keeps the unified Result shape on the error path
fileupload	Single and batch upload plus download. Stores under a random name rather than the client-supplied one, and verifies the resolved path stays inside the storage root
restclient	RestClient (the Spring 6.1 replacement for RestTemplate) against an external API, mapping 4xx to a domain exception. Tested with MockRestServiceServer, so no network
cache	Spring's cache abstraction over Caffeine: @Cacheable, @CachePut, @CacheEvict
actuator	Health endpoint, a custom HealthIndicator, and business metrics registered through Micrometer

Two details worth calling out:

• The fileupload path-traversal guard is tested, not just asserted in a comment.
• The cache tests assert on how many times the method body ran, rather than poking at cache internals. That is the effect a caller actually cares about.

Rewriting the async example

async/TestController extended BaseController, which forced it to implement nine CRUD methods that have nothing to do with asynchrony. All nine were return null;. Ninety lines of noise around roughly ten lines of actual subject matter.

While rewriting it I found the module did not work at all:

• @EnableAsync was missing. Without it @Async is inert, so every task ran synchronously on the request thread. The example never demonstrated the thing it exists to demonstrate.
• AsyncResult is deprecated in Spring 6; replaced with CompletableFuture.completedFuture.
• The controller polled with while (true) { if (all done) break; Thread.sleep(1000); }. Besides burning a thread, the one-second granularity made the reported elapsed time wrong by up to a second. Replaced with CompletableFuture::join.
• System.out.println to a logger, static Random to ThreadLocalRandom.

New tests assert that the three tasks genuinely run concurrently and that the caller is not blocked — which is what would have caught the missing @EnableAsync.

Also removed @RestController from the abstract BaseController. An abstract base class should not be a @RestController, and its @PathVariable/@RequestBody annotations do nothing without a @RequestMapping. Added a class comment saying not to extend it from non-CRUD controllers.

I left the five website controllers extending BaseController alone. Those genuinely are CRUD controllers, so the base class fits them; their unimplemented methods are a separate question from async, where the inheritance was pure noise.

Also fixed copy-pasted javadoc in four entry-point classes that each described a different module ("RabbitMq启动器" on the security, mongodb and async mains, "后台管理启动器" on javase and socket).

Verification

All 21 modules build; 24 tests, 23 passing and 1 skipped (the RabbitMQ test, which needs a broker):

Tests run: 2, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.async.AsyncTaskTest
Tests run: 5, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.validation.RegisterControllerTest
Tests run: 5, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.fileupload.FileControllerTest
Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.restclient.GithubServiceTest
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.cache.BookServiceCacheTest
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0 -- info.xiaomo.actuator.ActuatorEndpointTest
[INFO] BUILD SUCCESS

Notes

• .properties files are read as ISO-8859-1, so the Chinese values in actuator's config use \uXXXX escapes, matching the convention already used elsewhere in this repository. A test asserts the value comes back correctly, since this fails silently otherwise.
• .gitignore gains upload (the fileupload default storage directory) and .DS_Store, and its missing trailing newline is fixed.

CodeQL caught a real weakness in the new code

Worth recording, since this is the first time CodeQL has ever run on this repository.

It flagged two high-severity Uncontrolled data used in path expression alerts in StorageService, and it was right. extensionOf took everything after the last dot of the client-supplied filename, so an upload named a.b/../../evil yields the "extension" .b/../../evil — a whole path segment spliced into the storage path. The original code did guard against this by comparing the parent directory after normalize(), so it was not exploitable, but that is checking after the tainted value has already been built into a path. Fragile, and hard to argue about.

Fixed in two rounds:

1. Keep the tainted value out of the path in the first place: strip every directory component from the original filename (handling Windows backslashes), then require the remainder to match \.[A-Za-z0-9]{1,10} or discard it entirely. Downloads must match the exact shape store produces.
2. CodeQL does not treat a regex check as a sanitizer, so the alerts persisted. Switched the resolution itself to the canonical normalize() then startsWith(root) form, centralised in one resolveWithinRoot method. The allowlist stays as defence in depth.

Three more tests cover the specific vector: a traversal fragment in the original filename must not reach the extension, a filename not matching the stored shape is rejected, and a legitimate extension is still preserved.

CodeQL — No new alerts in code changed by this pull request.