feat: support primitive response arrays and shared catalog tooling

2026-09-25 02:22:24 +08:00
parent 1f2d8b6a6a
commit 64e3bd6cfc
40 changed files with 1656 additions and 1348 deletions
--- a/reports/contractFollowupAcceptance.md
+++ b/reports/contractFollowupAcceptance.md
@@ -0,0 +1,34 @@
+# v0.16.0-preview 契约与生成体验验收
+
+日期：2026-09-25。范围是通用数组响应、OpenAPI 引用、共享 Go 错误目录与环境覆盖；没有引入业务专属错误或外部服务依赖。
+
+## 验证结果
+
+- 字符串、布尔、各支持整数/浮点类型与 any 数组可以校验并生成 Go 类型；实际生成消费者验证中文字符串、int64 精度、混合对象/数组/null/标量、nil 根数组归一和 raw 数组。未知类型、byte/File/根嵌套数组明确拒绝。
+- 重复响应先共享，再依据体积收益共享 schema/示例，避免组件表本身膨胀。引用全部可解析，编译与压缩可重复；示例业务数据中的字面 `$ref` 不被解释。HTTP 200 同时含成功/业务错误时，两种 schema、所有模板示例和 data:null 保留。
+- 两个独立生成服务共享一次 Go Catalog 导出；服务/路由文档筛选不生成运行期目录。支持 internal 包，临时 Go overlay、模块文件及导出程序在工作结束后删除。check 完整文件快照不变；过期目录、编译错误、非法路径和 symlink 输出拒绝。
+- 重新生成保留 Logic；生成 --check、独立消费者 race 与编译通过。根 go run/go build、信号退出、nethttp/native、下载/原始回调/multipart 和生命周期清理继续通过。
+- 环境覆盖验证同一个 Lookup、allow/ignore/reject、完整名优先、显式空与未设置区别、false/0、JSON 集合、默认值不被修改、错误不带输入值。框架旧短名称入口兼容；存储/MySQL 生成组合验证了新版模板。
+
+## 实际契约文档
+
+| 服务 | 原字节数 | 新字节数 | 操作数 | 展开后内容 |
+| --- | ---: | ---: | ---: | --- |
+| eTax API | 20,751,149 | 847,171 | 67 | 完全一致 |
+| eTax ID | 1,008,210 | 392,481 | 3 | 完全一致 |
+
+[文档报告](contractFollowupDocuments.json) 保存原/新 SHA256 与生成源码摘要。通过只读 api export 写入临时目录，逐项比较完整 paths 操作；业务项目未做迁移或修改。
+
+[全量回归报告](contractFollowupRegression.json) 与 [进程验收](contractFollowupLocal.json) 保存本次检查结果。
+
+## 复验
+
+```sh
+GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./... -count=1 -timeout=300s
+go vet ./...
+go build ./...
+python3 scripts/verifyManagedProject.py --report reports/contractFollowupLocal.json
+python3 scripts/verifyManagedRelease.py --version v0.16.0-preview --report reports/contractFollowupRemote.json
+```
+
+共享 Catalog 提供方是清单显式指定的可信代码。框架隔离自己的文件操作，但不能保证用户提供方自身没有副作用；提供方应保持纯粹。该版本仍为 preview，未承诺支持完整 Go/goctl 类型语法或替业务完成数据库、权限、事务迁移。
--- a/reports/contractFollowupDocuments.json
+++ b/reports/contractFollowupDocuments.json
@@ -0,0 +1,40 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.16.0-preview",
+  "date": "2026-09-25",
+  "method": "Read-only api export against existing contracts; expand standard local references and compare every path operation to the existing documents. No business migration performed.",
+  "services": [
+    {
+      "service": "api",
+      "beforeBytes": 20751149,
+      "afterBytes": 847171,
+      "operations": 67,
+      "expandedOperationsIdentical": true,
+      "beforeSHA256": "e9e7fa5de073f1c1747d83e8144dead47080ad720f1c0daf9f0ef6af330eff02",
+      "afterSHA256": "b1276c7cec2ce7bcaba9a73c475dcc3f5b485306cc6b9a66a4ccf5c6077a13cb",
+      "components": {
+        "responses": 25,
+        "schemas": 1,
+        "securitySchemes": 1
+      }
+    },
+    {
+      "service": "id",
+      "beforeBytes": 1008210,
+      "afterBytes": 392481,
+      "operations": 3,
+      "expandedOperationsIdentical": true,
+      "beforeSHA256": "0ab7f09e18604e402ef372cfe71720c60d8e744b43c7fcbf83211ce1c1a5b04b",
+      "afterSHA256": "31c1b14754dc863431bf56ef3f6820b019428d8982011503ac91ea87aaecdf9d",
+      "components": {
+        "responses": 14,
+        "schemas": 1,
+        "securitySchemes": 0
+      }
+    }
+  ],
+  "sourceHashes": {
+    "cmd/go-omni/apigen/documentRefs.go": "7b841a668154d872493104eda0f9049340c67d9323eb99f1621a1ef6ba343891",
+    "cmd/go-omni/apigen/contractMetadata.go": "392fca7c015d17e0799019f62c9ed82904a7531a9779eb28c12ec37f8ab93fd7"
+  }
+}
--- a/reports/contractFollowupLocal.json
+++ b/reports/contractFollowupLocal.json
@@ -0,0 +1,59 @@
+{
+  "passed": true,
+  "mode": "localSource",
+  "durationSeconds": 4.91,
+  "checks": [
+    "rootGoRun",
+    "rootGoBuild",
+    "stableRegeneration",
+    "checkMainOwnership",
+    "contractChangePreview",
+    "logicSignatureCheckPersists",
+    "businessSourcePreserved",
+    "fixedConsumerBuild",
+    "nethttpSIGINT",
+    "nethttpSIGTERM",
+    "nativeSIGINT",
+    "nativeSIGTERM",
+    "listenerReleased",
+    "temporaryProcessesRemoved",
+    "nethttpGeneratedTransfers",
+    "nativeGeneratedTransfers",
+    "malformedMultipart400",
+    "goOwnedErrors",
+    "default404And405"
+  ],
+  "sourceHashes": {
+    "cmd/go-omni/apigen/generate.go": "9d81a3a4cd7905bd1829626e960512d86ac628d981be47c1d0cacc0648c0f33a",
+    "cmd/go-omni/apigen/templates.go": "6a98c26329d4c54d97abc170a324016931baac0e21028f649f1660347f5dd971",
+    "cmd/go-omni/apigen/startup.go": "e3322fa3e2aff9f45d66427f44187535c7c0960edc0f5fdfd5d7b4943b349334",
+    "cmd/go-omni/apigen/managed_test.go": "8b1b86d38151e78a1a18d8ecf001b9635d32c37276abaf2c9e28af10aa983e9d",
+    "cmd/go-omni/apigen/contractChanges.go": "aeb83990e908738faaa3cdfa20c3b8938023db05b6e55f2d24352c44144056a8",
+    "cmd/go-omni/apigen/logicCheck.go": "ca1af4f876a3a0db7b7b9ba9b82c1d6399fd89d29f667dad39cfd3de526eb1cb",
+    "cmd/go-omni/apigen/write.go": "180c5f5daee1441fe936cb376b1645a3d0c802cc78bf4b451dbf7e7b3e4ac0f4",
+    "cmd/go-omni/api.go": "5203a17c5f66977a9eba838d61cf5a7356de53d5f72a1196fd4f2046aa43ac85",
+    "config/config.go": "b4935ebb452c9df34b733842687ba11eec7e006a54ce42ff767273dd74d6e672",
+    "httpx/transfer.go": "c9fe4e98c0e599d367eaf19ebecf367db914edfca9ad3a65527496d1dea80a3d",
+    "httpx/multipart.go": "b942ede7a810b268cd43b395c3bddcfaaacad92812bbb60e653466b8d86bc875",
+    "scripts/verifyManagedProject.py": "b0e4b1aea4f44d61470c35c41f971e0882ae36b0eb5df2be190400d62fc60a18",
+    "lifecycle/controller.go": "1fb9393df1908afed93d87a1bf3ecea8d79d78e437a656b56bb7f1e5f6e51d31",
+    "health/health.go": "41f07f27a7fdcfa7973c2c554a22b73129ebc5d44e945e70e054e1cff24ab866",
+    "config/endpoints.go": "9f5123f962d52b71e5b73d5942316170875e895129a94e8b669ce782969ef27d",
+    "httpx/response.go": "2cf78b8f0eee8049ee612bb409a6eecc1d39eab9ab8f3b533ea21e3cac1611cb",
+    "app/app.go": "e5255ffdd36cba1c155037afc42f1c921b1f91bc79db75798a7feb0e9d51b1c0",
+    "app/transport.go": "88212d67d375e4c48c250a2e4c62fbff4e7873a67f91f2deb113a60634149f73",
+    "cmd/go-omni/scaffold/templates/api-config.go.tmpl": "715d29a9be33ba232eac339547cc0a13ae09c8bcb38a65a69a4f32f09fea5346",
+    "cmd/go-omni/scaffold/templates/api-runtime.go.tmpl": "e8575c04b0923d924d96e4334731313076284fd068c4990715b7a07a2724f969",
+    "cmd/go-omni/scaffold/templates/api-close.go.tmpl": "3f22d272e92f3b64b62123b3d80ec1a6ce8834257d64752fd75facf12623902b",
+    "cmd/go-omni/scaffold/templates/api-databaseOptions.go.tmpl": "6e5395b4a787c77a6cabfd85f16049a39578d6ec751a9b78203f3a03baabdf28",
+    "cmd/go-omni/scaffold/templates/api-options.go.tmpl": "11fe34ce45e8c98f7b5c9c0a2c512eb0b3abf86f95b4b576e083bcb6f5d0f824",
+    "cmd/go-omni/scaffold/templates/api-context.go.tmpl": "6cf67d37ef64f388b23a98781c3ee3abb71a2e0b9e71eeb70f1e5492ff7e32b4",
+    "cmd/go-omni/apigen/testdata/managed/options.go": "30d48e4b5aab476c887ac53cc89b48b2b7e250c8cd25e55fecb49bb2a3589247",
+    "cmd/go-omni/apigen/testdata/managed/background.go": "fb357b5deefd5187f2df406be5189fc4d57da857bd55b474f4726bf065c77167",
+    "cmd/go-omni/apigen/testdata/managed/client.go": "cdd7d394ddad4bcdc10224890a884aa513ed2ffd8275ecdad8de9963dd10986a",
+    "cmd/go-omni/apigen/testdata/managed/phases_test.go": "4d826d7133027ac2399f8209f03efa46ed54aa45dcd0a35274a9009314941dca",
+    "cmd/go-omni/apigen/testdata/managed/shutdown_test.go": "79fbf8dd4508b8217af888a31aaf2f2a01c1fa3869b2e80420605af697c66319",
+    "cmd/go-omni/apigen/testdata/managed/consumer_test.go": "9e103c9de7a1a906903bc09787e1b38905dc5bb4d891c88938028da5dee98f6f",
+    "cmd/go-omni/apigen/testdata/managed/operations.go": "44cea63e6023458c5818c9fdae223631cd1721f0841e671457398bfde8bc48f1"
+  }
+}
--- a/reports/contractFollowupRegression.json
+++ b/reports/contractFollowupRegression.json
@@ -0,0 +1,59 @@
+{
+  "passed": true,
+  "frameworkVersion": "v0.16.0-preview",
+  "date": "2026-09-25",
+  "command": "GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./... -count=1 -timeout=300s",
+  "testedPackages": [
+    "git.yuntuo.hk/k2safe/go-omni",
+    "git.yuntuo.hk/k2safe/go-omni/app",
+    "git.yuntuo.hk/k2safe/go-omni/audit",
+    "git.yuntuo.hk/k2safe/go-omni/auth",
+    "git.yuntuo.hk/k2safe/go-omni/cache",
+    "git.yuntuo.hk/k2safe/go-omni/cache/redis",
+    "git.yuntuo.hk/k2safe/go-omni/cmd/go-omni",
+    "git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/apigen",
+    "git.yuntuo.hk/k2safe/go-omni/cmd/go-omni/scaffold",
+    "git.yuntuo.hk/k2safe/go-omni/config",
+    "git.yuntuo.hk/k2safe/go-omni/contract",
+    "git.yuntuo.hk/k2safe/go-omni/database",
+    "git.yuntuo.hk/k2safe/go-omni/database/gormx",
+    "git.yuntuo.hk/k2safe/go-omni/database/migrate",
+    "git.yuntuo.hk/k2safe/go-omni/database/mysql",
+    "git.yuntuo.hk/k2safe/go-omni/errors",
+    "git.yuntuo.hk/k2safe/go-omni/examples/modules",
+    "git.yuntuo.hk/k2safe/go-omni/examples/platform",
+    "git.yuntuo.hk/k2safe/go-omni/examples/reference",
+    "git.yuntuo.hk/k2safe/go-omni/examples/reference/repository",
+    "git.yuntuo.hk/k2safe/go-omni/health",
+    "git.yuntuo.hk/k2safe/go-omni/httpc",
+    "git.yuntuo.hk/k2safe/go-omni/httpx",
+    "git.yuntuo.hk/k2safe/go-omni/internal/perfcheck",
+    "git.yuntuo.hk/k2safe/go-omni/lifecycle",
+    "git.yuntuo.hk/k2safe/go-omni/logx",
+    "git.yuntuo.hk/k2safe/go-omni/metrics",
+    "git.yuntuo.hk/k2safe/go-omni/middleware",
+    "git.yuntuo.hk/k2safe/go-omni/middleware/redis",
+    "git.yuntuo.hk/k2safe/go-omni/openapi",
+    "git.yuntuo.hk/k2safe/go-omni/pagination",
+    "git.yuntuo.hk/k2safe/go-omni/queue/redis",
+    "git.yuntuo.hk/k2safe/go-omni/resilience",
+    "git.yuntuo.hk/k2safe/go-omni/response",
+    "git.yuntuo.hk/k2safe/go-omni/storage",
+    "git.yuntuo.hk/k2safe/go-omni/storage/local",
+    "git.yuntuo.hk/k2safe/go-omni/storage/oss",
+    "git.yuntuo.hk/k2safe/go-omni/storage/s3",
+    "git.yuntuo.hk/k2safe/go-omni/task",
+    "git.yuntuo.hk/k2safe/go-omni/telemetry",
+    "git.yuntuo.hk/k2safe/go-omni/transport",
+    "git.yuntuo.hk/k2safe/go-omni/transport/http2",
+    "git.yuntuo.hk/k2safe/go-omni/transport/native",
+    "git.yuntuo.hk/k2safe/go-omni/transport/nethttp"
+  ],
+  "logSHA256": "ea70707ea4c160e9ed56edab99d040d9959dfa402a3e8f6d090d2b30ccef1513",
+  "additionalChecks": [
+    "go vet ./...",
+    "go build ./...",
+    "example managedService generate --check",
+    "example managedService go test ./..."
+  ]
+}