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/contracts/responses.api

@@ -0,0 +1,58 @@
+syntax = "v1"
+
+info (
+ title: "Configurable response example"
+ version: "1.0.0"
+)
+
+// Define the public body once. No field names are required by the framework.
+response CommonResponse (
+ body: {
+  "code": "${code}",
+  "msg": "${message}",
+  "data": "${data}"
+ }
+ codeType: int32
+ successCode: 200
+ errorCode: 9999
+ successMessage: "操作成功"
+ dataMode: always
+ codes: {"ITEM_NOT_FOUND":404001}
+ messages: {"ITEM_NOT_FOUND":"记录不存在"}
+)
+
+response PartnerResponse (
+ body: {"accepted":"${ok}","payload":"${data}","meta":{"trace":"${requestId}"}}
+ errorBody: {"accepted":"${ok}","error":{"reason":"${message}"}}
+)
+
+error ItemNotFound 404 "ITEM_NOT_FOUND" "item not found"
+
+type ItemReq {
+ ItemID int64 `path:"itemId" binding:"min=1"`
+}
+
+type ItemResp {
+ ItemID int64 `json:"itemId"`
+ Name string `json:"name"`
+}
+
+@server (
+ group: items
+ prefix: /api
+ response: CommonResponse
+)
+service response-api {
+ @errors ItemNotFound
+ @handler getItem
+ get /items/:itemId (ItemReq) returns (ItemResp)
+
+ // Success is the ItemResp object itself; errors still use CommonResponse.
+ @response raw
+ @handler rawItem
+ get /rawItems/:itemId (ItemReq) returns (ItemResp)
+
+ @response PartnerResponse
+ @handler partnerItem
+ get /partnerItems/:itemId (ItemReq) returns (ItemResp)
+}

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
 }