feat: load explicit configuration references and remove implicit env overlays

examples/managedService/.goOmni/apiManifest.json

@@ -1,6 +1,6 @@
 {
   "generatorConfig": true,
-  "templateVersion": "v0.20.0-preview",
+  "templateVersion": "v0.22.0-preview",
   "profile": {
     "database": "none",
     "storage": "none",
@@ -12,7 +12,7 @@
   "entry": "api/managed.api",
   "generated": {
     "docs/openapi.json": "0370fd6bd6a387e2ef21f6b42b009ce66749846b8bea3d481009a34f3af039a5",
-    "internal/config/loadGen.go": "5d630b894abdbbd66ddfa7d7d30f7573fc4ff995020a32a9f9157cd4af3a5655",
+    "internal/config/loadGen.go": "d85e3123e4c96c95cb0886e60e4760230426efca4d2bbbfc981822da08b90d13",
     "internal/handler/appGen.go": "f5251b4dc33e2312b0bdb71ead70d2171977d851265e124f640458d705a2cc9d",
     "internal/handler/demo/handlersGen.go": "3c76d85dbe89eb5127d9d134dc625203ecf9719dd11d174c1f335691b99e1375",
     "internal/handler/openapiGen.go": "f24cab3abbb8557a3fc4dd93fba23cc0b093f3e0c944d3ba1bd5b0eeff2d96f3",
@@ -22,7 +22,7 @@
     "internal/svc/runtimeGen.go": "29f6afb6614881935099c1845ecb3f7902ee773caa077940f566cb8dfdbcdbb1",
     "internal/types/dtoManagedd28645a2af1cGen.go": "7586e86fa5d67051283178cc578c890f6c02fd2d5c383170a71a39c2e77ce344",
     "internal/types/typesGen.go": "372d67f23a313b3e77d2a3b7a236315db9721bc63350bf1f71db1293e57570d1",
-    "main.go": "64e26d97de7e7c6c17f47186785edc73d43c23d6c20b50bfc7fff6ef2e914f17"
+    "main.go": "10cb6a84b2eb1b68dc10c2dca949c9dd7c68a9f78a8e6d8f56ce9336d4b2d125"
   },
   "contract": {
     "routes": {

examples/managedService/README.md

@@ -46,6 +46,6 @@ Configuration, API contracts, svc fields/Init/AppOptions, Logic, Repository and
 middleware implementations remain developer-owned. Regeneration preserves them.
 Use `go-omni api format` to format local contracts, then `api generate` and
 `api generate --check`. See the [framework development guide](../../DEVELOPMENT.md)
-for array/null responses, typed multipart, full configuration environment overrides,
+for array/null responses, typed multipart, explicit configuration references and -check-config,
 shared contracts and v0.13 upgrade steps. This example keeps its raw callback,
 streaming upload and download to exercise those existing extension points.

examples/managedService/etc/config.yaml

@@ -1,16 +1,3 @@
-# Non-secret settings only. Environment variables override these values.
 server:
-  address: '127.0.0.1:8080'
-  enableLogger: true
-  slowRequestThreshold: 500ms
-  shutdownTimeout: 10s
-  endpoints:
-    liveness: {enabled: true, path: /health/live, responseMode: app}
-    readiness: {enabled: true, path: /health/ready, responseMode: app}
-    openapi: {enabled: true, path: /openapi.json}
-  log:
-    service: "example.com/managed"
-    level: info
-    format: json
-    output: stderr
-    redactKeys: []
+  address: "${GO_OMNI_HTTP_ADDR:-127.0.0.1:8080}"
+  transport: "${GO_OMNI_TRANSPORT:-nethttp}"

examples/managedService/go.mod

@@ -2,7 +2,7 @@ module example.com/managed
 
 go 1.22.0
 
-require git.yuntuo.hk/k2safe/go-omni v0.21.0-preview
+require git.yuntuo.hk/k2safe/go-omni v0.22.0-preview
 
 require (
 	github.com/gabriel-vasile/mimetype v1.4.3 // indirect

examples/managedService/internal/config/loadGen.go

@@ -3,14 +3,12 @@ package config
 
 import omniConfig "git.yuntuo.hk/k2safe/go-omni/config"
 
-// Load is maintained by the generator. Extend Config/Default/Validate in
-// config.go, or NewLoader in loader.go; do not duplicate the loading pipeline.
+// Load resolves explicit file references, binds onto Default and validates.
+// Ordinary projects only edit Config, Default, Validate and the selected file.
 func Load(path string) (Config, error) {
 	loader, err := NewLoader()
 	if err != nil {
 		return Config{}, err
 	}
-	return omniConfig.LoadProject(path, Default(), omniConfig.EnvOptions{
-		Prefix: "GO_OMNI_", Empty: "ignore", Aliases: omniConfig.ServerEnvAliases("GO_OMNI_", "server"),
-	}, loader)
+	return omniConfig.LoadProject(path, Default(), loader)
 }

examples/managedService/main.go

@@ -17,8 +17,15 @@ import (
 )
 
 func main() {
-	path := flag.String("config", "etc/config.yaml", "configuration file; empty uses defaults and environment")
+	path := flag.String("config", "etc/config.yaml", "configuration file; empty uses only Default()")
+	check := flag.Bool("check-config", false, "validate configuration and exit without starting dependencies")
 	flag.Parse()
+	if *check {
+		if _, err := config.Load(*path); err != nil {
+			log.Fatal(err)
+		}
+		return
+	}
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
 	if err := run(ctx, *path); err != nil {