@Comment("Whether records of this model carry a comment stream (needs the erupt-comment module)")boolean comment() default true;
前端读它决定要不要显示入口,服务端也读它决定要不要接受写入:
java
private void checkEnabled(String erupt) { EruptModel model = EruptCoreService.getEruptWithRemote(erupt); if (null != model && !model.getErupt().power().comment()) { throw new EruptWebApiRuntimeException("Comments are disabled for " + erupt); }}
@Comment("Whether erupt-cloud-server may forward this API to the node that owns the erupt. " + "Turn it off for a server-owned API that only keys on the erupt name (record comments, " + "for example): the node neither carries the module nor knows the server's users, so the " + "server must answer the call itself, under the 'nodeName.eruptName' it addressed")boolean cloudProxy() default true;
EruptCloudServerInterceptor 在任何节点路由之前先看它:
java
// Server-owned API (record comments and the like): the erupt name may point at a node, but the// answer lives here — the node carries neither the module nor the users the data refers to.if (!eruptRouter.cloudProxy()) return true;
第 11 期 · 记录评论为什么不绑定业务表
每期专题首发于此,另有版本动态、源码解读、社区精选案例。
一、为什么写这篇
先说需求是怎么来的。
用户的原话通常是:"这条退款单为什么退了?财务问我,我只能去翻群聊。" 后台系统天然缺一层记录级的对话——不是操作日志(那是机器写的、说"谁改了什么"),而是人写的、说"为什么"。
国内平台都做了这层,但都把它挂在了一个具体的业务对象上:
xxx_comment。三条路径的共同点是:评论的生命周期,依附于某个具体的业务对象定义。 定义有多少个,这层就要长多少遍。
本文的反向命题是:
第一句是老生常谈,第二句才是这一期真正想讲的——在 erupt-cloud 的多节点部署里,记录在节点上,评论必须留在中心。这一条会逼出一个核心注解的新属性。
二、两种做法:纵向挂载 vs 横切寻址
erupt-comment)Long/UUID/ 复合串通吃@Power(comment = false)「横切」的代价是放弃了数据库外键——评论表和业务表之间没有任何约束。我们认为这笔交易划算:外键换来的是引用完整性,而一条针对已删除记录的历史评论,本来就应该留着。
三、九个类、七条路由、一个可选依赖
先给可数的事实。整个模块在
erupt-plugin/erupt-comment/:e_record_comment,联合索引(erupt, recordId)/erupt-api/comment/**erupt-notice七条路由如下(
EruptCommentController):GET/{erupt}/{id}POST/{erupt}/{id}parentId与mentions)POST/{erupt}/countsGET/{erupt}/mention-users@时的候选人PUT/{erupt}/{id}/{commentId}/resolvedPUT/{erupt}/{id}/{commentId}/pinnedDELETE/{erupt}/{id}/{commentId}注意
counts和mention-users是字面量段,排在{id}变量之前——这是 Spring 路由的既有规则,但把它写进注释是为了防止后来人加一条GET /{erupt}/{something}时踩坑。@mention 是可选的。
erupt-notice在 pom 里标了<optional>true</optional>,通知器整个类挂在@ConditionalOnClass上:服务层用
ObjectProvider拿它,拿不到就跳过:没装
erupt-notice时,@依然会被解析、存进mentions字段、在前端高亮——只是没人收到站内信。降级是静默的,不是报错的。catch块也值得说一句:发信失败只打日志。一条评论已经写进库了,不该因为通知链路抽风而回滚。四、寻址:把主键当字符串存
这是全模块唯一一个"设计决策",其余都是它的推论。
三个决定:
recordId是String。 于是Long主键、UUID主键、甚至复合主键拼出来的串,都能进同一张表。代价是查询只能走那个联合索引、做不了 join——对一个「打开一条记录时读十几行」的场景,这不是问题。mentions存的是快照[{id, name}],不是外键。 用户改名之后,历史评论里显示的还是当时那个名字。这是刻意的:评论是一段历史记录,不是一个实时视图。写入前会过一遍resolveMentions,只保留真实存在的用户 id,杜绝前端伪造。线程只有一层。 回复一条回复,会被拉平到它的顶层:
没有无限嵌套,也就没有渲染缩进的递归、没有"删中间节点怎么办"。删顶层时把它的回复一并带走,就是全部的级联逻辑。
开关在
@Power上(xyz.erupt.annotation.sub_erupt.Power,2.2.0 新增):前端读它决定要不要显示入口,服务端也读它决定要不要接受写入:
圈出一个反直觉的小结
这张表故意不知道自己在给谁存评论。所以后台那张「评论记录」管理表里,"模型"这一列不能直接展示
erupt的原始值——那是个类名,对人没有意义。CommentEruptChoice反过来查:先select distinct c.erupt找出真的有人评论过的模型,再用@Erupt(name)作为标签交给EruptUtil.getChoiceList走一遍 i18n。于是筛选框里只会出现真实存在过的模型,一个没人评论过的模型不配占一个选项;一个已经被删掉的模型,则用它自己的名字继续指认自己。
五、
cloudProxy = false:记录在节点,评论在中心 前面都还算常规。真正被逼出来的设计在这里。
erupt-cloud的默认语义是:erupt 名字指向哪个节点,请求就转发到哪个节点。中心只是一个网关,业务模型和数据都在节点上。这条规则以前对所有 API 都成立。评论是第一个必须打破它的 API。因为一条评论由四样东西组成——评论表、作者、@ 候选人、站内信——它们全都在中心。节点既没装这个模块,也没有用户体系,它根本答不上来。
于是
@EruptRouter加了一个属性(erupt-core,xyz.erupt.core.annotation.EruptRouter):EruptCloudServerInterceptor在任何节点路由之前先看它:默认
true,所以现存的每一条路由行为不变。评论的七条路由全部标cloudProxy = false。妙处在于寻址不需要任何额外映射:请求进来时 erupt 名字已经是
nodeName.eruptName(云菜单本来就是这么注册的),这串东西直接就是评论行的 key。中心不需要知道这条记录长什么样,只需要知道它被叫作什么。一个刻意的取舍写在
checkEnabled的注释里:节点模型解析出来的是一个带注解默认值的远程占位对象,power().comment()读不到节点上的真实声明。我们没有为此回节点取一次。 理由是浏览器据以显示入口的 build model 本来就来自节点,节点自己的 opt-out 在客户端已经生效;为服务端这一道兜底去换一次 HTTP 往返,每写一条评论都要付,不值。这一条推广到别处
cloudProxy不是给评论开的后门,它是 core 对 cloud-server 说「这条 API 归中心」的唯一一个点。任何只按 erupt 名字寻址、数据却落在中心的能力——收藏、订阅、标签、审批意见——以后都用同一个开关。六、跟宜搭 / 简道云 / JeecgBoot 怎么比?
erupt-comment@Erupt模型的任意一行@Power(comment = false)erupt-notice,模块缺席则静默降级cloudProxy = false)e_record_comment最后一行是这一期真正的分野。SaaS 平台上,"评论存在哪"不是一个你能回答的问题;
erupt-comment里它是一张你能select *的表,甚至能在后台以普通模型的形态打开(菜单挂在系统管理下,和登录日志、操作日志并列——它就是一种日志)。七、5 分钟上手
从空 Spring Boot 项目到能访问的 admin 页面,完整流程已经独立成一篇:
→ 快速部署 / Quick Start
那一页覆盖 Maven 依赖、
application.yml、第一个@Erupt实体、默认登录账号,以及 Docker / K8S 部署。跑通之后,本模块只要加一个依赖(用
erupt-spring-boot-starter-all的话已经包含了):装上即生效——所有
@Erupt模型的记录面板里都会出现评论入口。要给某个模型关掉:想让
@真的发出站内信,再补一个erupt-comment之外的可选依赖:不加也能用,见 §三。
参与讨论
本期专题对应的核心源码在
erupt-plugin/erupt-comment,cloudProxy在xyz.erupt.core.annotation.EruptRouter。欢迎在 GitHub Discussions 留贴。贡献者
页面历史