企业级Go框架设计以业务约束为起点，通过“约定优于配置”实现目录即契约、路径与handler强绑定、中间件可拆解、服务治理预留钩子、接口面向业务变更等架构实践。
企业级 Go 框架不是堆功能，而是用架构思维把业务约束翻译成代码结构——比如临床试验系统必须满足 GCP 审计日志、多中心权限隔离、HIS/LIS 对接等硬性要求，框架设计就得从这些约束倒推。
约定优于配置：目录结构即契约
新成员入职后 10 分钟内能写出一个合规 API，靠的不是文档，是目录强制约定。比如 internal/handler 只放 HTTP 入口，internal/logic 禁止直接调用 DB，internal/model 的 struct 必须带 CreatedAt 和 UpdatedBy 字段。一旦有人在 logic 里写 db.QueryRow，CI 就该报错。
- 路径名和 handler 函数名强绑定：比如
/v1/sites/:site_id/subjects对应handler.SiteSubjectHandler.List - 所有 handler 必须接收
*gin.Context或封装后的app.Context，禁止裸传http.ResponseWriter -
internal/pkg下只放跨域工具（如 JWT 解析、审计日志写入），不放业务逻辑
中间件链必须可拆解、可跳过
真实业务里，不是每个接口都要走完整链。比如患者提交问卷（ePRO）要鉴权 + 审计 + 限流，但后台导出 Excel 报表只需鉴权 + 权限校验，跳过限流和审计日志（避免 IO 拖慢导出）。
- 用
r.GET("/export", authMiddleware, exportPermissionMiddleware, exportHandler)显式声明，别塞进全局r.Use() - 权限中间件里别做 DB 查询：查用户所属 site ID 这种操作，应该由前置的
authMiddleware解析 JWT 后存到c.Set("site_id", xxx)，后续中间件直接取 - 审计日志中间件必须支持
c.GetBool("skip_audit")，方便测试或内部调试绕过
服务治理能力不能靠“加插件”补
Go-Zero 内置熔断限流，Gin 却得自己集成 gobreaker 和 golang.org/x/time/rate。但问题不在选型，而在设计时是否预留了钩子。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 所有 RPC 调用必须经过统一出口函数
rpc.Call(ctx, service, method, req)，而不是散落在各处的client.Do() - HTTP client 必须用封装后的
httpx.Client，它默认带超时、重试、指标打点，且允许按 path 前缀关闭重试（比如对 /healthz 不重试） - 熔断状态不能只存在内存里：生产环境必须持久化到 Redis，否则单实例重启就丢失熔断记忆
接口抽象要面向业务变更，而非技术实现
当智能开放平台要接入三家不同 AI 厂商的模型时，如果当时定义的是 type BaiduAIClient struct，现在就得改三处；但如果一开始定义 type AIModel interface { Predict(ctx context.Context, input string) (string, error) }，新增厂商只需实现这个接口。
- 数据库层抽象用
Repo接口，而非 ORM 实体：比如SubjectRepo只暴露Create/FindBySiteID，不暴露UpdateByID这种易被滥用的方法 - 第三方对接统一走 adapter 层：
hismiddleware.HISAdapter包含GetPatientInfo和SyncVisitRecord，内部可切换 HL7 v2/v3 或 FHIR - 所有接口方法参数必须是 struct，禁止裸传多个 string/int：既便于扩展字段，也利于 mock 测试
最难的不是写代码，是判断某个功能该放进框架还是交给业务代码——比如 JWT 秘钥轮换，框架只提供 ParseToken 接口和 key fetcher 注册点，具体怎么从 Vault 拉密钥、何时刷新，得由业务决定。
