1. 先把这套东西拆开看它到底解决什么问题第一次接触 GoFly 这套内部代号的项目时我脑子里冒出来的第一个念头是市面上中后台框架已经多到看不过来为什么还要自己攒一套带着这个疑问把代码翻了一遍又跟着跑了两个真实项目之后我大概理解了它的定位——它不是又一个万能脚手架而是把医疗行业中后台这一个极其具体的场景里反复出现的脏活累活提前固化成了基础设施。换句话说它解决的不是怎么写 CRUD而是怎么让十个租户的数据不串、让每一次敏感操作都留痕、让运营端和业务端共用一套代码又不互相拖累。这套框架的技术底座是 Go Vue 的前后端分离后端用 Go 承担网关、鉴权、多租户上下文、审计、业务接口前端用 Vue 做 Admin平台运营端和 Business租户业务端两套界面共享组件库与请求层。适用人群很明确——手里有 3 到 10 人规模的后端小团队需要在一两个月内交付一个能同时服务多个客户机构的中后台系统或者你正在维护一个已经有点失控的老项目想看看别人是怎么把租户隔离、权限、审计这几件事做成横切能力的。基础要求不高会写 Go 的 handler、看得懂 Vue 的 Composition API剩下的这篇里都能补。我特别想先把一件事讲透医疗级这三个字在工程上到底意味着什么。很多人第一反应是要过认证但我实际接触下来它在代码层面体现为几条很硬的约束——数据必须能追溯来源和变更、任何越权访问都要被拦住、敏感字段默认不可见、批量导出要单独管控、删除不能是真删。这些约束如果不在框架层解决而是等到每个业务模块自己去做最后一定是每个模块的做法都不一样验收时挨个返工。GoFly 的价值就在于它把这些做成了默认行为业务开发只要不主动破坏天然就是合规的。而 SAAS 多租户隔离和 Admin/Business 双端一体化是这套框架另外两根支柱。前者决定了你的产品能不能一个实例服务多个客户后者决定了你的团队要不要维护两套几乎一样的代码。这两件事听起来都不难真正动手做过的都知道坑有多密——租户 ID 漏传一个接口就是数据泄露级别的 bug双端共用代码一旦边界没划清改运营端的功能会莫名其妙影响业务端。下面我就按怎么想—怎么做—怎么踩坑—怎么排查的顺序把这几块拆开讲。2. 整体设计与选型为什么是这套组合2.1 中后台项目真正的时间黑洞在哪一个新中后台项目从零开始真正写业务逻辑的时间通常只占三成左右剩下七成全耗在人人都需要、但谁写都差不多的地方登录鉴权、菜单权限、按钮权限、数据字典、文件上传、操作日志、导入导出、定时任务、消息通知、分页封装、统一异常处理、接口文档。这些模块单拎出来任何一个都不复杂但加起来的重复劳动非常可观而且每个新同事进来都要重新熟悉一遍写法。我的判断标准很朴素如果一套框架能让我在拿到需求后的第一天就开始写患者随访记录这种真正的业务表而不是先花三天搭登录页那它就值。GoFly 的路由分层、中间件链、代码生成器基本做到了这一点——建完表跑一次生成列表页、详情页、增删改查接口、权限点就都出来了剩下的时间全部投在业务规则上。这个起步速度对承接项目制交付的团队来说是能直接换算成成本的。2.2 医疗场景给框架带来的额外约束普通电商中后台删错一条订单大不了赔钱道歉医疗相关的系统里一条记录被改错、被越权看到、被删掉找不回来后果完全不是一个量级。所以这套框架在设计上有几处反直觉的坚持我认为都很值得借鉴逻辑删除是默认物理删除几乎不开放。表结构里统一带deleted_at业务层提供的删除接口实际执行的是标记删除真要清理得走后台的运维流程并二次确认。写操作强制留痕。新增、修改、删除、导出、审批这几类动作会被审计中间件捕获记录操作人、租户、IP、请求参数脱敏后、耗时、结果。敏感字段在 DTO 层就切断。手机号、证件号、住址这类字段在实体里是完整存储的但出参结构体里默认不返回需要单独授权才解密展示。权限的最小可用原则。默认拒绝菜单、按钮、接口、数据范围四层都要显式授权新加的功能点不会因为忘了关而默认开放。这几条如果让每个业务团队自己约定几乎不可能执行一致。做成框架默认行为之后最差的情况也只是有人写了个绕过审计的自定义接口而这种情况在代码评审里是一眼能看出来的。2.3 Admin/Business 双端一体化到底省了什么先说清楚双端是什么Admin 端是平台方自己用的管理租户开通、套餐、配额、全局配置、租户健康度Business 端是租户方用的也就是每个客户机构的员工登录后看到的那套业务界面。两端的用户体系、权限体系、菜单体系是同源的但可见范围完全不同。一体化不等于一套界面两种角色那是偷懒最后会做成四不像。GoFly 的做法是同一仓库、同一套基础设施、两个独立入口共享的有请求封装、状态管理、权限指令、基础组件、工具函数独立的是路由树、布局、菜单配置、以及各自的页面目录。构建时通过环境变量区分入口产出两份静态资源部署时挂在不同的路径下比如/admin和/console也可以分开部署到不同的域名。这么设计的好处很实在修一个日期选择器的 bug两端同时生效但运营端加一个租户配额调整页面不会让租户端多出半行代码。我的经验是双端复用一定要在基础设施层复用绝对不要试图在页面层复用——凡是出现if (isAdmin)的页面组件最后都会变成维护噩梦。2.4 SAAS 多租户三种隔离方案与选择理由这是整个项目里最需要想清楚的一个决策因为它一旦定下来后期改动成本极高。三种主流方案的对比我整理成了下面这张表隔离级别数据存放方式隔离强度运维成本适用规模独立数据库每租户一个 DB最高高扩容迁移都麻烦少量大客户、强监管场景共享库独立 Schema一个库多个 schema较高中连接数增长快中等数量租户共享库共享表单表加tenant_id依赖代码纪律低大量中小租户GoFly 默认走的是共享库共享表 tenant_id字段隔离同时保留了通过配置切换到独立库的能力大客户单独开一套。选它的理由有三条一是租户数量预期在几百这个量级独立库的连接池和迁移成本扛不住二是运营端需要做跨租户的聚合统计共享表一条 SQL 就能出结果独立库就得写循环三是框架层能通过 GORM 的全局 Scope 把tenant_id条件自动注入人为漏写的概率被压得很低。注意共享表方案的安全边界完全依赖每条 SQL 都带租户条件。所以框架里必须有一层强制的自动注入并且在代码评审时把任何手写原生 SQL 的地方都标红检查。我见过太多项目业务跑了两年某个统计接口忘了加租户条件直接把 A 客户的汇总数据展示给了 B 客户。3. 核心机制拆解租户隔离是怎么落到代码里的3.1 租户识别链路从登录请求到 context租户识别是整条链路的起点做错了后面全错。这套框架的识别顺序是登录时确定租户 → 签发带租户信息的令牌 → 请求进来后由中间件解析并注入上下文 → 全链路透传。登录接口本身是无租户的它需要先根据账号或者租户编码定位到具体租户再校验该租户下的用户。这里有个细节值得说Business 端登录页通常要求用户输入机构编码 账号 密码机构编码就是为了定位租户Admin 端的运营人员则属于平台级租户一般tenant_id 0或者一个保留 ID可以跨租户查看。两套登录逻辑共用一套令牌签发但令牌里的 claims 不同。// 令牌载荷租户信息必须签进去不能靠前端传 type Claims struct { UserID int64 json:uid TenantID int64 json:tid Scope string json:scope // platform / tenant jwt.RegisteredClaims } // 鉴权中间件解析令牌把租户和用户塞进 context func AuthMiddleware() gin.HandlerFunc { return func(c *gin.Context) { token : strings.TrimPrefix(c.GetHeader(Authorization), Bearer ) claims, err : ParseToken(token) if err ! nil { c.AbortWithStatusJSON(401, gin.H{code: 40101, msg: 登录状态失效}) return } ctx : context.WithValue(c.Request.Context(), ctxKeyTenant, claims.TenantID) ctx context.WithValue(ctx, ctxKeyUser, claims.UserID) ctx context.WithValue(ctx, ctxKeyScope, claims.Scope) c.Request c.Request.WithContext(ctx) c.Next() } }注意一个特别容易犯的错租户 ID 绝对不能从请求头、query 参数或者 body 里取。只要允许前端传就等于把隔离开关交给了浏览器。我见过一个项目为了方便调试加了个X-Tenant-Id头做覆盖上线三个月后被人扫出来直接成了跨租户读数据的入口。3.2 GORM 层自动注入租户条件拿到 context 里的租户 ID 之后怎么保证每条查询都带上它框架的做法是封装一个TenantDB(ctx)方法返回一个已经挂好租户 Scope 的*gorm.DB实例业务代码统一从这里拿句柄不允许直接用全局db。func TenantDB(ctx context.Context) *gorm.DB { tid : TenantIDFromCtx(ctx) return globalDB.WithContext(ctx).Scopes(WithTenant(tid)) } // 全局 Scope自动追加 tenant_id 条件 func WithTenant(tid int64) func(*gorm.DB) *gorm.DB { return func(db *gorm.DB) *gorm.DB { if tid 0 { // 平台级查询显式放行 return db } return db.Where(tenant_id ?, tid) } }这个写法能覆盖 90% 的场景但有几个坑必须提前知道。第一Updates和Delete同样会走 Scope这是好事但如果你用db.Model(X{}).Where(...)却没从TenantDB拿句柄Scope 就不生效。第二Joins关联查询的租户条件需要手动补因为 Scope 只作用于主表。第三原生 SQLRaw完全绕过 Scope这是最危险的口子。我的处理办法是加一条团队约定所有Raw调用必须在旁边写一行注释说明租户条件是怎么保证的代码评审时重点看这一行。同时在测试环境做一个租户穿透测试——用 A 租户的令牌去请求所有接口断言返回里不包含 B 租户的主键这个用例跑起来很土但极其有效能挡住绝大多数低级泄漏。3.3 平台侧合法越权与跨租户聚合运营端要看所有租户的日活趋势这个查询天然是跨租户的。如果粗暴地给平台账号也塞一个tenant_id 0那所有业务表都会查到空数据。所以框架里区分了两种上下文租户上下文和平台上下文。平台上下文下TenantDB不追加任何条件但要额外经过一道跨租户操作审计——这类查询会被单独记录包含操作人、涉及租户数量、耗时。涉及明细数据的接口比如查看某租户的用户列表必须显式传入目标租户 ID并且校验该运营人员是否有该租户的授权范围不能因为是平台账号就无差别放行。聚合统计我建议单独走一条读路径直接查从库或者预聚合表不要复用业务查询。原因很简单跨租户的GROUP BY tenant_id在数据量大之后会拖垮主库而且这类查询的 QPS 和业务查询完全不是一个量级。我们后来的做法是每天凌晨跑一次汇总任务把每个租户的关键指标落到一张统计表里运营端只查这张表响应时间从秒级降到了几十毫秒。3.4 租户开通与数据初始化新租户开通看起来只是插一条记录实际上要做的事情不少创建租户主记录、初始化该租户的套餐和配额、生成默认角色和菜单权限、初始化业务字典、创建第一个管理员账号、发开通通知。这一串动作必须在一个事务里完成失败要整体回滚否则会出现租户建了但管理员没建的僵尸状态。func ProvisionTenant(ctx context.Context, req ProvisionReq) error { return globalDB.Transaction(func(tx *gorm.DB) error { tenant : Tenant{Code: req.Code, Name: req.Name, Status: StatusActive} if err : tx.Create(tenant).Error; err ! nil { return err } // 默认角色与权限模板 if err : initDefaultRoles(tx, tenant.ID); err ! nil { return err } // 业务字典 if err : initDicts(tx, tenant.ID); err ! nil { return err } // 首个管理员 admin : User{TenantID: tenant.ID, Account: req.AdminAccount, Source: provision} if err : tx.Create(admin).Error; err ! nil { return err } return nil }) }套餐配额我建议做成软限制接近上限时提醒超过上限时只拦截写操作、不拦读操作。硬拦所有请求的体验非常差客户会觉得系统突然坏了而实际上只是配额用完。软限制配合告警运营能提前介入沟通转化的成功率反而更高。3.5 数据库连接池参数怎么算这是很多团队凭感觉填、最后被打脸的地方。共享库方案下所有租户共用一个连接池参数设错的直接后果是高峰期大面积超时。我的估算方法是这样假设单实例的峰值 QPS 是 800平均每个请求的 SQL 耗时 15ms那么并发所需的连接数大约是800 × 0.015 ≈ 12。但这是平均值实际上短事务和慢查询混在一起所以要在平均值上给 3 到 5 倍冗余MaxOpenConns设 50 到 80 比较合理。MaxIdleConns通常设为MaxOpenConns的 60% 左右避免频繁建连。ConnMaxLifetime建议 30 分钟比数据库侧的空闲断开时间短防止拿到服务端已经关闭的死连接。datasource: max_open_conns: 64 max_idle_conns: 40 conn_max_lifetime: 30m conn_max_idle_time: 10m还有一条经验连接数不是越多越好。数据库侧的max_connections是全局的你一个应用开 200 个连接多副本部署就是 600 个很容易把数据库打满。宁可应用侧排队也不要让数据库侧雪崩。压测时我会专门看两个指标——连接池等待时长、以及WaitCount的增长趋势前者超过 5ms 就说明该调了。4. 权限、审计与合规要点4.1 三层权限模型功能、数据、字段中后台的权限如果只做到这个菜单能不能看见迟早会出问题。GoFly 分了三层每层的实现方式完全不同值得单独说。功能权限是最外层控制菜单和按钮的可见性本质是一串权限码比如biz:record:create存在角色上角色赋给用户。前端通过自定义指令v-perm控制元素渲染后端通过中间件校验接口权限码。关键点是后端校验必须独立完成不能因为前端隐藏了按钮就认为没人能调这个接口——打开开发者工具直接发请求是最常见的越权方式。数据权限是中间层控制能看到哪些行。典型场景是科室隔离某个医生只能看本科室的记录。实现方式是在查询里追加数据范围条件范围规则挂在角色上本人、本部门、本部门及下级、全部。这块最容易出 bug 的地方是规则的组合——一个用户可能有多个角色数据范围要取并集还是交集我们的做法是取并集权限放宽但要记录一条多角色的提示让管理员知道这个人的可见范围可能超出预期。字段权限是最内层控制能看到哪些列。这层在医疗场景尤其重要比如检验结果里的敏感项默认打码需要单独授权才能查看明文。实现上是在 DTO 转换层做的出参结构体里对敏感字段做条件赋值未授权时置空或替换为掩码。type RecordVO struct { ID int64 json:id Name string json:name Phone string json:phone } func toVO(u *Record, hasFieldPerm bool) *RecordVO { vo : RecordVO{ID: u.ID, Name: u.Name, Phone: maskPhone(u.Phone)} if hasFieldPerm { vo.Phone u.Phone // 有授权才给明文 } return vo }4.2 审计日志记什么、怎么记、怎么存审计日志的价值在于事后能还原所以字段设计要围绕还原这件事来。我们最终定下来的必填字段是操作人、租户、操作类型、资源类型、资源主键、变更前后快照脱敏、IP、UA、请求耗时、结果状态、链路 ID。其中变更前后快照是最有用的客户投诉这个数据被谁改了的时候直接对比快照就能给出答案。性能上必须做两件事一是异步落库审计日志走独立的 goroutine 池或者消息队列不阻塞主流程二是分表或按时间分区日志表的增长速度远超业务表一个中等规模的租户一年就能产出几千万条记录。我们的做法是按月分表只在线保留 12 个月更早的归档到冷存储。注意异步落库一定要处理队列满了怎么办。我们的策略是队列使用率超过 80% 时降级为同步写宁可慢一点也不能丢审计记录。丢一条审计日志在验收时可能就是致命问题。4.3 敏感字段的加密与脱敏什么时候用加密、什么时候用脱敏很多团队分不清。简单区分脱敏是显示层面的处理数据库里还是明文加密是存储层面的处理数据库里存的是密文。前者防的是别人偷看屏幕后者防的是数据库被拖走。我的判断标准是手机号、邮箱这类需要模糊查询或者做提醒的字段用脱敏 存储明文加列级权限证件号、住址、病历描述这类既敏感又不需要检索的字段用加密存储。加密用 AES-GCM密钥放在配置中心或环境变量里绝不进代码仓库。加密后如果需要按该字段查询就只能做精确匹配存哈希索引这一点在设计阶段就要想清楚否则后期改起来极其痛苦。4.4 双端鉴权模型的差异Admin 端和 Business 端虽然共用令牌签发逻辑但授权模型确实不同。Admin 端是岗位制权限跟着岗位走运营、客服、财务各管一摊权限变化不频繁Business 端是角色制每个租户可以自定义自己的角色和权限组合灵活度要求高而且租户管理员自己就能改。这带来一个实现上的差异Admin 端的菜单树在代码里静态定义权限码硬编码升级时直接覆盖Business 端的菜单树从数据库读租户初始化时根据套餐复制一份模板之后租户自己调整。这意味着 Business 端的菜单要做租户级别的版本管理——我们吃过亏全局模板更新之后部分租户的菜单出现了父菜单没了子菜单还在的孤儿节点前端直接白屏。后来加了初始化脚本做一致性校验才彻底解决。5. 从零到跑通一个业务模块的完整实操5.1 环境准备与本地起服务本地环境需要 Go 1.21 以上、Node 18 以上、MySQL 8.0低于 8.0 的话窗口函数和一些 JSON 特性用不了统计模块会受影响、Redis 7。依赖管理后端用 go mod前端用 pnpm。# 后端 cp configs/config.example.yaml configs/config.local.yaml # 修改数据库、Redis 连接串然后 go run ./cmd/server -c configs/config.local.yaml # 前端 cd web pnpm install pnpm dev:admin # 运营端默认 5173 pnpm dev:business # 业务端默认 5174第一次启动会自动执行迁移脚本建表并写入基础数据平台租户、超级管理员、默认菜单。我建议本地开发时把 SQL 日志打开log.level: debug能直观看到每条查询有没有带租户条件——这是最便宜的隔离检查手段。5.2 建表与租户字段规范业务表的设计有几条硬性约定违反了后面的代码生成和 Scope 注入都会出问题主键统一bigint自增必须包含tenant_id bigint not null、created_at、updated_at、deleted_at所有需要唯一约束的字段唯一索引必须带上tenant_id。CREATE TABLE biz_followup ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, tenant_id BIGINT UNSIGNED NOT NULL, patient_no VARCHAR(32) NOT NULL, content TEXT, status TINYINT NOT NULL DEFAULT 0, created_by BIGINT UNSIGNED NOT NULL, created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3), updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3), deleted_at DATETIME(3) NULL, PRIMARY KEY (id), UNIQUE KEY uk_tenant_patient (tenant_id, patient_no, deleted_at), KEY idx_tenant_created (tenant_id, created_at) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有个经典坑deleted_at参与唯一索引是为了让删除后可以重建同编号记录。但 MySQL 里 NULL 不参与唯一性判断所以同一条记录可以被逻辑删除多次而不报错。解决办法是用deleted_at存时间戳默认 0 表示未删或者干脆加一个deleted_flag。我们最后选了后者简单直接。5.3 后端接口实现用代码生成器生成基础 CRUD 之后我一般会重写 List 和 Create 两个方法把租户和审计的细节落实。列表接口的重点是分页参数、数据权限、以及避免count(*)拖慢查询。func (s *FollowupService) List(ctx context.Context, req ListReq) (*ListResp, error) { db : TenantDB(ctx).Model(Followup{}). Scopes(DataScope(ctx, biz_followup)) // 数据权限 if req.PatientNo ! { db db.Where(patient_no ?, req.PatientNo) } var total int64 if err : db.Count(total).Error; err ! nil { return nil, err } var rows []Followup err : db.Order(id DESC). Offset((req.Page - 1) * req.Size).Limit(req.Size). Find(rows).Error if err ! nil { return nil, err } return ListResp{Total: total, Items: toVOList(rows)}, nil }创建接口除了写业务数据还要做两件事从上下文补tenant_id和created_by绝不允许前端传以及触发审计事件。审计我封装成了一个装饰器式的方法业务代码里只写一行audit.Record(ctx, biz:followup:create, row)具体落库逻辑在中间层统一处理。分页查询有个性能细节数据量大时Count会是瓶颈。我的做法是当total不需要精确时比如前端只显示约 1 万条用EXPLAIN估算行数需要精确时把Count的查询条件尽量收窄或者单独走从库。5.4 前端页面与动态路由Business 端的路由是动态的登录后拉取当前用户的菜单树转换成路由配置再addRoute。这里最容易出两个问题一是刷新页面后动态路由丢失表现为 404二是路由守卫死循环表现为白屏。// 路由守卫的正确写法先判断是否已加载再决定拉菜单还是直接放行 router.beforeEach(async (to, from, next) { if (to.path /login) return next() const store useUserStore() if (!store.token) return next(/login) if (store.routesLoaded) return next() try { await store.loadMenus() // 拉菜单 addRoute store.routesLoaded true return next({ ...to, replace: true }) // 关键重新匹配一次 } catch (e) { store.reset() return next(/login) } })next({ ...to, replace: true })这一行是关键直接next()的话当前这次导航用的还是旧的路由表匹配不到新加的路由就 404 了。这个问题我至少见过五六个项目踩。5.5 联调与验收清单功能写完不算完我习惯在提测前过一遍这张单子能省掉大量返工检查项检查方式通过标准租户隔离用 A 租户令牌遍历所有接口响应中不出现 B 租户数据越权防护去掉按钮权限后直接发请求统一返回 403审计完整执行增删改导出日志表均有记录且字段齐全敏感字段未授权账号查看详情敏感列显示掩码大数据量列表页 10 万条数据翻页首屏 1s 内翻页 500ms 内导出导出 5 万行不超时文件可正常打开6. 部署与性能上线前必须过的几道关6.1 单二进制打包与前后端同源Go 的一个很实用的特性是能把前端构建产物用embed打进二进制部署时只需要传一个文件配合配置文件就能跑起来。这对私有化交付特别友好——客户现场往往只有一台机器没有 CI多传一个静态资源目录就多一分出错的可能。//go:embed all:dist var adminFS embed.FS func AdminAssets() http.FileSystem { sub, _ : fs.Sub(adminFS, dist) return http.FS(sub) }注意all:前缀不加的话以点开头的文件比如.well-known下的内容会被忽略。另外单页应用要配一个 fallback 规则非静态资源的路径统一返回index.html否则用户直接访问深层路由会 404。6.2 数据库迁移与灰度多租户系统的迁移有三条铁律可重复执行、向前兼容、先改代码再改结构。加字段没问题删字段和改类型一定要分两次上线——第一次让代码兼容新旧两种结构第二次再真正删掉旧字段。否则灰度期间新旧实例同时跑老实例读到新结构直接报错。迁移脚本我会放在代码库里做版本管理用一张schema_migrations表记录已执行的版本号启动时自动比对。大表加字段在 MySQL 8.0 上基本是 online DDL但如果表超过千万行我建议还是走 gh-ost 或者手工分批避免长时间锁表。6.3 压测看什么指标压测不是看 TPS 数字好不好看而是找瓶颈在哪。我一般只盯四个指标P99 延迟、错误率、连接池等待、慢查询数量。前两个反映用户体感后两个定位问题根源。一个实际的例子压测时 P99 从 80ms 突然涨到 900ms错误率没变。翻了慢查询日志发现是某个跨租户的统计接口在做全表扫描没走索引。加了一个(tenant_id, created_at)的联合索引之后恢复正常。这类问题在功能测试阶段完全看不出来只有压测才暴露。我建议每个新上线的列表页都至少跑一次 500 并发的短压测成本很低收益很大。7. 常见问题与排查实录7.1 高频故障速查表下面这些是我在几个项目里真实遇到过的问题按出现频率排序现象可能原因排查方法处理方式数据串租户用了全局 db 而非 TenantDB搜代码里所有globalDB.直接调用改为 TenantDB加穿透测试goroutine 里查不到数据context 未透传租户 ID 为 0日志打印上下文里的 tid显式传 ctx禁止context.TODO()刷新页面 404动态路由未重新匹配看路由守卫逻辑next({...to, replace:true})唯一索引冲突deleted_at为 NULL 不参与唯一性查重复数据改用deleted_flag或时间戳时间差 8 小时数据库时区与 Go 时区不一致对比SELECT NOW()与程序时间统一 UTC 存储展示层转换导出超时一次性加载全部数据看内存和 SQL 耗时分批流式写加进度反馈菜单白屏孤儿节点导致路由树构建失败校验父子关系初始化脚本做一致性检查审计日志丢失异步队列满后直接丢弃看队列使用率监控超阈值降级为同步写7.2 几个值得单独说的坑第一个坑goroutine 里丢租户上下文。典型场景是异步发通知。主流程里起了个go func()里面直接调了 service 方法结果 service 从 context 里拿不到租户 ID查出来是空的报错又因为异步被吞掉了最后表现为通知有时候发不出去。解决办法很简单——起协程前先把需要的上下文值取出来显式传进去别依赖隐式的 context 传递。// 正确做法 tid : TenantIDFromCtx(ctx) uid : UserIDFromCtx(ctx) go func(tenantID, userID int64) { ctx2 : WithTenantCtx(context.Background(), tenantID, userID) notify(ctx2, ...) }(tid, uid)第二个坑逻辑删除与唯一约束的冲突。前面提过一次这里补充完整。如果deleted_at是DATETIME NULL那么被逻辑删除的记录deleted_at有值理论上参与唯一性判断但同一行连续删两次就会冲突第二次把值改成新的时间中间可能有毫秒级重复。更稳妥的方案是加一个is_deleted TINYINT DEFAULT 0参与唯一索引删除时置 1重建时插 0简单可靠。第三个坑时区。存储全用 UTC展示层按用户所在的时区转换这条原则大家都知道但实际做的时候经常被time.Now()破坏。我们的规矩是数据库连接串里明确写locUTCparseTimetrue业务代码里禁止直接time.Now()统一走封装好的clock.Now()方便测试也方便统一处理。这个规矩在跨时区客户上线时救过一次命——某个客户的服务器时区设成了本地时间如果没有统一封装查出来的数据会整体偏移 8 小时。第四个坑批量导出把内存打爆。一开始的实现是查出全部数据再序列化5 万行的时候内存直接飙到 2G。后来改成流式写 CSV游标分批查每批 2000 条边查边写csv.Writer内存稳定在 100M 以内。同时加了导出任务表异步执行 完成后站内通知用户不用一直盯着页面转圈。第五个坑租户切换后的缓存脏数据。有些配置做了本地缓存key 里忘了拼租户 ID结果 A 租户改了配置B 租户读到了 A 的值。教训是凡是和租户相关的缓存 key一律以租户 ID 开头这条规则写进团队的编码规范里评审时必查。8. 我在实际项目里的几点体会踩过这些坑之后我对这类框架的评价标准变了一个方向——不再看它功能有多少而是看它在你不注意的时候能不能兜住底。功能多是加分项但兜底能力是及格线。GoFly 让我比较认可的地方恰恰是它把租户条件必须带敏感字段默认不返回写操作必须留痕这几件事做成了默认行为你写得再随意也不太容易越过红线。另外一个很实际的感受是共享表的多租户方案一定要配一套自动化的隔离测试。我们现在每次发版前都会跑一个脚本随机挑三个租户用各自的令牌把所有接口遍历一遍比对返回结果里是否出现了其他租户的主键。这套东西写起来不到两百行但它拦下来的问题比我做过的所有代码评审加起来都多。最后分享一个小技巧。框架自带的权限点、菜单、字典这些基础数据很容易在多人协作时被改乱。我的做法是在仓库里放一份基准快照YAML 格式CI 里跑一个比对任务一旦发现有人在数据库里直接改了权限却没同步到快照就报警。这个机制看着有点笨但确实把线上线下权限不一致这类玄学问题挡在了上线之前。
