Technical article
Route static preflight: validate route configuration without starting the service
route-static-preflight.py ships with the delivery package and turns pre-delivery route review into one deterministic command — no LightESB startup, no external connections — across ten scenario profiles from HTTP to industrial protocols.
The expensive mistakes are static ones
A LightESB service is exactly what sits in its version directory: route XML plus two properties files, hot-loaded on change. The model is simple, but it makes low-level slips frequent — a `{{server.port}}` placeholder no properties file defines, a referenced request-schema.json that was never delivered, an industrial sample that forgets the safe default server.running=false and dials plant equipment on load.
All of these are statically detectable. Manual review is slow; starting the service to read logs is costly in delivery and review environments. The preflight tool collapses that review into a single command with a gate-friendly exit code.
What the tool checks
Generic closure
Exactly one XML per directory with unique route ids; XML and both properties files parse and carry service identity; every {{key}} placeholder resolves; referenced .ds and schema JSON resources exist on disk.
Ten scenario profiles
http, timer, transform, schema, externaldb, ai-agent, mqtt, opcua, modbus, sap-mock — each adds its required keys and safe defaults, such as HTTP.Listener=true for HTTP and server.running=false for industrial protocols.
Fully offline
No service startup, no environment-variable resolution, no external connections. The verdict comes from the service directory files alone.
Gate-friendly output
A single-line PASS on success; itemized findings with the exact key names on failure. Exit codes 0/1 drop directly into CI or pre-delivery scripts.
One command, real output
Run it against the bundled HTTP sample. A pass prints a single-line verdict:
python3 skills/lightesb-route-authoring/scripts/route-static-preflight.py \
--service-dir example/routes/http-undertow/DemoHttpSrv/v1.0.0 \
--profile http
PASS profile=http route=demo-http-route.xmlWhen configuration is missing, findings are itemized — each line names the profile and the exact key to fix:
FAIL
- [http] 缺少配置键：system.components
- [http] 配置值必须为 HTTP.Listener=true
- [http] system.components 缺少：undertowhttp
- [http] XML 缺少必要模式：undertow:Know the boundary
PASS means "statically loadable with confidence" — not that the service is loaded, and not that the business flow works. The right delivery posture: run static preflight first, follow with runtime verification as needed, and state clearly in the delivery note which validations were done and which were not.