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.

examples/userService/.goOmni/apiManifest.json

@@ -12,7 +12,8 @@
     "docs/openapi.json": "05bce8951699350cc1ebca5a626c39349395dd09e395b41560c129e530583204",
     "internal/apierrors/errorsGen.go": "20e94bbc90ae9f4330de4c25b9a550026c4c352502719a643ede3e8912a6566e",
     "internal/handler/openapiGen.go": "e4130f5c7494f7db4830bfef203fa8154a9cd087c95954f64c29d74693ead433",
-    "internal/handler/routesGen.go": "7f45030e7eb9f055c4b4d2ff12ad855d7c726aad4aee63c5b3c3f97559a64257",
+    "internal/handler/responseGen.go": "d742efc2a3d1d168fae7849e905297bd440c3d6b3802b6150f494c07e6097f4f",
+    "internal/handler/routesGen.go": "0ff429a8aa7f8643e0e844f7c43a63a1f82cca5ce6bfe917f06edd860ebe923f",
     "internal/handler/user/handlersGen.go": "06f3c2798ff323812ff3eb2d8b933a569af3ce1b86a67b66036374add98c0d7e",
     "internal/middleware/registryGen.go": "a6122a5453dedc6a4415860108814c50e155128cfe5412b39dd33ce2d01b4b00",
     "internal/types/typesGen.go": "3ab2ce9ffe467c3ea53ac3d1fec283ecebc87cef57fd592d08dca991fd964876"

examples/userService/README.md

@@ -18,8 +18,9 @@ go-omni migrate --dir migrations --apply
 go run ./cmd/server
 ```
 
-源码示例的 go.mod 使用 `replace ... => ../..`。复制到独立仓库时，删除这条 replace，
-保留已发布的固定依赖版本，再执行 go mod tidy。远程版本验证脚本会自动检查没有本地替换。
+源码示例的 go.mod 使用 `replace ... => ../..`。生成代码使用 `v0.8.0-preview` 响应策略入口。
+复制到独立仓库时删除 replace，保留同版本固定依赖，再执行 go mod tidy；CLI 也固定到同一版本。
+远程版本验证脚本会检查没有本地替换。
 `GO_OMNI_TRANSPORT=native` 可切换为 native，业务代码无需调整。
 
 配置是默认值 → etc/config.yaml → 环境变量。日志默认写入 var/log/server.log 并轮转，
@@ -70,10 +71,10 @@ Gen.go 和 docs/openapi.json 由生成器维护；Service、Repository、迁移
 在框架仓库运行：
 
 ```sh
-python3 scripts/verifyAPIWorkflow.py --report performance/apiDeveloperExperienceLocal.json
-# 已发布版本：全新 module cache 安装 CLI，无本地 replace 消费框架。
-python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
-  --report performance/apiDeveloperExperienceRemote.json
+python3 scripts/verifyAPIWorkflow.py --report performance/responsePoliciesWorkflowLocal.json
+# 使用本版远程 CLI 和模块验收，无本地替换。
+python3 scripts/verifyAPIWorkflow.py --version v0.8.0-preview \
+  --report performance/responsePoliciesWorkflowRemote.json
 ```
 
 验收创建只绑定 localhost 的临时 MySQL 容器（1 CPU / 768 MiB），使用随机密钥，结束时删除。

examples/userService/go.mod

@@ -3,7 +3,7 @@ module example.com/userService
 go 1.22.0
 
 require (
-	git.yuntuo.hk/k2safe/go-omni v0.7.0-preview.1
+	git.yuntuo.hk/k2safe/go-omni v0.8.0-preview
 	github.com/go-sql-driver/mysql v1.9.3
 )
 

examples/userService/internal/handler/responseGen.go

@@ -0,0 +1,30 @@
+// Code generated by go-omni api. DO NOT EDIT.
+package handler
+
+import (
+	"encoding/json"
+	"git.yuntuo.hk/k2safe/go-omni/response"
+	"strings"
+)
+
+var responseTemplates = map[string]response.Encoder{"": response.Default()}
+
+func newResponseTemplate(raw string) response.Encoder {
+	var cfg response.Config
+	decoder := json.NewDecoder(strings.NewReader(raw))
+	decoder.UseNumber()
+	if err := decoder.Decode(&cfg); err != nil {
+		panic(err)
+	}
+	return response.MustNew(cfg)
+}
+func responseEncoder(name string, raw bool) response.Encoder {
+	encoder := responseTemplates[name]
+	if encoder == nil {
+		panic("unknown response template")
+	}
+	if raw {
+		encoder = response.RawJSON(encoder)
+	}
+	return encoder
+}

examples/userService/internal/handler/routesGen.go

@@ -6,6 +6,7 @@ import (
 	s0 "example.com/userService/internal/service/user"
 	"example.com/userService/internal/servicecontext"
 	"fmt"
+	"git.yuntuo.hk/k2safe/go-omni/httpx"
 	"git.yuntuo.hk/k2safe/go-omni/openapi"
 )
 
@@ -17,11 +18,11 @@ func RegisterRoutes(router openapi.Registrar, deps *servicecontext.Context) erro
 		return fmt.Errorf("missing middleware Auth")
 	}
 	h0 := h0.New(s0.New(deps))
-	router.Handle("POST", "/api/v1/users", h0.CreateUser, deps.Middlewares["Auth"])
-	router.Handle("GET", "/api/v1/users/:id", h0.GetUser, deps.Middlewares["Auth"])
-	router.Handle("GET", "/api/v1/users", h0.ListUsers, deps.Middlewares["Auth"])
-	router.Handle("PUT", "/api/v1/users/:id", h0.UpdateUser, deps.Middlewares["Auth"])
-	router.Handle("DELETE", "/api/v1/users/:id", h0.DeleteUser, deps.Middlewares["Auth"])
-	router.Handle("POST", "/api/v1/users/:id/export", h0.ExportUser, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "POST", "/api/v1/users", responseEncoder("", false), h0.CreateUser, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "GET", "/api/v1/users/:id", responseEncoder("", false), h0.GetUser, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "GET", "/api/v1/users", responseEncoder("", false), h0.ListUsers, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "PUT", "/api/v1/users/:id", responseEncoder("", false), h0.UpdateUser, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "DELETE", "/api/v1/users/:id", responseEncoder("", false), h0.DeleteUser, deps.Middlewares["Auth"])
+	httpx.HandleWithResponse(router, "POST", "/api/v1/users/:id/export", responseEncoder("", false), h0.ExportUser, deps.Middlewares["Auth"])
 	return nil
 }