feat: release configurable API response contracts

Define reusable response bodies in .api with typed code mappings, per-route overrides and matching OpenAPI schemas. Add application and callback encoders, early response policy selection, and isolated remote-consumer release verification.

Release v0.8.0-preview after full race, vet, build and local MySQL workflow acceptance.

config/config.go

@@ -6,6 +6,7 @@ import (
 
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/logx"
+	"git.yuntuo.hk/k2safe/go-omni/response"
 )
 
 const defaultRequestIDHeader = "X-Request-ID"
@@ -24,15 +25,17 @@ type TLSConfig struct {
 
 // Config controls the default runtime behavior of an App.
 type Config struct {
-	Address              string        `json:"address"`
-	Transport            string        `json:"transport"`
-	TLS                  TLSConfig     `json:"tls"`
-	RequestIDHeader      string        `json:"requestIdHeader"`
-	EnableLogger         bool          `json:"enableLogger"`
-	SlowRequestThreshold time.Duration `json:"slowRequestThreshold"`
-	TrustedProxies       []string      `json:"trustedProxies"`
-	ShutdownTimeout      time.Duration `json:"shutdownTimeout"`
-	Log                  logx.Config   `json:"log"`
+	Address              string           `json:"address"`
+	Transport            string           `json:"transport"`
+	TLS                  TLSConfig        `json:"tls"`
+	RequestIDHeader      string           `json:"requestIdHeader"`
+	EnableLogger         bool             `json:"enableLogger"`
+	SlowRequestThreshold time.Duration    `json:"slowRequestThreshold"`
+	TrustedProxies       []string         `json:"trustedProxies"`
+	ShutdownTimeout      time.Duration    `json:"shutdownTimeout"`
+	Log                  logx.Config      `json:"log"`
+	Response             response.Config  `json:"response"`
+	ResponseEncoder      response.Encoder `json:"-"`
 }
 
 func Default() Config {
@@ -47,6 +50,9 @@ func Default() Config {
 
 // Validate checks configuration values before an application starts.
 func (c Config) Validate() error {
+	if err := c.Response.Validate(); err != nil {
+		return err
+	}
 	if c.SlowRequestThreshold < 0 {
 		return &ConfigError{Field: "slowRequestThreshold", Message: "must be nonnegative"}
 	}
@@ -134,15 +140,29 @@ func WithTrustedProxies(proxies ...string) Option {
 // WithConfig applies a complete configuration loaded from a file or
 // environment. Later options can still override individual fields.
 func WithConfig(settings Config) Option {
+	settings.Response = settings.Response.Clone()
 	settings.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 	settings.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	return func(cfg *Config) {
 		*cfg = settings
+		cfg.Response = settings.Response.Clone()
 		cfg.TrustedProxies = append([]string(nil), settings.TrustedProxies...)
 		cfg.Log.RedactKeys = append([]string(nil), settings.Log.RedactKeys...)
 	}
 }
 
+// WithResponse configures this application's default JSON envelope.
+func WithResponse(settings response.Config) Option {
+	settings = settings.Clone()
+	return func(cfg *Config) { cfg.Response = settings.Clone(); cfg.ResponseEncoder = nil }
+}
+
+// WithResponseEncoder replaces the default encoder with application code.
+// OpenAPI for custom encoders must describe their actual wire contract explicitly.
+func WithResponseEncoder(encoder response.Encoder) Option {
+	return func(cfg *Config) { cfg.ResponseEncoder = encoder }
+}
+
 // WithLogConfig configures the logger used by the application runtime.
 func WithLogConfig(settings logx.Config) Option {
 	settings.RedactKeys = append([]string(nil), settings.RedactKeys...)

config/file.go

@@ -181,6 +181,7 @@ func (r *Reloader) Snapshot() Config {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 	cfg := r.current
+	cfg.Response = r.current.Response.Clone()
 	cfg.TrustedProxies = append([]string(nil), cfg.TrustedProxies...)
 	cfg.Log.RedactKeys = append([]string(nil), cfg.Log.RedactKeys...)
 	return cfg