contracts/README.md

git.fsdpf.net/go/contracts（master）

跨服务共享的契约层：各类服务（HTTP/gRPC/队列/任务调度/定时任务/MQTT/WebSocket/条件流引擎等） 的接口定义，以及资源系统相关的类型别名，供 framework-v2（服务编排/启动）和各业务项目共同 依赖，避免互相直接 import 造成循环依赖。配合 "-v2" 系列项目使用。

这个仓库有什么

DI 辅助（di.go）

对 samber/do/v2 的一层薄封装：Injector/Invoke/MustInvoke/InvokeNamed/ MustInvokeNamed，全仓库统一用这几个函数取 DI 容器里的服务，不直接 import samber/do/v2。

插件与注册（app.go）

App 接口：LoadGoPlugin(file string) error 加载 Go plugin，RegControllers/RegResWatchers/ RegGRpcs/RegJobs/RegCrons/RegMqtts/RegFlowDecisions/RegGoBridges/ RegResVirtualTables 一批 Reg* 方法把插件里定义的各类实现注册进框架，对应的 GetApp*/ Get* 方法按 code 查回来。

资源系统对接

• resource.go：GetResource/MustResource 是 req.GetResource/req.MustResource 的类型 别名，GetUser 按 uuid 查用户。
• res_watcher.go：ResEventType（resx.ResEventType 别名）+ ResWatcher——资源发生变更时 要通知的外部监听方注册信息。
• res_virtual_table.go：ResVirtualTableSetup（req.ResVirtualTableSetup 别名）——framework-v2 在 sqlite_vtable build tag 下注册进容器，负责给 SQLite 注册虚拟表模块。
• event_stream.go：事件流相关契约。

各类服务契约

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 （鉴权/验证码）、condflow.go（条件流引擎对接）、gobridge.go（跨语言 bridge）、mcp.go （Model Context Protocol 对接）、executor.go（通用执行器契约）。

子包

• base/：基础类型（用户、角色等业务通用结构）。
• support/：辅助工具。

分支状态

master 是持续开发中的新架构，跟老仓库 v1-legacy 分支不完全兼容——di.go/app.go/ condflow.go/gobridge.go/mcp.go/res_virtual_table.go/res_watcher.go 都是新增的， res_event.go/res_type/ 这些老概念已经拆分/移除。还在用老版契约的老项目，参见 v1-legacy 分支。