From 0ab301890e811323c41fb3a5501aad9f501dda16 Mon Sep 17 00:00:00 2001 From: what Date: Thu, 20 Aug 2026 17:20:35 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20README=EF=BC=8C?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=20v1-legacy=20=E5=88=86=E6=94=AF=E7=9A=84?= =?UTF-8?q?=E8=83=BD=E5=8A=9B=E8=8C=83=E5=9B=B4=E4=B8=8E=E5=AE=89=E8=A3=85?= =?UTF-8?q?=E6=96=B9=E5=BC=8F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 记录这条老线跟 master 的差异，以及依赖方（如 zg-estate）应该怎么锁定/更新 到这个分支，避免误跑 go get -u 拉到 master 上的破坏性改动。 --- README.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..359a39c --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +# git.fsdpf.net/go/contracts（v1-legacy） + +老架构下跨服务共享的契约层：HTTP/gRPC/队列/任务调度/定时任务/MQTT/WebSocket 等各类服务的接口 +定义，以及资源系统（`resource.go`）、用户审批（`user_approval.go`）等业务相关契约，供 +`framework`（服务编排/启动）和各业务项目共同依赖，避免互相直接 import 造成循环依赖。 + +## 这个分支有什么 + +- `resource.go`/`orm.go`：跟老版 `req`/`orm` 配套的资源、ORM 相关契约。 +- `http.go`/`grpc.go`/`grpcall.go`/`server.go`：HTTP/gRPC 服务契约。 +- `job.go`/`cron.go`/`queue.go`：任务调度、定时任务、消息队列契约。 +- `mqtt.go`/`ws.go`：MQTT、WebSocket 契约。 +- `jwt_auth.go`/`captcha.go`/`user_approval.go`：鉴权、验证码、用户审批相关契约。 +- `res_event.go`：资源变更事件契约（新架构里拆成了 `res_watcher.go`/`event_stream.go`，接口 + 形状不一样）。 +- `res_type/`：资源类型相关的独立子包（新架构里已经不存在，能力并到别处了）。 +- `base/`/`support/`：基础类型和辅助工具。 + +## 这个分支的定位 + +给还在维护、但还没迁移到新架构（`master` 分支上新增的 `di.go` DI 辅助函数、`app.go`、 +`condflow.go`、`gobridge.go`、`mcp.go`、`res_virtual_table.go`/`res_watcher.go` 等）的老项目用， +比如 `zg-estate`（直接依赖）。只接受独立于新架构的 bug 修复。 + +## 依赖方怎么安装/更新 + +Go modules 不会记住某个版本是从哪个分支解析出来的，`go.mod`/`go.sum` 里存的只是一次性解析出 +的 commit 伪版本号，分支上有新提交也不会自动同步。 + +**首次锁定，或者要拿这个分支上新提交的更新**，都执行同一条命令： + +``` +go get git.fsdpf.net/go/contracts@v1-legacy +``` + +**禁止**跑裸的 `go get -u`（或者 `go get git.fsdpf.net/go/contracts@latest`）——这个仓库没有打 +语义化 tag，Go 对"最新版本"的解析规则是退回到仓库默认分支（`master`）的 HEAD，会把新架构的 +破坏性改动一起拉进来，而不是停留在这个分支上。同时注意这条老线依赖的 `git.fsdpf.net/go/db`/ +`git.fsdpf.net/go/req`/`git.fsdpf.net/go/orm` 也要一起锁定在它们各自的 `v1-legacy` 分支， +不能新老混用。