有段时间我的工作内容基本被“后台”刷屏了。今天给运营做订单管理后台明天给客服搭工单系统后天又得给风控同学整理规则配置界面……表面上看每个系统都不一样拆开之后全是同一套骨架登录、权限、菜单、日志、文件上传、定时任务、系统配置。做到第三个的时候我还能打打鸡血做到第七八个我是真的开始怀疑自己天天写增删改查代码能力没长进工作成就感还越来越低。于是就有了 XinServer。它不是什么商业产品也不是某个知名开源框架而是我把自己折腾过的各类后台系统里反复出现的那部分能力抽出来重新设计的一套可复用的后台服务底座。目标很简单以后再接新后台登录认证、权限模型、操作审计、任务调度、文件服务、消息通知这些基础能力不再重写业务方只需要写好业务本身的逻辑剩下的交给底座。这篇文章我就把这个项目的设计思路、模块边界、难点排坑过程完整分享一下给同样被困在“后台泥潭”里的朋友做个参考。1. 重复业务做多了真的会怀疑自己XinServer 的起因1.1 那些翻来覆去写的“公共代码”我先列一下当时遇到的情况。那段时间前后做了大概七个后台类项目有给运营看数据报表的有给客服处理用户工单的有给审核团队做内容复核的还有给财务做结算对账的。从业务形态上看差异很大但从工程实现的视角看公共的部分惊人地一致用户登录、会话管理、密码找回角色权限、菜单管理、按钮级别的权限控制操作日志、登录日志、数据字典文件上传、Excel 导入导出定时任务对账、关单、报表生成系统参数配置、通知消息发送这些功能我在每个项目里都要重新写一遍。第一次写权限模块还挺开心研究 RBAC 模型、设计角色表、写拦截器觉得很有挑战。到了第三个项目我已经可以直接把上一套权限代码复制过来改个表名前缀就完事了。复制多了之后问题就来了七个系统里的权限逻辑有的写在拦截器有的写在 AOP 注解有的直接在 Service 里 if 判断。一旦业务方说“A 系统的权限规则要调整”我得打开几个项目一个个找改完还要担心影响其他功能。更可怕的是质量参差。早期某个项目里的会话管理用的是长期有效的 Token用户离职了账号还在续期安全上留下隐患另一个项目倒是做了过期时间但忘记处理“踢人下线”的逻辑账号可以同时在十几个设备登录。这些坑散落在不同后台里像定时炸弹一样等触发。1.2 为什么不是“找一个现成平台”而是自研后来大家也开始讨论要不要直接引入一个现成的后台框架、低代码平台或者开源的管理系统模板。当时我认认真真拉了个表格评估最后放弃了原因有三点可选方案优点缺点结论复制旧项目代码上手最快每个项目都有自己的“历史包袱”维护成本随时间翻倍不可持续引入开源后台框架功能全、社区活跃定制复杂需求时要绕框架的弯版本升级容易踩兼容坑可以借鉴不能直接套用低代码平台简单需求很快业务规则一复杂平台就成了黑盒出了问题很难定位不适合我们的场景自研一套通用底座完全可控、贴合业务前期设计投入大最终选择另外还有个边界问题。数据库连接池、ORM、缓存、消息队列这些基础组件自己重写没有必要成熟的开源生态已经很稳定了直接用就行。真正值得自己沉淀的是和业务规则强相关、又横跨多系统的那部分能力比如权限模型、数据权限、审计带、任务调度抽象。它们没有一个标准答案换个业务场景需求就变了必须把实现握在自己手里。所以 XinServer 的定位从一开始就很清楚不做“全家桶”只做后台开发里复用率最高的那部分底座每个模块都允许业务方做扩展但改公共逻辑时不至于伤筋动骨。2. 整体设计把底子打对后面才不拧巴2.1 三层模型与模块总线XinServer 的代码结构我搭成了三层内核层、模块层、业务层。内核层只负责最基础的事情包括模块的加载与卸载、统一配置读取、日志上下文、事件总线还有“模块健康检查”。它不包含任何业务概念也不知道“用户”“订单”是什么。模块层放通用能力每个能力是一个独立模块。我在第一版规划了六个核心模块认证、权限、审计、任务、文件、通知。模块之间做到“不知道对方的存在”需要协作时通过事件总线发消息。业务层就是具体项目里真正要写的逻辑比如“查询订单列表”“导出对账单”。这一层可以依赖模块层但模块层绝不能反向依赖某一套具体业务的表结构。为什么这么设计我吃过耦合的苦。以前在一个老项目里发通知的逻辑被直接写在订单服务的代码里后来另一个业务想复用通知能力只能把订单服务里面那段代码复制出去连带复制了一堆无关依赖。模块之间没有总线表面上改一处代码很快实际上到处是隐形的依赖关系。XinServer 里强制模块只认事件和接口不认具体实现类至少在结构上避免了越扯越乱的“蜘蛛网”。2.2 目录结构与模块注册示例我把项目做成了多模块结构大概是这个样子xin-server-core/ # 内核层 ├── module/ # 模块生命周期管理 ├── config/ # 统一配置模型 ├── event/ # 事件总线 └── log/ # 日志上下文 xin-module-auth/ # 认证模块 xin-module-permission/ # 权限模块 xin-module-audit/ # 审计模块 xin-module-task/ # 任务调度模块 xin-module-file/ # 文件模块 xin-module-notify/ # 通知模块 xin-starter/ # 面向业务方的启动器 xin-example/ # 官方示例工程这里有一个关键设计模块不是通过代码里直接 import 来注册的而是每个模块提供一个描述文件内核启动时会自动扫描装配。模块实现统一接口public interface XinModule { String name(); default int order() { return 0; } default void onInit(XinContext context) { } default void onDestroy(XinContext context) { } }每个模块在自己的META-INF/xin-modules文件里声明# META-INF/xin-modules/net.example.xin.module.auth.AuthModule # META-INF/xin-modules/net.example.xin.module.task.TaskModule这样做的好处是加一个模块只需要放一个 jar 包删一个模块也不用去改启动类。多个业务系统可以挑选自己需要的模块组合比如一个纯查询的报表后台可能只需要审计模块和文件模块不需要任务模块那就不引入它。类比一下这就像是电脑主板上的 PCIe 插槽接口标准统一插什么卡由业务方自己定而不是把声卡网卡显卡全焊死在主板上。2.3 配置策略环境分离与默认值后台开发里配置这块我踩过太多“本地能跑测试环境挂了”的坑。XinServer 的配置策略我最终定了三句话默认值写在代码里环境差异写在环境变量里启动时强制打印配置指纹。默认值必须足够“安全”。比如xin.file.max-size默认给 10MB某个环境忘了配置它至少能正常工作而不是因为 null 直接报错。环境变量只覆盖真正有差异的项比如数据库地址、对象存储的桶名、通知渠道的密钥。配置指纹则是把所有生效配置做一个哈希启动时打印出来同时打印哪些配置项来自默认值、哪些来自环境变量、哪些被显式覆盖。这样处理以后多环境问题从“猜”变成了“对指纹”。测试环境说它连的数据库是 A我拿它启动日志里的指纹和开发环境比一下立刻就知道有没有配置漂移省去了四处翻配置文件的排查时间。3. 第一个硬骨头认证、权限和审计一次做透3.1 会话方案短 Token 长 Refresh主动踢人认证模块是第一块硬骨头。后台系统不像 C 端 App 那样弱化管理它要求账号可禁用、会话可吊销、登录设备可查。最开始我图省事直接生成一个有效期 30 天的 Token 扔给前端后来发现安全问题没法处理有同事反馈账号被离职员工继续使用光是“让 Token 立即失效”这件事就做不到。XinServer 最终用了短 Token 加 Refresh Token 的混合方案。简单说客户端登录后拿到的访问 Token 有效期 30 分钟过期后通过 Refresh Token 去换新的。Refresh Token 保存在服务端存储里有效期 7 天每次刷新都会轮换。账号被禁用时服务端直接把该用户的所有 Refresh Token 失效这样最多 30 分钟内访问 Token 也会因为校验失败而退出。方案主动踢人分布式支持实现成本后台场景适配度长有效期 JWT困难好低低纯服务端 Session容易需要会话存储中中短 Token Refresh较好好中高这个方案里最容易忽略的细节是“并发的刷新请求”。前端如果同时发出三个请求三个请求都发现访问 Token 过期各自拿着 Refresh Token 去刷新就可能造成 Refresh Token 重复使用。我在服务端做了并发控制刷新接口使用分布式锁Refresh Token 校验和轮换在同一个事务里完成刷新失败则统一返回重新登录。3.2 RBAC 之外还有数据权限很多后台系统的权限模块做成了“用户-角色-权限点”三层但落到真实业务时发现不够用。比如运营人员能看订单管理菜单但只能看自己负责区域的订单客服组长能看本组工单但不能看其他组的数据。这是数据权限的问题不是功能权限能覆盖的。XinServer 的权限模块在做完功能权限后专门实现了数据权限注解DataScope( column dept_id, strategy DataScopeStrategy.DEPT_AND_CHILDREN ) public PageResultOrderVO queryOrder(OrderQuery query) { // 业务代码完全不需要关心数据过滤 }实现原理是在 Service 方法执行前AOP 切面从当前登录上下文中取出用户所属部门再把部门条件封装成 SQL 片段注入到查询中。这里必须强调一个底线column字段和目标值都是预编译参数绝不能靠字符串拼接 SQL否则分分钟被搞出注入漏洞。数据权限策略我有五种仅本人、本部门、本部门及下级部门、本组织全部、全部数据。每种策略对应不同的自动条件。这个模块做到位之后新业务接入时几乎不用再写“过滤当前操作人数据”的代码直接加注解就完事。3.3 操作审计不是简单塞张日志表一开始我认为审计模块就是弄一张表记录谁在什么时候做了什么操作。真的做进去才发现如果只是简单记录后面根本没法追溯一笔订单为什么从已支付变成了已退款。XinServer 的审计模块记录了四类信息操作人基础信息、请求上下文、入参出参快照、变更前后对比。实现上采用注解加 AOPAuditLog(module order, action refund, scene 退款审批) public void refund(RefundRequest req) { // 业务逻辑 }切面在方法执行前记录入参和请求 ID执行后记录结果、耗时、出参然后把数据交给异步处理器写库。这里有个坑如果异步处理器和主流程不在同一个本地事务里主流程提交了审计日志却可能丢失。我最后是给审计模块加了一个消息表先和业务操作一起写入同一个事物再由异步任务把消息表里的记录同步到审计日志表查询走审计日志表写入走消息表至少保证日志不丢。还有一个容易被忽略的合规点敏感字段不能原样落日志。密码、Token、身份证号这些必须在注解里标记脱敏SensitiveField(strategy SensitiveStrategy.MASK) private String idCard;审计模块内置脱敏策略默认对敏感字段打码只有拿到专门解密权限的接口才能看明文。这一点在真实运营事故排查时特别重要。4. 任务、文件、通知三个高频组件的统一抽象4.1 定时任务模块去掉对具体调度器的依赖后台系统里永远有定时任务的影子对账、过期关单、报表生成、数据归档。早期我直接在业务代码里用Scheduled注解单机跑没问题后来服务一多就乱了同一个任务是所有节点都会执行一遍还是只挑一台执行如果执行到一半宕机了下次调度会不会重复执行XinServer 的任务模块做了一层抽象业务方只需要定义一个任务处理器Component public class SettlementTask implements XinTaskHandler { Override public String taskName() { return daily_settlement; } Override public void execute(TaskContext ctx) { // 实现真正的对账逻辑 } }任务模块负责三件事调度的表达式管理、集群互斥、失败重试。集群互斥用的是分布式锁加锁 Key 按任务名生成锁带有过期时间。过期时间必须大于任务最长执行时间否则任务还在跑锁已经释放了另一个节点就会再进来执行一遍。我给默认值设成了 10 分钟并要求每个任务在注册时声明自己的预估超时时间。任务模块还做了一个本地缓存加数据库表的双重策略调度状态先放缓存确认后写库。这样即使调度中间件临时抖动重启后也能按数据库里的记录把错过的任务补偿回来。4.2 文件模块写业务代码时别再关心文件在哪文件上传、Excel 导出、图片预览这些在后台系统中出现频率极高。我自己的项目早期版本里FileUtil散落在不同模块里有的写本地磁盘有的塞数据库 BLOB有的直接对接对象存储接口五花八门业务方每次都得看代码才知道“这个文件到底传到哪里去了”。XinServer 的文件模块统一了接口public interface FileStorage { StoredFile save(InputStream in, String fileName, String contentType); InputStream getStream(String fileId); void delete(String fileId); String getUrl(String fileId); }本地实现和对象存储实现都实现了同一个接口切换只需要改配置xin.file.storage.typelocal # 或者 xin.file.storage.typeoss业务代码完全不感知存储介质。开发环境用本地存储生产切到对象存储一行业务代码都不用改。这个抽象的真实价值不是省代码而是把“文件存储”从业务思考里拿掉了业务方只需要关心文件内容本身。实现过程中有几个细节值得注意第一上传时不能信任前端传的 Content-Type服务端要自己判断扩展名白名单第二私有读的 bucket 不能直接返回静态 URL要生成带有效期的签名地址第三临时文件要有生命周期定期清理避免把磁盘或存储桶塞满。4.3 通知模块发信渠道的插件化后台系统几乎都要发通知邮件提醒、站内信、Webhook 回调。XinServer 的通知模块把通知拆成了两层通知任务层和渠道发送层。业务方发通知时只需要构造一个统一的消息对象NotificationMessage.builder() .title(对账失败提醒) .content(今日对账任务执行失败请及时处理) .receivers(List.of(opsexample.com)) .channels(List.of(ChannelType.EMAIL, ChannelType.WEBHOOK)) .build();通知模块收到消息后会为每个接收者、每个渠道生成一条发送任务并负责重试和退避。邮件渠道失败了不会影响站内信渠道某一渠道连续失败超过阈值会自动熔断不再占用资源反复尝试。我特别想提醒的一点通知一定要异步发送绝不能放在主业务流程里。有一次在生成订单的接口里同步调邮件服务邮件服务超时整个下单流程都被拖慢线上用户反馈订单提交一直转圈。后来我把通知模块的发送动作全部改成从任务队列消费主流程只负责写入通知任务表响应时间立刻恢复正常。5. 联调时差点把心态搞崩的几个坑5.1 每个环境都说“配置一样”结果天差地别XinServer 在联调阶段遇到的第一个大坑是配置漂移。现象是本地跑得好好的提交到测试环境就报错测试环境调通了预发布环境导出文件又超限。每个环境的人都信誓旦旦说“配置文件我对比过了一模一样”但我把三个环境的配置拉出来一看一个关键项完全不同环境xin.file.max-size 实际值来源开发环境10MB默认值测试环境20MB配置文件覆盖预发布5MB环境变量覆盖而且这三个环境里有的配置写在 application.yml有的写在外挂配置文件有的写在环境变量里肉眼根本没法对比。后来配置指纹帮我解决了问题但也让我长了个教训多环境问题出现时第一反应不是怀疑代码而是先对比配置指纹。很多“这里能跑那里不能跑”的问题根本原因是环境差异不是代码逻辑差异。5.2 长事务把连接池打爆之后我救回来的过程有一次运营后台的导出功能突然 hang 住页面没有任何报错但操作全部超时。日志里反复出现HikariPool-1 - Connection is not available request timed out after 30000ms我第一反应是连接池配小了赶紧把最大连接数从 20 调到 50改完好了一会儿过几分钟又不行了。我盯着监控看了半天发现活跃连接数一直非常高而且迟迟不释放这说明问题不是连接数不够而是连接被占用了太长时间。顺着线程栈查下去发现导出逻辑是一个大事务先查询几天内的全部数据循环调用外部接口补充信息最后再统一写库。数据库事务要等外部接口全部返回才提交每一个外部调用按 1 秒算1000 条数据就是 1000 秒一条连接被活活占住多来几个请求连接池就枯竭了。修复方案分三步第一事务边界缩小到真正的写操作第二外部接口调用全部移出事务第三导出改成异步任务前端轮询任务状态不在请求线程里一次性查全量数据。这个坑给我的教训是不要在事务里做外部远程调用也不要在一个事务里处理大范围数据事务越短越安全。5.3 回调重复到达幂等设计第一次翻车通知模块接了很多 Webhook 回调有一次线上出现了一个非常尴尬的事故支付回调因为网络抖动同一个事件被渠道推了三次我们的处理逻辑没有做幂等控制三次都执行成功结果用户收到三份订单权益。修复的核心是在接收端建立去重表表结构很简单callback_event_id event_type received_at status -- PROCESSING / SUCCESS / IGNORE以callback_event_id event_type建唯一索引处理之前先插入一条记录插入成功才执行后续业务重复插入会直接报唯一键冲突直接返回“已处理”。同时还要配合状态机避免并发时两个请求同时读到“未处理”状态一个在处理、另一个也在处理。数据库唯一索引是最终兜底Redis 分布式锁只能作为前置加速不能完全依赖锁来保证幂等。这个坑让整个团队都留下了深刻印象后来统一出了一个约定所有接收外部回调的入口第一行必须写幂等检查不写不允许提交代码。6. 项目落地之后后台开发终于有了成就感6.1 接入从两周缩到一天半XinServer 做完第一版稳定运行后我们拿它接了一个新的优惠券核销后台。这个项目放在以前光搭登录权限菜单这些基础设施差不多要两周时间。基于 XinServer 的 starter 工程新同学拿到示例项目对照文档把数据库连接改一下再把业务模块写进工程里当天就能跑通登录流程。整个基础能力接入只花了一天半剩下时间全部投入业务查询和看板展示。这个感受非常明显以前每做一个后台前面三分之一时间都在做“通用基建”业务价值还没开始交付时间就先耗掉了。现在这些全部归零团队每个人心里都清楚“第一周就能出一个可 demo 的版本”对业务方的响应速度完全不一样。6.2 被业务方当成“积木”而不是“黑盒”运营和财务开始提一些临时需求比如“我想自己导出某个时间段的退款明细不要每次都找开发跑脚本”。以前这种需求得排期开发现在基于 XinServer 的权限和文件组件我们快速做了一个自助导出入口运营人员只要在界面上选条件点导出后台自动异步生成文件文件走统一存储带有效期链接下载。这件事让我特别有感触一个好的后台底座不是让业务方看到更炫酷的技术而是让他们觉得“这个系统是活的我可以自己拼出想要的东西”。权限、数据范围、导出、审计这些能力都变成标准积木业务方提需求时我们不再说“这个功能做不了”而是说“这块以前沉淀过了我把它接到这里”。6.3 我对成就感的重新理解回过头看做 XinServer 这段经历带给我的最大改变不是技术上的而是对工作的感受。以前做后台总觉得是在不停地“填表”一张表一张表地做做完一个还有下一个看不到积累。现在不一样权限模块被三个系统复用了文件组件被五个功能接入了任务调度后台支撑着每天的定时对账每当看到别人用我写的组件不再重复踩坑那种成就感比多写十个页面实在得多。如果你也正在后台开发的重复劳动里找不到方向我建议你先别急着学新框架而是把最近三四个项目里的公共逻辑整理一遍看看哪些东西真的是“每个项目都要写的”试着抽出来沉淀成一套属于自己的底座。规模大小不重要重要的是你开始从“填表的人”变成“搭积木的人”后台开发这件事就会变得不那么无聊了。 
长河君 · 2026/10/10 13:24:53 · 阅读 1.2k 自研后台服务底座：从重复开发到模块化复用的实践与设计
有段时间我的工作内容基本被“后台”刷屏了。今天给运营做订单管理后台明天给客服搭工单系统后天又得给风控同学整理规则配置界面……表面上看每个系统都不一样拆开之后全是同一套骨架登录、权限、菜单、日志、文件上传、定时任务、系统配置。做到第三个的时候我还能打打鸡血做到第七八个我是真的开始怀疑自己天天写增删改查代码能力没长进工作成就感还越来越低。于是就有了 XinServer。它不是什么商业产品也不是某个知名开源框架而是我把自己折腾过的各类后台系统里反复出现的那部分能力抽出来重新设计的一套可复用的后台服务底座。目标很简单以后再接新后台登录认证、权限模型、操作审计、任务调度、文件服务、消息通知这些基础能力不再重写业务方只需要写好业务本身的逻辑剩下的交给底座。这篇文章我就把这个项目的设计思路、模块边界、难点排坑过程完整分享一下给同样被困在“后台泥潭”里的朋友做个参考。1. 重复业务做多了真的会怀疑自己XinServer 的起因1.1 那些翻来覆去写的“公共代码”我先列一下当时遇到的情况。那段时间前后做了大概七个后台类项目有给运营看数据报表的有给客服处理用户工单的有给审核团队做内容复核的还有给财务做结算对账的。从业务形态上看差异很大但从工程实现的视角看公共的部分惊人地一致用户登录、会话管理、密码找回角色权限、菜单管理、按钮级别的权限控制操作日志、登录日志、数据字典文件上传、Excel 导入导出定时任务对账、关单、报表生成系统参数配置、通知消息发送这些功能我在每个项目里都要重新写一遍。第一次写权限模块还挺开心研究 RBAC 模型、设计角色表、写拦截器觉得很有挑战。到了第三个项目我已经可以直接把上一套权限代码复制过来改个表名前缀就完事了。复制多了之后问题就来了七个系统里的权限逻辑有的写在拦截器有的写在 AOP 注解有的直接在 Service 里 if 判断。一旦业务方说“A 系统的权限规则要调整”我得打开几个项目一个个找改完还要担心影响其他功能。更可怕的是质量参差。早期某个项目里的会话管理用的是长期有效的 Token用户离职了账号还在续期安全上留下隐患另一个项目倒是做了过期时间但忘记处理“踢人下线”的逻辑账号可以同时在十几个设备登录。这些坑散落在不同后台里像定时炸弹一样等触发。1.2 为什么不是“找一个现成平台”而是自研后来大家也开始讨论要不要直接引入一个现成的后台框架、低代码平台或者开源的管理系统模板。当时我认认真真拉了个表格评估最后放弃了原因有三点可选方案优点缺点结论复制旧项目代码上手最快每个项目都有自己的“历史包袱”维护成本随时间翻倍不可持续引入开源后台框架功能全、社区活跃定制复杂需求时要绕框架的弯版本升级容易踩兼容坑可以借鉴不能直接套用低代码平台简单需求很快业务规则一复杂平台就成了黑盒出了问题很难定位不适合我们的场景自研一套通用底座完全可控、贴合业务前期设计投入大最终选择另外还有个边界问题。数据库连接池、ORM、缓存、消息队列这些基础组件自己重写没有必要成熟的开源生态已经很稳定了直接用就行。真正值得自己沉淀的是和业务规则强相关、又横跨多系统的那部分能力比如权限模型、数据权限、审计带、任务调度抽象。它们没有一个标准答案换个业务场景需求就变了必须把实现握在自己手里。所以 XinServer 的定位从一开始就很清楚不做“全家桶”只做后台开发里复用率最高的那部分底座每个模块都允许业务方做扩展但改公共逻辑时不至于伤筋动骨。2. 整体设计把底子打对后面才不拧巴2.1 三层模型与模块总线XinServer 的代码结构我搭成了三层内核层、模块层、业务层。内核层只负责最基础的事情包括模块的加载与卸载、统一配置读取、日志上下文、事件总线还有“模块健康检查”。它不包含任何业务概念也不知道“用户”“订单”是什么。模块层放通用能力每个能力是一个独立模块。我在第一版规划了六个核心模块认证、权限、审计、任务、文件、通知。模块之间做到“不知道对方的存在”需要协作时通过事件总线发消息。业务层就是具体项目里真正要写的逻辑比如“查询订单列表”“导出对账单”。这一层可以依赖模块层但模块层绝不能反向依赖某一套具体业务的表结构。为什么这么设计我吃过耦合的苦。以前在一个老项目里发通知的逻辑被直接写在订单服务的代码里后来另一个业务想复用通知能力只能把订单服务里面那段代码复制出去连带复制了一堆无关依赖。模块之间没有总线表面上改一处代码很快实际上到处是隐形的依赖关系。XinServer 里强制模块只认事件和接口不认具体实现类至少在结构上避免了越扯越乱的“蜘蛛网”。2.2 目录结构与模块注册示例我把项目做成了多模块结构大概是这个样子xin-server-core/ # 内核层 ├── module/ # 模块生命周期管理 ├── config/ # 统一配置模型 ├── event/ # 事件总线 └── log/ # 日志上下文 xin-module-auth/ # 认证模块 xin-module-permission/ # 权限模块 xin-module-audit/ # 审计模块 xin-module-task/ # 任务调度模块 xin-module-file/ # 文件模块 xin-module-notify/ # 通知模块 xin-starter/ # 面向业务方的启动器 xin-example/ # 官方示例工程这里有一个关键设计模块不是通过代码里直接 import 来注册的而是每个模块提供一个描述文件内核启动时会自动扫描装配。模块实现统一接口public interface XinModule { String name(); default int order() { return 0; } default void onInit(XinContext context) { } default void onDestroy(XinContext context) { } }每个模块在自己的META-INF/xin-modules文件里声明# META-INF/xin-modules/net.example.xin.module.auth.AuthModule # META-INF/xin-modules/net.example.xin.module.task.TaskModule这样做的好处是加一个模块只需要放一个 jar 包删一个模块也不用去改启动类。多个业务系统可以挑选自己需要的模块组合比如一个纯查询的报表后台可能只需要审计模块和文件模块不需要任务模块那就不引入它。类比一下这就像是电脑主板上的 PCIe 插槽接口标准统一插什么卡由业务方自己定而不是把声卡网卡显卡全焊死在主板上。2.3 配置策略环境分离与默认值后台开发里配置这块我踩过太多“本地能跑测试环境挂了”的坑。XinServer 的配置策略我最终定了三句话默认值写在代码里环境差异写在环境变量里启动时强制打印配置指纹。默认值必须足够“安全”。比如xin.file.max-size默认给 10MB某个环境忘了配置它至少能正常工作而不是因为 null 直接报错。环境变量只覆盖真正有差异的项比如数据库地址、对象存储的桶名、通知渠道的密钥。配置指纹则是把所有生效配置做一个哈希启动时打印出来同时打印哪些配置项来自默认值、哪些来自环境变量、哪些被显式覆盖。这样处理以后多环境问题从“猜”变成了“对指纹”。测试环境说它连的数据库是 A我拿它启动日志里的指纹和开发环境比一下立刻就知道有没有配置漂移省去了四处翻配置文件的排查时间。3. 第一个硬骨头认证、权限和审计一次做透3.1 会话方案短 Token 长 Refresh主动踢人认证模块是第一块硬骨头。后台系统不像 C 端 App 那样弱化管理它要求账号可禁用、会话可吊销、登录设备可查。最开始我图省事直接生成一个有效期 30 天的 Token 扔给前端后来发现安全问题没法处理有同事反馈账号被离职员工继续使用光是“让 Token 立即失效”这件事就做不到。XinServer 最终用了短 Token 加 Refresh Token 的混合方案。简单说客户端登录后拿到的访问 Token 有效期 30 分钟过期后通过 Refresh Token 去换新的。Refresh Token 保存在服务端存储里有效期 7 天每次刷新都会轮换。账号被禁用时服务端直接把该用户的所有 Refresh Token 失效这样最多 30 分钟内访问 Token 也会因为校验失败而退出。方案主动踢人分布式支持实现成本后台场景适配度长有效期 JWT困难好低低纯服务端 Session容易需要会话存储中中短 Token Refresh较好好中高这个方案里最容易忽略的细节是“并发的刷新请求”。前端如果同时发出三个请求三个请求都发现访问 Token 过期各自拿着 Refresh Token 去刷新就可能造成 Refresh Token 重复使用。我在服务端做了并发控制刷新接口使用分布式锁Refresh Token 校验和轮换在同一个事务里完成刷新失败则统一返回重新登录。3.2 RBAC 之外还有数据权限很多后台系统的权限模块做成了“用户-角色-权限点”三层但落到真实业务时发现不够用。比如运营人员能看订单管理菜单但只能看自己负责区域的订单客服组长能看本组工单但不能看其他组的数据。这是数据权限的问题不是功能权限能覆盖的。XinServer 的权限模块在做完功能权限后专门实现了数据权限注解DataScope( column dept_id, strategy DataScopeStrategy.DEPT_AND_CHILDREN ) public PageResultOrderVO queryOrder(OrderQuery query) { // 业务代码完全不需要关心数据过滤 }实现原理是在 Service 方法执行前AOP 切面从当前登录上下文中取出用户所属部门再把部门条件封装成 SQL 片段注入到查询中。这里必须强调一个底线column字段和目标值都是预编译参数绝不能靠字符串拼接 SQL否则分分钟被搞出注入漏洞。数据权限策略我有五种仅本人、本部门、本部门及下级部门、本组织全部、全部数据。每种策略对应不同的自动条件。这个模块做到位之后新业务接入时几乎不用再写“过滤当前操作人数据”的代码直接加注解就完事。3.3 操作审计不是简单塞张日志表一开始我认为审计模块就是弄一张表记录谁在什么时候做了什么操作。真的做进去才发现如果只是简单记录后面根本没法追溯一笔订单为什么从已支付变成了已退款。XinServer 的审计模块记录了四类信息操作人基础信息、请求上下文、入参出参快照、变更前后对比。实现上采用注解加 AOPAuditLog(module order, action refund, scene 退款审批) public void refund(RefundRequest req) { // 业务逻辑 }切面在方法执行前记录入参和请求 ID执行后记录结果、耗时、出参然后把数据交给异步处理器写库。这里有个坑如果异步处理器和主流程不在同一个本地事务里主流程提交了审计日志却可能丢失。我最后是给审计模块加了一个消息表先和业务操作一起写入同一个事物再由异步任务把消息表里的记录同步到审计日志表查询走审计日志表写入走消息表至少保证日志不丢。还有一个容易被忽略的合规点敏感字段不能原样落日志。密码、Token、身份证号这些必须在注解里标记脱敏SensitiveField(strategy SensitiveStrategy.MASK) private String idCard;审计模块内置脱敏策略默认对敏感字段打码只有拿到专门解密权限的接口才能看明文。这一点在真实运营事故排查时特别重要。4. 任务、文件、通知三个高频组件的统一抽象4.1 定时任务模块去掉对具体调度器的依赖后台系统里永远有定时任务的影子对账、过期关单、报表生成、数据归档。早期我直接在业务代码里用Scheduled注解单机跑没问题后来服务一多就乱了同一个任务是所有节点都会执行一遍还是只挑一台执行如果执行到一半宕机了下次调度会不会重复执行XinServer 的任务模块做了一层抽象业务方只需要定义一个任务处理器Component public class SettlementTask implements XinTaskHandler { Override public String taskName() { return daily_settlement; } Override public void execute(TaskContext ctx) { // 实现真正的对账逻辑 } }任务模块负责三件事调度的表达式管理、集群互斥、失败重试。集群互斥用的是分布式锁加锁 Key 按任务名生成锁带有过期时间。过期时间必须大于任务最长执行时间否则任务还在跑锁已经释放了另一个节点就会再进来执行一遍。我给默认值设成了 10 分钟并要求每个任务在注册时声明自己的预估超时时间。任务模块还做了一个本地缓存加数据库表的双重策略调度状态先放缓存确认后写库。这样即使调度中间件临时抖动重启后也能按数据库里的记录把错过的任务补偿回来。4.2 文件模块写业务代码时别再关心文件在哪文件上传、Excel 导出、图片预览这些在后台系统中出现频率极高。我自己的项目早期版本里FileUtil散落在不同模块里有的写本地磁盘有的塞数据库 BLOB有的直接对接对象存储接口五花八门业务方每次都得看代码才知道“这个文件到底传到哪里去了”。XinServer 的文件模块统一了接口public interface FileStorage { StoredFile save(InputStream in, String fileName, String contentType); InputStream getStream(String fileId); void delete(String fileId); String getUrl(String fileId); }本地实现和对象存储实现都实现了同一个接口切换只需要改配置xin.file.storage.typelocal # 或者 xin.file.storage.typeoss业务代码完全不感知存储介质。开发环境用本地存储生产切到对象存储一行业务代码都不用改。这个抽象的真实价值不是省代码而是把“文件存储”从业务思考里拿掉了业务方只需要关心文件内容本身。实现过程中有几个细节值得注意第一上传时不能信任前端传的 Content-Type服务端要自己判断扩展名白名单第二私有读的 bucket 不能直接返回静态 URL要生成带有效期的签名地址第三临时文件要有生命周期定期清理避免把磁盘或存储桶塞满。4.3 通知模块发信渠道的插件化后台系统几乎都要发通知邮件提醒、站内信、Webhook 回调。XinServer 的通知模块把通知拆成了两层通知任务层和渠道发送层。业务方发通知时只需要构造一个统一的消息对象NotificationMessage.builder() .title(对账失败提醒) .content(今日对账任务执行失败请及时处理) .receivers(List.of(opsexample.com)) .channels(List.of(ChannelType.EMAIL, ChannelType.WEBHOOK)) .build();通知模块收到消息后会为每个接收者、每个渠道生成一条发送任务并负责重试和退避。邮件渠道失败了不会影响站内信渠道某一渠道连续失败超过阈值会自动熔断不再占用资源反复尝试。我特别想提醒的一点通知一定要异步发送绝不能放在主业务流程里。有一次在生成订单的接口里同步调邮件服务邮件服务超时整个下单流程都被拖慢线上用户反馈订单提交一直转圈。后来我把通知模块的发送动作全部改成从任务队列消费主流程只负责写入通知任务表响应时间立刻恢复正常。5. 联调时差点把心态搞崩的几个坑5.1 每个环境都说“配置一样”结果天差地别XinServer 在联调阶段遇到的第一个大坑是配置漂移。现象是本地跑得好好的提交到测试环境就报错测试环境调通了预发布环境导出文件又超限。每个环境的人都信誓旦旦说“配置文件我对比过了一模一样”但我把三个环境的配置拉出来一看一个关键项完全不同环境xin.file.max-size 实际值来源开发环境10MB默认值测试环境20MB配置文件覆盖预发布5MB环境变量覆盖而且这三个环境里有的配置写在 application.yml有的写在外挂配置文件有的写在环境变量里肉眼根本没法对比。后来配置指纹帮我解决了问题但也让我长了个教训多环境问题出现时第一反应不是怀疑代码而是先对比配置指纹。很多“这里能跑那里不能跑”的问题根本原因是环境差异不是代码逻辑差异。5.2 长事务把连接池打爆之后我救回来的过程有一次运营后台的导出功能突然 hang 住页面没有任何报错但操作全部超时。日志里反复出现HikariPool-1 - Connection is not available request timed out after 30000ms我第一反应是连接池配小了赶紧把最大连接数从 20 调到 50改完好了一会儿过几分钟又不行了。我盯着监控看了半天发现活跃连接数一直非常高而且迟迟不释放这说明问题不是连接数不够而是连接被占用了太长时间。顺着线程栈查下去发现导出逻辑是一个大事务先查询几天内的全部数据循环调用外部接口补充信息最后再统一写库。数据库事务要等外部接口全部返回才提交每一个外部调用按 1 秒算1000 条数据就是 1000 秒一条连接被活活占住多来几个请求连接池就枯竭了。修复方案分三步第一事务边界缩小到真正的写操作第二外部接口调用全部移出事务第三导出改成异步任务前端轮询任务状态不在请求线程里一次性查全量数据。这个坑给我的教训是不要在事务里做外部远程调用也不要在一个事务里处理大范围数据事务越短越安全。5.3 回调重复到达幂等设计第一次翻车通知模块接了很多 Webhook 回调有一次线上出现了一个非常尴尬的事故支付回调因为网络抖动同一个事件被渠道推了三次我们的处理逻辑没有做幂等控制三次都执行成功结果用户收到三份订单权益。修复的核心是在接收端建立去重表表结构很简单callback_event_id event_type received_at status -- PROCESSING / SUCCESS / IGNORE以callback_event_id event_type建唯一索引处理之前先插入一条记录插入成功才执行后续业务重复插入会直接报唯一键冲突直接返回“已处理”。同时还要配合状态机避免并发时两个请求同时读到“未处理”状态一个在处理、另一个也在处理。数据库唯一索引是最终兜底Redis 分布式锁只能作为前置加速不能完全依赖锁来保证幂等。这个坑让整个团队都留下了深刻印象后来统一出了一个约定所有接收外部回调的入口第一行必须写幂等检查不写不允许提交代码。6. 项目落地之后后台开发终于有了成就感6.1 接入从两周缩到一天半XinServer 做完第一版稳定运行后我们拿它接了一个新的优惠券核销后台。这个项目放在以前光搭登录权限菜单这些基础设施差不多要两周时间。基于 XinServer 的 starter 工程新同学拿到示例项目对照文档把数据库连接改一下再把业务模块写进工程里当天就能跑通登录流程。整个基础能力接入只花了一天半剩下时间全部投入业务查询和看板展示。这个感受非常明显以前每做一个后台前面三分之一时间都在做“通用基建”业务价值还没开始交付时间就先耗掉了。现在这些全部归零团队每个人心里都清楚“第一周就能出一个可 demo 的版本”对业务方的响应速度完全不一样。6.2 被业务方当成“积木”而不是“黑盒”运营和财务开始提一些临时需求比如“我想自己导出某个时间段的退款明细不要每次都找开发跑脚本”。以前这种需求得排期开发现在基于 XinServer 的权限和文件组件我们快速做了一个自助导出入口运营人员只要在界面上选条件点导出后台自动异步生成文件文件走统一存储带有效期链接下载。这件事让我特别有感触一个好的后台底座不是让业务方看到更炫酷的技术而是让他们觉得“这个系统是活的我可以自己拼出想要的东西”。权限、数据范围、导出、审计这些能力都变成标准积木业务方提需求时我们不再说“这个功能做不了”而是说“这块以前沉淀过了我把它接到这里”。6.3 我对成就感的重新理解回过头看做 XinServer 这段经历带给我的最大改变不是技术上的而是对工作的感受。以前做后台总觉得是在不停地“填表”一张表一张表地做做完一个还有下一个看不到积累。现在不一样权限模块被三个系统复用了文件组件被五个功能接入了任务调度后台支撑着每天的定时对账每当看到别人用我写的组件不再重复踩坑那种成就感比多写十个页面实在得多。如果你也正在后台开发的重复劳动里找不到方向我建议你先别急着学新框架而是把最近三四个项目里的公共逻辑整理一遍看看哪些东西真的是“每个项目都要写的”试着抽出来沉淀成一套属于自己的底座。规模大小不重要重要的是你开始从“填表的人”变成“搭积木的人”后台开发这件事就会变得不那么无聊了。