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.

app/router.go

@@ -4,6 +4,7 @@ import (
 	"net/http"
 
 	"git.yuntuo.hk/k2safe/go-omni/httpx"
+	"git.yuntuo.hk/k2safe/go-omni/response"
 )
 
 func (a *App) handle(routes httpx.RouterGroup, method, path string, handler httpx.Handler, middleware []httpx.Middleware) {
@@ -11,6 +12,10 @@ func (a *App) handle(routes httpx.RouterGroup, method, path string, handler http
 }
 
 func (a *App) adapt(handler httpx.Handler, middleware ...httpx.Middleware) http.Handler {
+	return a.adaptResponse(a.responseEncoder, handler, middleware...)
+}
+
+func (a *App) adaptResponse(encoder response.Encoder, handler httpx.Handler, middleware ...httpx.Middleware) http.Handler {
 	wrapped := handler
 	all := make([]httpx.Middleware, 0, len(a.middlewares)+len(middleware))
 	all = append(all, a.middlewares...)
@@ -25,6 +30,7 @@ func (a *App) adapt(handler httpx.Handler, middleware ...httpx.Middleware) http.
 			request = request.WithContext(httpx.WithClientIPResolver(request.Context(), a.clientIPResolver))
 		}
 		requestContext := httpx.NewContext(request, writer, httpx.RouteParams(request.Context()))
+		requestContext.SetResponseEncoder(encoder)
 		if err := wrapped(requestContext); err != nil {
 			a.writeError(requestContext, err)
 		}
@@ -37,6 +43,14 @@ func (a *App) Handle(method, path string, handler httpx.Handler, middleware ...h
 	a.handle(a.router, method, path, handler, middleware)
 }
 
+// HandleWithResponse selects the route policy before all application middleware.
+func (a *App) HandleWithResponse(method, path string, encoder response.Encoder, handler httpx.Handler, middleware ...httpx.Middleware) {
+	if encoder == nil {
+		encoder = a.responseEncoder
+	}
+	a.router.Handle(method, path, a.adaptResponse(encoder, handler, middleware...))
+}
+
 func (a *App) GET(path string, handler httpx.Handler, middleware ...httpx.Middleware) {
 	a.handle(a.router, http.MethodGet, path, handler, middleware)
 }
@@ -94,6 +108,15 @@ func (g *RouterGroup) Handle(method, path string, handler httpx.Handler, middlew
 	g.route(method, path, handler, middleware)
 }
 
+func (g *RouterGroup) HandleWithResponse(method, path string, encoder response.Encoder, handler httpx.Handler, middleware ...httpx.Middleware) {
+	if encoder == nil {
+		encoder = g.app.responseEncoder
+	}
+	combined := append([]httpx.Middleware{}, g.middlewares...)
+	combined = append(combined, middleware...)
+	g.group.Handle(method, path, g.app.adaptResponse(encoder, handler, combined...))
+}
+
 func (g *RouterGroup) GET(path string, handler httpx.Handler, middleware ...httpx.Middleware) {
 	g.route(http.MethodGet, path, handler, middleware)
 }