干企业信息化这么多年我最怕的项目就是薪酬工资管理系统。怕的不是需求复杂而是它天生不允许出错——一次算薪错误全公司都能在下个月工资日准时发现。我负责的这套企业员工薪酬工资管理系统最终方案很直接后端SpringBoot前端Vue整体采用SpringCloud微服务分布式架构。Nacos管注册和配置Gateway做统一入口Redis扛分布式锁服务之间按业务边界拆开各管一摊。这篇文章把这些落地的思路、拆解、配置和坑一次说清楚适合正在做薪酬系统、或者准备用SpringCloud改造旧系统的朋友参考。1. 整体架构思路为什么非要用微服务1.1 薪酬系统真正难的不是“算工资”而是跨部门协作很多人觉得薪酬系统就是一个计算器输入出勤天数、绩效分数输出应发工资、扣税、实发工资。实际接手后才会发现它背后牵扯着人力资源部、财务部、IT部、公司高层甚至审计和银行。每个月有严格的算薪时间窗口几号之前提交考勤几号之前完成审批几号之前把银行代发文件送出去。任何一个环节卡住都会变成“全公司下周收不到工资”的事故。单体应用不是不能做但做到后面会非常别扭。我曾经维护过一套老旧的单体重型系统所有模块都在同一个应用里调用关系混乱代码里到处都是静态工具类互相薅数据。最头疼的是资源隔离问题月末算薪时大量工资单需要CPU密集计算同一时间报表模块又在跑全公司年度薪酬汇总两个任务挤在同一个JVM里互相拖慢。有一次算薪任务跑了40分钟还没结束就是因为报表查询把连接池占满了。这种场景下微服务拆分不是炫技而是为了让算薪服务、报表服务、审批服务能独立部署、独立扩容互不拖后腿。具体到这个项目我们把系统划分成几个独立的服务每个服务有独立的数据库或独立的schema。服务之间只通过API通信不共享数据表。为了支撑这套分布式体系引入了SpringCloud全家桶Nacos做注册中心和配置中心Gateway做统一入口OpenFeign做服务间调用Sentinel做限流降级。这套组合最大的价值是不用自己造轮子微服务治理里的服务发现、配置刷新、负载均衡、熔断限流都有现成组件可以接。1.2 技术选型SpringBoot、SpringCloud和Vue分别解决什么问题先理清一个很多人混淆的概念。Spring是一个基础容器框架核心是IOC和AOPSpringBoot把Spring的用法大幅简化用starter依赖和自动配置把项目跑起来SpringCloud则是在SpringBoot基础上提供微服务治理能力包括服务注册、配置中心、网关、熔断等。所以一个典型的SpringCloud微服务每个子服务本身就是一个SpringBoot应用外面套一层SpringCloud组件。很多初学者把SpringBoot和SpringCloud当成两个对立的东西其实它们是一层叠一层的。前端选Vue而不是JSP核心原因是组件化和前后端分离。薪酬管理界面有大量表单、弹窗、数据表格比如薪酬项配置、工资单明细、审批页面用Vue的组件模式写起来比后端套模板清爽得多。我们用的是Vue3 Element Plus Vite配合Pinia做状态管理。页面上的逻辑都通过axios调用后端API前端只关心交互后端只关心业务和计算两边各守各的边界。这套组合的实际好处在项目中期体现得特别明显。有次财务提出要调整个税计算页面希望把累计预扣明细展示得更清楚。如果是单体JSP前后端代码混在一起改一个页面可能要连带动Controller和SQL但在Vue工程里我只需要新写一个组件加载工资单数据后做前端展示计算后端接口基本不动两天就上线了。1.3 服务边界怎么划共享什么独立什么服务拆分最怕拍脑袋。如果按“Controller层拆一个服务、Service层拆一个服务”这种技术分层来拆那只是把单体变成了分布式单体调用链路乱成一团出了故障反而更难排查。正确做法是按业务能力拆每个服务围绕一块清晰的业务领域。这个薪酬系统最终拆分为以下服务服务名称核心职责关键数据system-service用户、角色、菜单、字典、权限用户表、角色表、菜单表employee-service员工主数据、入转调离、组织架构员工档案、部门、岗位salary-service薪酬项、薪酬方案、算薪、工资单薪酬项、工资单、个税记录approval-service审批流程引擎、审批记录审批单、审批节点report-service月度汇总、成本分析、对外报表汇总表、统计快照notify-service站内信、邮件、短信工资条消息记录、发送日志file-service附件存储、工资单PDF、银行代发文件MinIO对象存储每个服务独立部署后最大好处是故障隔离。算薪服务因为临时数据异常OOM了报表服务还能正常对外提供查询系统服务挂了其他服务虽然认证会受影响但至少工资单查询页面不会跟着一起卡死。缺点也很明显服务间调用有网络开销需要处理分布式事务、数据一致性、重复请求。正因为这些代价我们才在第三部分重点讲了锁、事务和幂等处理这些不是可选项而是分布式架构下的必修课。服务拆分还有一个原则能不同步数据就尽量不同步必须要冗余的数据也要控制在最小范围。比如工资单里需要显示员工部门和岗位我们没有让salary-service每次去查employee-service而是在生成工资单的时候冗余了一份部门编码和岗位名称快照。这样算薪过程中即使员工调岗历史工资单还是显示当时的部门不会算完突然变了。历史数据不能跟着主数据漂移这是薪酬系统里特别容易踩的坑。2. 核心业务功能设计与关键细节2.1 员工主数据和组织架构一切计算的起点员工主数据是薪酬计算的源头。工号必须唯一身份证号要严格校验银行卡号和开户行要分字段保存手机号、邮箱要保证能收到工资条通知。更关键的是入职日期、转正日期、离职日期这些日期直接参与司龄工资、年假折算、离职结算的计算差一天都可能引发争议。员工状态也要建模清楚。我们设计了在职、试用期、待离职、离职、停薪留职等状态每个状态对应不同的算薪规则。试用期员工没有某些补贴离职员工要算离职补偿停薪留职不发放全勤奖。这些规则不能散落在代码的if-else里而是做成可配置的规则项由HR在薪酬方案里维护。组织架构本身是一棵树部门调整时有发生。为了不影响历史月份工资单employee-service提供组织快照能力。每月算薪前系统会生成一份当月的部门快照工资单上记录的是快照里的部门编码而不是实时去查当前组织树。否则3月份财务调整了部门4月再看3月工资单历史数据全变对账根本没法做。另外员工薪酬数据属于敏感信息前端展示要做脱敏处理。银行卡号中间8位打码手机号只保留前3后4身份证号同样处理。数据权限上普通HR只能看自己负责的部门薪酬专员能看全部但操作要留痕部门负责人只能看汇总不能看个人明细。这一切在网关层做登录校验在各个服务里做二次数据权限校验前端再隐藏按钮三层配合。2.2 薪酬计算引擎规则要能配置金额要用对类型薪酬计算是salary-service的核心。我把薪酬项分成三类固定项基本工资、岗位工资、计算项绩效工资绩效基数×绩效系数、加班费基本工资/21.75×加班天数×倍数、扣款项事假扣款、社保个人部分、个税。每个薪酬项有计算顺序先算应发项再算应扣项最后算个税和实发。我们用表达式引擎来管理规则没有把所有公式硬编码在Java里。薪酬项表大致长这样salary_item_code -- 薪酬项编码 item_name -- 薪酬项名称 calc_type -- fixed / formula formula_expression -- 格式化表达式 priority -- 计算顺序 is_taxable -- 是否计税 is_active -- 是否启用表达式引擎选择了Aviator轻量、性能好还支持自定义函数。比如这样一条规则basicSalary positionSalary (performanceBase * performanceScore)HR不需要改代码只要在管理界面配置好公式算薪任务就能读取并执行。为了避免公式写错导致灾难性结果每次修改薪酬方案时我们都要跑一遍“试算”拿上个月的工资单做对比差异超过一定比例就告警。金额计算是薪酬系统的高危区。Java里float和double绝对不能用来算钱二进制的浮点数表示会导致精度丢失。我们全部用BigDecimal而且必须用字符串构造或者BigDecimal.valueOf禁止直接new BigDecimal(0.1)。所有金额字段在数据库里用decimal(18,2)对外统一保留两位小数。每项薪酬项计算完成后单独四舍五入而不是等到最后实发时才四舍五入否则明细汇总金额和实发金额会有尾差财务对账会疯掉。个税计算这半年改得频繁我们是把税率表做成配置表每次政策调整只更新配置不需要发版。个税用累计预扣法按月累计算收入、累计减除费用、累计专项附加扣除再算出累计应纳税额减去已预缴部分得到当月个税。这里一定要用一个幂等的计算服务同一个员工、同一个月、同一薪酬方案多次调用结果必须一致。2.3 工资单审批状态机和发放流程工资单不能算完就直接发必须走审批流。我们把工资单状态设计成一条清晰的状态机草稿、待审批、审批中、已通过、已驳回、已归档。员工一月份的工资单在审批通过后就不能再被普通HR编辑如果真需要调整必须走“更正单”流程改正后重新审批保留所有历史修改记录。这个设计保护了HR也保护了员工信任。审批流由approval-service统一管理但工资单状态本身保存在salary-service。两个服务的协作方式是approval-service负责流程引擎、审批人判定、审批记录审批通过后通过API通知salary-service更新状态。salary-service只认审批事件不直接依赖approval-service的工作流表。这样即使工作流引擎要换也不会污染工资单核心数据。审批完成后进入发放环节。系统会生成银行代发文件文件名包含月份和批次号内容按银行要求的格式生成。文件生成后必须先做试算校验代发总额必须等于工资单实发总额笔数必须等于通过的工资单数量。校验不通过就阻断下发防止出现全公司工资错发的灾难。发放完成后工资单状态进入已归档同时通过notify-service给员工推送工资条。2.4 报表统计和分页查询的实操细节报表服务承接了所有查询分析压力。月度工资汇总表、部门成本分析表、社保公积金汇缴表、个税申报表每类报表数据量大SQL join多。这里我们用MyBatis分页插件先解决列表查询的性能问题配置一个拦截器分页参数由前端传入查询自动带limit和count。但真正能抗住压力的不是分页而是“预汇总”。每月算薪完成后salary-service会生成一张月度汇总快照表按部门、岗位、薪酬项维度提前聚合。报表服务查询时直接查快照不再实时扫描工资单明细。这个优化非常有效原本需要十几秒的年度汇总报表查询时间降到一秒以内。导出Excel也做成了异步任务。前端点“导出”后端先创建导出任务并返回任务ID用户在页面上等着导出完成后通过WebSocket收到通知再下载。导出用POI的SXSSFWorkbook流式写文件几十万行数据不会OOM。下载接口做成一次性token避免业务人员拿着Excel下载链接到处乱发。3. 分布式架构落地实操记录3.1 Nacos注册中心与配置中心先把基础环境搭稳这套系统的第一个基础设施是Nacos。我们使用Nacos同时承担注册中心和配置中心两个角色。每个SpringBoot服务启动时自动注册到Nacos调用方通过服务名而不是IP地址访问这解决了一个很实际的问题服务部署在多台服务器上实例IP可能会变不可能手写IP列表。服务端的配置如下我截取的是salary-service的bootstrap配置spring: application: name: salary-service profiles: active: dev cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: 5e5cdb3c-xxxx-xxxx group: SALARY_GROUP config: server-addr: 127.0.0.1:8848 namespace: 5e5cdb3c-xxxx-xxxx file-extension: yaml shared-configs: ->spring: cloud: gateway: routes: - id: salary-service uri: lb://salary-service predicates: - Path/api/salary/** filters: - StripPrefix1 - id: employee-service uri: lb://employee-service predicates: - Path/api/employee/** filters: - StripPrefix1StripPrefix1特别关键。前端请求的是 /api/salary/salary-list网关剥离掉第一层api后转发给salary-service的路径是 /salary/salary-list和后端Controller的RequestMapping匹配。如果不加这个过滤器salary-service收到的是 /api/salary/salary-list如果后端没有这个映射就直接404排查起来一头雾水。网关层做的第二件事是统一鉴权。我们在Gateway里写了一个全局过滤器对所有请求校验JWT直接把token中的用户ID和权限标识解析出来放到请求头里转发给下游服务Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String auth exchange.getRequest().getHeaders().getFirst(Authorization); // 校验token解析userId、userName、tenantId ServerHttpRequest request exchange.getRequest().mutate() .header(X-User-Id, userId) .header(X-User-Name, userName) .build(); return chain.filter(exchange.mutate().request(request).build()); } }这样做的好处是下游业务服务不用再关心token解析逻辑直接从Header里取当前用户。注意网关过滤器和业务代码不要耦合太深网关只做身份校验和路由不做具体的薪酬计算或权限判断。权限判断还得在每个服务里做因为网关你没法知道某个按钮级权限是否匹配。3.3 服务间调用OpenFeign如何传递用户上下文服务间的调用我们在salary-service里通过OpenFeign调用employee-service查询员工基础信息。Feign配置简单但有一个分布式场景下的经典问题用户信息传递。前端调用salary-service时X-User-Id在网关已经写进Header但salary-service通过Feign再去调用employee-service时这个Header不会自动透传。如果employee-service需要知道当前操作人比如记录“谁修改了员工状态”就必须把用户ID传过去。解决办法是给Feign加一个RequestInterceptor在发请求时把当前请求上下文中的Header复制到新的Feign请求里public class FeignUserContextInterceptor implements RequestInterceptor { Override public void apply(RequestTemplate template) { ServletRequestAttributes attributes ServletRequestAttributes.getRequestAttributes(); if (attributes ! null) { HttpServletRequest request attributes.getRequest(); template.header(X-User-Id, request.getHeader(X-User-Id)); template.header(X-User-Name, request.getHeader(X-User-Name)); } } }这里要特别注意异步线程的情况——如果你用异步线程池发起Feign调用ServletRequestAttributes可能为空用户上下文会丢失。我们的做法是利用ThreadLocal或者直接使用Spring Cloud的RequestContextHolder传参异步调用则显式把用户ID作为方法参数传进线程。概括成一句话分布式链路里用户身份要么始终放Header传递要么显式在方法参数里传不要指望框架自动帮你穿来穿去。配合Sentinel做服务保护。工资单查询接口和算薪接口都配置了流控规则。比如算薪接口单机QPS阈值20超过的请求排队等待对查询报表的外部接口设置关联限流如果报表服务处理不过来直接降级返回“系统繁忙”。Sentinel和OpenFeign结合后某服务挂了不会把整个调用链拖死。我们就在一次模拟故障时验证过employee-service宕机后salary-service的接口立刻降级并返回熔断提示而不是一直等连接超时。3.4 算薪防重Redis分布式锁的痛点和解决这个系统里有一个很典型的分布式问题用户连续点击两次“生成某月工资单”同一部门、同一月份可能被并发算薪生成两份工资单。单机时代可以用synchronized锁一个对象但服务拆成多实例后每个实例的同步锁互不认账必须用分布式锁。我们使用Redis分布式锁。最简单的实现是SETNX加过期时间String lockKey salary:calc: yearMonth : deptId; String requestId UUID.randomUUID().toString(); Boolean locked redisTemplate.opsForValue().setIfAbsent(lockKey, requestId, 30, TimeUnit.SECONDS); if (!Boolean.TRUE.equals(locked)) { throw new RuntimeException(该部门本月工资单正在生成中请勿重复提交); } try { // 执行算薪任务生产者发送消息到MQ异步处理 } finally { String currentValue redisTemplate.opsForValue().get(lockKey); if (requestId.equals(currentValue)) { redisTemplate.delete(lockKey); } }为什么finally里要比较requestId就是防止一个线程的锁过期被自动释放后另一个线程拿到了新锁而第一个线程的finally执行delete把别人的锁删掉。比较value再删除这是必须做的“先查后删”步骤。更严谨的做法是直接用Lua脚本保证compare-and-delete的原子性。锁的时间设置也要讲究。算薪任务是异步的真正耗时的计算已经放到MQ里所以锁不需要长时间占用。锁的粒度是月份部门而不是“全公司”一把锁。如果是全公司一把锁任何一个部门算薪没结束其他部门全部被阻塞月底算薪高峰期会拖到很晚。拆到部门粒度各算各的互不干扰。生产环境我更推荐用Redisson它有看门狗机制自动续期不会因为业务执行超过锁过期时间就提前释放。但用Redisson也别把锁范围定太大关键还是锁粒度设计。3.5 发薪数据一致性分布式事务的取舍分布式事务是SpringCloud项目里最让人头疼的一块。我们的典型场景审批通过后工资单状态要改成“已通过”同时要在财务模块生成一笔待付账记录。这个操作跨了salary-service和account-service财务模块我们直接复用外部财务系统接口两个服务各自有本地事务没法用同一个数据库事务搞定。具体方案我们做了一个对比方案优点缺点适用场景Seata AT模式代码侵入小框架自动回滚需要额外部署TC对数据库连接和undo_log有要求一致性要求高、并发不极端的状态变更本地消息表 MQ解耦方案稳定需要处理消息幂等、重试、对账最终一致可接受的异步业务定时对账 人工补偿实现简单兜底能力强延迟高不能实时拦截错误所有场景的最后一道防线我们最终选了比较务实的组合工资单状态更新用Seata的AT模式做全局事务保证核心状态和财务报表同步异步消息通知和工资条推送走MQ允许最终一致但消费端必须做幂等。同时每天凌晨跑一个对账脚本检查工资单状态、财务记账、银行代发文件三者是否金额一致。这个对账脚本看上去很土但每次版本上线都靠它兜底。Seata使用中有一个很重要的认知AT模式不是免费午餐。它会在事务期间持有数据库行锁如果并发冲突高反而可能拖垮性能。薪资审批是低频操作采用AT完全没问题但如果抢购、秒杀这类超高并发场景就别硬上Seata了。3.6 前端Vue工程化动态路由、权限、导出文件前端使用Vue3 Element Plus Vite工程结构按功能模块划分。登录后调用system-service的菜单接口拿到当前用户的菜单树和按钮权限标识动态生成路由。这样做的好处是不同角色登录看到不同的导航且刷新页面后路由依然能恢复。路由守卫的伪代码大致是router.beforeEach((to, from, next) { if (!userStore.token) { next(/login); } else if (userStore.menus.length 0) { userStore.loadMenus().then(() { // 动态添加路由后再进入目标页面 next({ ...to, replace: true }); }); } else { next(); } });按钮权限用自定义指令控制。比如调薪按钮需要“salary:adjust”权限没有权限的账号渲染时直接移除DOM。这里有个细节前端隐藏按钮只是体验层面的控制真正的权限判断一定要在后端接口上做。因为懂开发的人随手就能改前端代码把按钮显示出来后端如果没有校验就等于权限白设。axios封装时要注意文件导出。导出工资单Excel时请求返回的是blob流但后端如果处理出错返回的是JSON错误信息。前端的响应拦截器里要先判断response.headers的类型是application/json就走统一错误处理是application/octet-stream才写入文件。我见过不少项目在这个地方踩坑明明接口报错却下载了一个空文件或一堆乱码。Vue调试时一定要装Vue DevTools查看路由状态、Pinia数据和组件props都非常直观。页面里工资单编辑器、工资条预览、审批历史三个组件是最常用的做成通用组件放到前端公共目录后续接社保模块或者公积金模块也都能复用。生产环境构建完注意nginx配置history路由否则刷新页面就404。4. 踩坑记录与排查方法4.1 版本兼容是最容易翻车的点搭建SpringCloud项目最烦躁的问题就是版本不匹配。SpringBoot、SpringCloud、SpringCloud Alibaba三者版本号不是一起发布的如果随便从网上找依赖组合启动时经常冒出NoSuchMethodError、ClassNotFoundException看堆栈看半天也定位不到。我这边当时用的是一套比较稳的组合Spring Boot 2.6.xSpring Cloud 2021.0.xSpring Cloud Alibaba 2021.0.xNacos Server 2.2.3Sentinel 1.8.6。列表仅作参考因为版本兼容关系随着时间一直在变真正靠谱的方式是打开Spring Cloud Alibaba官方项目wiki找到版本对应关系表按表格里的组合来配。不要只升级其中一个组件要整体同步升级。排查版本冲突时熟练使用mvn dependency:tree非常关键。比如Sentinel和OpenFeign同时存在时可能两个jar包传递依赖了不同版本的fastjson或jackson最终导致JSON序列化异常。这时统一通过dependencyManagement锁定版本比在pom里到处写排除靠谱。4.2 金额精度和计算顺序用double算工资等于事故这个坑我再强调一遍因为它带来的后果太严重。例如0.1 0.2用double计算结果是0.30000000000000004。工资单上写着应发7320.60元报表却显示7320.599999999999差几厘钱累计起来月底对账永远不平。我们的规则很简单所有金额字段类型用BigDecimal构造BigDecimal时用字符串或BigDecimal.valueOf禁止new BigDecimal(0.1)每个薪酬项算完就统一四舍五入到两位小数数据库decimal(18,2)不允许有未四舍五入的字段税率判断的临界值比如5000、8000这类节点要用compareTo不能equals个税计算还要考虑边界情况。如果员工本月有补发工资那么累计收入和累计已预扣都会变公式必须按月重算而不是把这个月单独拎出来算。我们用试算接口专门验证这些边界上线前拿真实历史数据跑回归。4.3 跨域、路由刷新和文件下载的联调问题前后端分离项目跨域问题躲不掉。我们的处理原则是生产环境统一由nginx反向代理不在代码里开CORS开发环境使用Vite的proxy代理到网关。如果某一天你发现前端两个不同端口的请求都跨域了检查是不是网关和后端服务都配了CORS头导致浏览器收到重复的Access-Control-Allow-Origin。正确的做法是只在网关层配一次后端服务不再配置跨域过滤器。Vue采用history模式后nginx必须配置try_files让不存在的路径都回到index.html否则用户直接访问 /salary/detail/123 就会404。在nginx里加一行location / { try_files $uri $uri/ /index.html; }文件下载的问题前面提过后端响应如果是JSON错误会混进blob流。前端封装时要在response拦截器里判断Content-Type不能一刀切全当文件下载。还有一个细节大文件导出一定要用异步任务不要在前端等十分钟也别让tomcat线程被导出任务占着不放。4.4 幂等和消息重复消费工资条推送走MQ时网络抖动或者消费端重启都会导致消息重发。如果消费端不做幂等员工可能一天收到三条相同工资条系统里也会留下重复通知记录。我们在notify-service加了一张message_log表每个消息带一个唯一的messageId消费前先查该ID是否已处理已处理就直接返回表里给messageId建唯一索引双保险防止并发插入。同样的思路也用在银行代发文件生成上。每次生成文件前检查“月份批次号是否已生成”如果已生成就复用上次文件而不是重新生成。这个幂等设计在分布式环境里几乎天天用到核心就是“唯一键状态检查”。4.5 常见问题排查速查表现象原因解决办法网关转发到服务后404没配置StripPrefix检查网关路由中是否加了StripPrefix1Spring启动时NoSuchMethodErrorSpringCloud Alibaba版本不匹配按官方版本对应表整体升级不要单升一个跨域请求失败预检通过但实际请求失败网关和后端服务重复设置CORS头跨域统一只在网关层配置服务端禁用CorsFilter工资单金额汇总对不上double精度丢失或最后统一四舍五入使用BigDecimal每个薪酬项单独四舍五入同一部门工资单重复生成未加分布式锁或锁粒度太大Redis锁按“月份部门”加锁锁内做幂等检查Vue页面刷新404history模式未配置nginx加try_files配置工资单审批通过但财务未记账分布式事务未处理核心状态用Seata全局事务辅以对账脚本导出的Excel在接口报错时变成乱码前端把JSON错误当文件流处理了响应拦截器判断Content-TypeJSON走错误逻辑这套速查表里的每一条都是我们在迭代过程中实际遇到并解决的。建议新加入项目的人先把这张表打印出来贴在工位边上能省很多排查时间。做这个系统让我最想提醒后来者的不是某个组件版本而是业务上要给自己留对账后门。工资这种东西再怎么自动化最终都要回到“账要平、单要齐、每一分钱要能解释”这三件事。技术上把微服务拆得再漂亮如果月末对不上账所有架构优雅都白搭。建议你在项目启动那天就把详细的流水日志、审计日志和补偿脚本设计进去这比多写两个微服务值钱得多。
企业薪酬工资管理系统：SpringCloud微服务架构落地实践
干企业信息化这么多年我最怕的项目就是薪酬工资管理系统。怕的不是需求复杂而是它天生不允许出错——一次算薪错误全公司都能在下个月工资日准时发现。我负责的这套企业员工薪酬工资管理系统最终方案很直接后端SpringBoot前端Vue整体采用SpringCloud微服务分布式架构。Nacos管注册和配置Gateway做统一入口Redis扛分布式锁服务之间按业务边界拆开各管一摊。这篇文章把这些落地的思路、拆解、配置和坑一次说清楚适合正在做薪酬系统、或者准备用SpringCloud改造旧系统的朋友参考。1. 整体架构思路为什么非要用微服务1.1 薪酬系统真正难的不是“算工资”而是跨部门协作很多人觉得薪酬系统就是一个计算器输入出勤天数、绩效分数输出应发工资、扣税、实发工资。实际接手后才会发现它背后牵扯着人力资源部、财务部、IT部、公司高层甚至审计和银行。每个月有严格的算薪时间窗口几号之前提交考勤几号之前完成审批几号之前把银行代发文件送出去。任何一个环节卡住都会变成“全公司下周收不到工资”的事故。单体应用不是不能做但做到后面会非常别扭。我曾经维护过一套老旧的单体重型系统所有模块都在同一个应用里调用关系混乱代码里到处都是静态工具类互相薅数据。最头疼的是资源隔离问题月末算薪时大量工资单需要CPU密集计算同一时间报表模块又在跑全公司年度薪酬汇总两个任务挤在同一个JVM里互相拖慢。有一次算薪任务跑了40分钟还没结束就是因为报表查询把连接池占满了。这种场景下微服务拆分不是炫技而是为了让算薪服务、报表服务、审批服务能独立部署、独立扩容互不拖后腿。具体到这个项目我们把系统划分成几个独立的服务每个服务有独立的数据库或独立的schema。服务之间只通过API通信不共享数据表。为了支撑这套分布式体系引入了SpringCloud全家桶Nacos做注册中心和配置中心Gateway做统一入口OpenFeign做服务间调用Sentinel做限流降级。这套组合最大的价值是不用自己造轮子微服务治理里的服务发现、配置刷新、负载均衡、熔断限流都有现成组件可以接。1.2 技术选型SpringBoot、SpringCloud和Vue分别解决什么问题先理清一个很多人混淆的概念。Spring是一个基础容器框架核心是IOC和AOPSpringBoot把Spring的用法大幅简化用starter依赖和自动配置把项目跑起来SpringCloud则是在SpringBoot基础上提供微服务治理能力包括服务注册、配置中心、网关、熔断等。所以一个典型的SpringCloud微服务每个子服务本身就是一个SpringBoot应用外面套一层SpringCloud组件。很多初学者把SpringBoot和SpringCloud当成两个对立的东西其实它们是一层叠一层的。前端选Vue而不是JSP核心原因是组件化和前后端分离。薪酬管理界面有大量表单、弹窗、数据表格比如薪酬项配置、工资单明细、审批页面用Vue的组件模式写起来比后端套模板清爽得多。我们用的是Vue3 Element Plus Vite配合Pinia做状态管理。页面上的逻辑都通过axios调用后端API前端只关心交互后端只关心业务和计算两边各守各的边界。这套组合的实际好处在项目中期体现得特别明显。有次财务提出要调整个税计算页面希望把累计预扣明细展示得更清楚。如果是单体JSP前后端代码混在一起改一个页面可能要连带动Controller和SQL但在Vue工程里我只需要新写一个组件加载工资单数据后做前端展示计算后端接口基本不动两天就上线了。1.3 服务边界怎么划共享什么独立什么服务拆分最怕拍脑袋。如果按“Controller层拆一个服务、Service层拆一个服务”这种技术分层来拆那只是把单体变成了分布式单体调用链路乱成一团出了故障反而更难排查。正确做法是按业务能力拆每个服务围绕一块清晰的业务领域。这个薪酬系统最终拆分为以下服务服务名称核心职责关键数据system-service用户、角色、菜单、字典、权限用户表、角色表、菜单表employee-service员工主数据、入转调离、组织架构员工档案、部门、岗位salary-service薪酬项、薪酬方案、算薪、工资单薪酬项、工资单、个税记录approval-service审批流程引擎、审批记录审批单、审批节点report-service月度汇总、成本分析、对外报表汇总表、统计快照notify-service站内信、邮件、短信工资条消息记录、发送日志file-service附件存储、工资单PDF、银行代发文件MinIO对象存储每个服务独立部署后最大好处是故障隔离。算薪服务因为临时数据异常OOM了报表服务还能正常对外提供查询系统服务挂了其他服务虽然认证会受影响但至少工资单查询页面不会跟着一起卡死。缺点也很明显服务间调用有网络开销需要处理分布式事务、数据一致性、重复请求。正因为这些代价我们才在第三部分重点讲了锁、事务和幂等处理这些不是可选项而是分布式架构下的必修课。服务拆分还有一个原则能不同步数据就尽量不同步必须要冗余的数据也要控制在最小范围。比如工资单里需要显示员工部门和岗位我们没有让salary-service每次去查employee-service而是在生成工资单的时候冗余了一份部门编码和岗位名称快照。这样算薪过程中即使员工调岗历史工资单还是显示当时的部门不会算完突然变了。历史数据不能跟着主数据漂移这是薪酬系统里特别容易踩的坑。2. 核心业务功能设计与关键细节2.1 员工主数据和组织架构一切计算的起点员工主数据是薪酬计算的源头。工号必须唯一身份证号要严格校验银行卡号和开户行要分字段保存手机号、邮箱要保证能收到工资条通知。更关键的是入职日期、转正日期、离职日期这些日期直接参与司龄工资、年假折算、离职结算的计算差一天都可能引发争议。员工状态也要建模清楚。我们设计了在职、试用期、待离职、离职、停薪留职等状态每个状态对应不同的算薪规则。试用期员工没有某些补贴离职员工要算离职补偿停薪留职不发放全勤奖。这些规则不能散落在代码的if-else里而是做成可配置的规则项由HR在薪酬方案里维护。组织架构本身是一棵树部门调整时有发生。为了不影响历史月份工资单employee-service提供组织快照能力。每月算薪前系统会生成一份当月的部门快照工资单上记录的是快照里的部门编码而不是实时去查当前组织树。否则3月份财务调整了部门4月再看3月工资单历史数据全变对账根本没法做。另外员工薪酬数据属于敏感信息前端展示要做脱敏处理。银行卡号中间8位打码手机号只保留前3后4身份证号同样处理。数据权限上普通HR只能看自己负责的部门薪酬专员能看全部但操作要留痕部门负责人只能看汇总不能看个人明细。这一切在网关层做登录校验在各个服务里做二次数据权限校验前端再隐藏按钮三层配合。2.2 薪酬计算引擎规则要能配置金额要用对类型薪酬计算是salary-service的核心。我把薪酬项分成三类固定项基本工资、岗位工资、计算项绩效工资绩效基数×绩效系数、加班费基本工资/21.75×加班天数×倍数、扣款项事假扣款、社保个人部分、个税。每个薪酬项有计算顺序先算应发项再算应扣项最后算个税和实发。我们用表达式引擎来管理规则没有把所有公式硬编码在Java里。薪酬项表大致长这样salary_item_code -- 薪酬项编码 item_name -- 薪酬项名称 calc_type -- fixed / formula formula_expression -- 格式化表达式 priority -- 计算顺序 is_taxable -- 是否计税 is_active -- 是否启用表达式引擎选择了Aviator轻量、性能好还支持自定义函数。比如这样一条规则basicSalary positionSalary (performanceBase * performanceScore)HR不需要改代码只要在管理界面配置好公式算薪任务就能读取并执行。为了避免公式写错导致灾难性结果每次修改薪酬方案时我们都要跑一遍“试算”拿上个月的工资单做对比差异超过一定比例就告警。金额计算是薪酬系统的高危区。Java里float和double绝对不能用来算钱二进制的浮点数表示会导致精度丢失。我们全部用BigDecimal而且必须用字符串构造或者BigDecimal.valueOf禁止直接new BigDecimal(0.1)。所有金额字段在数据库里用decimal(18,2)对外统一保留两位小数。每项薪酬项计算完成后单独四舍五入而不是等到最后实发时才四舍五入否则明细汇总金额和实发金额会有尾差财务对账会疯掉。个税计算这半年改得频繁我们是把税率表做成配置表每次政策调整只更新配置不需要发版。个税用累计预扣法按月累计算收入、累计减除费用、累计专项附加扣除再算出累计应纳税额减去已预缴部分得到当月个税。这里一定要用一个幂等的计算服务同一个员工、同一个月、同一薪酬方案多次调用结果必须一致。2.3 工资单审批状态机和发放流程工资单不能算完就直接发必须走审批流。我们把工资单状态设计成一条清晰的状态机草稿、待审批、审批中、已通过、已驳回、已归档。员工一月份的工资单在审批通过后就不能再被普通HR编辑如果真需要调整必须走“更正单”流程改正后重新审批保留所有历史修改记录。这个设计保护了HR也保护了员工信任。审批流由approval-service统一管理但工资单状态本身保存在salary-service。两个服务的协作方式是approval-service负责流程引擎、审批人判定、审批记录审批通过后通过API通知salary-service更新状态。salary-service只认审批事件不直接依赖approval-service的工作流表。这样即使工作流引擎要换也不会污染工资单核心数据。审批完成后进入发放环节。系统会生成银行代发文件文件名包含月份和批次号内容按银行要求的格式生成。文件生成后必须先做试算校验代发总额必须等于工资单实发总额笔数必须等于通过的工资单数量。校验不通过就阻断下发防止出现全公司工资错发的灾难。发放完成后工资单状态进入已归档同时通过notify-service给员工推送工资条。2.4 报表统计和分页查询的实操细节报表服务承接了所有查询分析压力。月度工资汇总表、部门成本分析表、社保公积金汇缴表、个税申报表每类报表数据量大SQL join多。这里我们用MyBatis分页插件先解决列表查询的性能问题配置一个拦截器分页参数由前端传入查询自动带limit和count。但真正能抗住压力的不是分页而是“预汇总”。每月算薪完成后salary-service会生成一张月度汇总快照表按部门、岗位、薪酬项维度提前聚合。报表服务查询时直接查快照不再实时扫描工资单明细。这个优化非常有效原本需要十几秒的年度汇总报表查询时间降到一秒以内。导出Excel也做成了异步任务。前端点“导出”后端先创建导出任务并返回任务ID用户在页面上等着导出完成后通过WebSocket收到通知再下载。导出用POI的SXSSFWorkbook流式写文件几十万行数据不会OOM。下载接口做成一次性token避免业务人员拿着Excel下载链接到处乱发。3. 分布式架构落地实操记录3.1 Nacos注册中心与配置中心先把基础环境搭稳这套系统的第一个基础设施是Nacos。我们使用Nacos同时承担注册中心和配置中心两个角色。每个SpringBoot服务启动时自动注册到Nacos调用方通过服务名而不是IP地址访问这解决了一个很实际的问题服务部署在多台服务器上实例IP可能会变不可能手写IP列表。服务端的配置如下我截取的是salary-service的bootstrap配置spring: application: name: salary-service profiles: active: dev cloud: nacos: discovery: server-addr: 127.0.0.1:8848 namespace: 5e5cdb3c-xxxx-xxxx group: SALARY_GROUP config: server-addr: 127.0.0.1:8848 namespace: 5e5cdb3c-xxxx-xxxx file-extension: yaml shared-configs: ->spring: cloud: gateway: routes: - id: salary-service uri: lb://salary-service predicates: - Path/api/salary/** filters: - StripPrefix1 - id: employee-service uri: lb://employee-service predicates: - Path/api/employee/** filters: - StripPrefix1StripPrefix1特别关键。前端请求的是 /api/salary/salary-list网关剥离掉第一层api后转发给salary-service的路径是 /salary/salary-list和后端Controller的RequestMapping匹配。如果不加这个过滤器salary-service收到的是 /api/salary/salary-list如果后端没有这个映射就直接404排查起来一头雾水。网关层做的第二件事是统一鉴权。我们在Gateway里写了一个全局过滤器对所有请求校验JWT直接把token中的用户ID和权限标识解析出来放到请求头里转发给下游服务Component public class AuthGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { String auth exchange.getRequest().getHeaders().getFirst(Authorization); // 校验token解析userId、userName、tenantId ServerHttpRequest request exchange.getRequest().mutate() .header(X-User-Id, userId) .header(X-User-Name, userName) .build(); return chain.filter(exchange.mutate().request(request).build()); } }这样做的好处是下游业务服务不用再关心token解析逻辑直接从Header里取当前用户。注意网关过滤器和业务代码不要耦合太深网关只做身份校验和路由不做具体的薪酬计算或权限判断。权限判断还得在每个服务里做因为网关你没法知道某个按钮级权限是否匹配。3.3 服务间调用OpenFeign如何传递用户上下文服务间的调用我们在salary-service里通过OpenFeign调用employee-service查询员工基础信息。Feign配置简单但有一个分布式场景下的经典问题用户信息传递。前端调用salary-service时X-User-Id在网关已经写进Header但salary-service通过Feign再去调用employee-service时这个Header不会自动透传。如果employee-service需要知道当前操作人比如记录“谁修改了员工状态”就必须把用户ID传过去。解决办法是给Feign加一个RequestInterceptor在发请求时把当前请求上下文中的Header复制到新的Feign请求里public class FeignUserContextInterceptor implements RequestInterceptor { Override public void apply(RequestTemplate template) { ServletRequestAttributes attributes ServletRequestAttributes.getRequestAttributes(); if (attributes ! null) { HttpServletRequest request attributes.getRequest(); template.header(X-User-Id, request.getHeader(X-User-Id)); template.header(X-User-Name, request.getHeader(X-User-Name)); } } }这里要特别注意异步线程的情况——如果你用异步线程池发起Feign调用ServletRequestAttributes可能为空用户上下文会丢失。我们的做法是利用ThreadLocal或者直接使用Spring Cloud的RequestContextHolder传参异步调用则显式把用户ID作为方法参数传进线程。概括成一句话分布式链路里用户身份要么始终放Header传递要么显式在方法参数里传不要指望框架自动帮你穿来穿去。配合Sentinel做服务保护。工资单查询接口和算薪接口都配置了流控规则。比如算薪接口单机QPS阈值20超过的请求排队等待对查询报表的外部接口设置关联限流如果报表服务处理不过来直接降级返回“系统繁忙”。Sentinel和OpenFeign结合后某服务挂了不会把整个调用链拖死。我们就在一次模拟故障时验证过employee-service宕机后salary-service的接口立刻降级并返回熔断提示而不是一直等连接超时。3.4 算薪防重Redis分布式锁的痛点和解决这个系统里有一个很典型的分布式问题用户连续点击两次“生成某月工资单”同一部门、同一月份可能被并发算薪生成两份工资单。单机时代可以用synchronized锁一个对象但服务拆成多实例后每个实例的同步锁互不认账必须用分布式锁。我们使用Redis分布式锁。最简单的实现是SETNX加过期时间String lockKey salary:calc: yearMonth : deptId; String requestId UUID.randomUUID().toString(); Boolean locked redisTemplate.opsForValue().setIfAbsent(lockKey, requestId, 30, TimeUnit.SECONDS); if (!Boolean.TRUE.equals(locked)) { throw new RuntimeException(该部门本月工资单正在生成中请勿重复提交); } try { // 执行算薪任务生产者发送消息到MQ异步处理 } finally { String currentValue redisTemplate.opsForValue().get(lockKey); if (requestId.equals(currentValue)) { redisTemplate.delete(lockKey); } }为什么finally里要比较requestId就是防止一个线程的锁过期被自动释放后另一个线程拿到了新锁而第一个线程的finally执行delete把别人的锁删掉。比较value再删除这是必须做的“先查后删”步骤。更严谨的做法是直接用Lua脚本保证compare-and-delete的原子性。锁的时间设置也要讲究。算薪任务是异步的真正耗时的计算已经放到MQ里所以锁不需要长时间占用。锁的粒度是月份部门而不是“全公司”一把锁。如果是全公司一把锁任何一个部门算薪没结束其他部门全部被阻塞月底算薪高峰期会拖到很晚。拆到部门粒度各算各的互不干扰。生产环境我更推荐用Redisson它有看门狗机制自动续期不会因为业务执行超过锁过期时间就提前释放。但用Redisson也别把锁范围定太大关键还是锁粒度设计。3.5 发薪数据一致性分布式事务的取舍分布式事务是SpringCloud项目里最让人头疼的一块。我们的典型场景审批通过后工资单状态要改成“已通过”同时要在财务模块生成一笔待付账记录。这个操作跨了salary-service和account-service财务模块我们直接复用外部财务系统接口两个服务各自有本地事务没法用同一个数据库事务搞定。具体方案我们做了一个对比方案优点缺点适用场景Seata AT模式代码侵入小框架自动回滚需要额外部署TC对数据库连接和undo_log有要求一致性要求高、并发不极端的状态变更本地消息表 MQ解耦方案稳定需要处理消息幂等、重试、对账最终一致可接受的异步业务定时对账 人工补偿实现简单兜底能力强延迟高不能实时拦截错误所有场景的最后一道防线我们最终选了比较务实的组合工资单状态更新用Seata的AT模式做全局事务保证核心状态和财务报表同步异步消息通知和工资条推送走MQ允许最终一致但消费端必须做幂等。同时每天凌晨跑一个对账脚本检查工资单状态、财务记账、银行代发文件三者是否金额一致。这个对账脚本看上去很土但每次版本上线都靠它兜底。Seata使用中有一个很重要的认知AT模式不是免费午餐。它会在事务期间持有数据库行锁如果并发冲突高反而可能拖垮性能。薪资审批是低频操作采用AT完全没问题但如果抢购、秒杀这类超高并发场景就别硬上Seata了。3.6 前端Vue工程化动态路由、权限、导出文件前端使用Vue3 Element Plus Vite工程结构按功能模块划分。登录后调用system-service的菜单接口拿到当前用户的菜单树和按钮权限标识动态生成路由。这样做的好处是不同角色登录看到不同的导航且刷新页面后路由依然能恢复。路由守卫的伪代码大致是router.beforeEach((to, from, next) { if (!userStore.token) { next(/login); } else if (userStore.menus.length 0) { userStore.loadMenus().then(() { // 动态添加路由后再进入目标页面 next({ ...to, replace: true }); }); } else { next(); } });按钮权限用自定义指令控制。比如调薪按钮需要“salary:adjust”权限没有权限的账号渲染时直接移除DOM。这里有个细节前端隐藏按钮只是体验层面的控制真正的权限判断一定要在后端接口上做。因为懂开发的人随手就能改前端代码把按钮显示出来后端如果没有校验就等于权限白设。axios封装时要注意文件导出。导出工资单Excel时请求返回的是blob流但后端如果处理出错返回的是JSON错误信息。前端的响应拦截器里要先判断response.headers的类型是application/json就走统一错误处理是application/octet-stream才写入文件。我见过不少项目在这个地方踩坑明明接口报错却下载了一个空文件或一堆乱码。Vue调试时一定要装Vue DevTools查看路由状态、Pinia数据和组件props都非常直观。页面里工资单编辑器、工资条预览、审批历史三个组件是最常用的做成通用组件放到前端公共目录后续接社保模块或者公积金模块也都能复用。生产环境构建完注意nginx配置history路由否则刷新页面就404。4. 踩坑记录与排查方法4.1 版本兼容是最容易翻车的点搭建SpringCloud项目最烦躁的问题就是版本不匹配。SpringBoot、SpringCloud、SpringCloud Alibaba三者版本号不是一起发布的如果随便从网上找依赖组合启动时经常冒出NoSuchMethodError、ClassNotFoundException看堆栈看半天也定位不到。我这边当时用的是一套比较稳的组合Spring Boot 2.6.xSpring Cloud 2021.0.xSpring Cloud Alibaba 2021.0.xNacos Server 2.2.3Sentinel 1.8.6。列表仅作参考因为版本兼容关系随着时间一直在变真正靠谱的方式是打开Spring Cloud Alibaba官方项目wiki找到版本对应关系表按表格里的组合来配。不要只升级其中一个组件要整体同步升级。排查版本冲突时熟练使用mvn dependency:tree非常关键。比如Sentinel和OpenFeign同时存在时可能两个jar包传递依赖了不同版本的fastjson或jackson最终导致JSON序列化异常。这时统一通过dependencyManagement锁定版本比在pom里到处写排除靠谱。4.2 金额精度和计算顺序用double算工资等于事故这个坑我再强调一遍因为它带来的后果太严重。例如0.1 0.2用double计算结果是0.30000000000000004。工资单上写着应发7320.60元报表却显示7320.599999999999差几厘钱累计起来月底对账永远不平。我们的规则很简单所有金额字段类型用BigDecimal构造BigDecimal时用字符串或BigDecimal.valueOf禁止new BigDecimal(0.1)每个薪酬项算完就统一四舍五入到两位小数数据库decimal(18,2)不允许有未四舍五入的字段税率判断的临界值比如5000、8000这类节点要用compareTo不能equals个税计算还要考虑边界情况。如果员工本月有补发工资那么累计收入和累计已预扣都会变公式必须按月重算而不是把这个月单独拎出来算。我们用试算接口专门验证这些边界上线前拿真实历史数据跑回归。4.3 跨域、路由刷新和文件下载的联调问题前后端分离项目跨域问题躲不掉。我们的处理原则是生产环境统一由nginx反向代理不在代码里开CORS开发环境使用Vite的proxy代理到网关。如果某一天你发现前端两个不同端口的请求都跨域了检查是不是网关和后端服务都配了CORS头导致浏览器收到重复的Access-Control-Allow-Origin。正确的做法是只在网关层配一次后端服务不再配置跨域过滤器。Vue采用history模式后nginx必须配置try_files让不存在的路径都回到index.html否则用户直接访问 /salary/detail/123 就会404。在nginx里加一行location / { try_files $uri $uri/ /index.html; }文件下载的问题前面提过后端响应如果是JSON错误会混进blob流。前端封装时要在response拦截器里判断Content-Type不能一刀切全当文件下载。还有一个细节大文件导出一定要用异步任务不要在前端等十分钟也别让tomcat线程被导出任务占着不放。4.4 幂等和消息重复消费工资条推送走MQ时网络抖动或者消费端重启都会导致消息重发。如果消费端不做幂等员工可能一天收到三条相同工资条系统里也会留下重复通知记录。我们在notify-service加了一张message_log表每个消息带一个唯一的messageId消费前先查该ID是否已处理已处理就直接返回表里给messageId建唯一索引双保险防止并发插入。同样的思路也用在银行代发文件生成上。每次生成文件前检查“月份批次号是否已生成”如果已生成就复用上次文件而不是重新生成。这个幂等设计在分布式环境里几乎天天用到核心就是“唯一键状态检查”。4.5 常见问题排查速查表现象原因解决办法网关转发到服务后404没配置StripPrefix检查网关路由中是否加了StripPrefix1Spring启动时NoSuchMethodErrorSpringCloud Alibaba版本不匹配按官方版本对应表整体升级不要单升一个跨域请求失败预检通过但实际请求失败网关和后端服务重复设置CORS头跨域统一只在网关层配置服务端禁用CorsFilter工资单金额汇总对不上double精度丢失或最后统一四舍五入使用BigDecimal每个薪酬项单独四舍五入同一部门工资单重复生成未加分布式锁或锁粒度太大Redis锁按“月份部门”加锁锁内做幂等检查Vue页面刷新404history模式未配置nginx加try_files配置工资单审批通过但财务未记账分布式事务未处理核心状态用Seata全局事务辅以对账脚本导出的Excel在接口报错时变成乱码前端把JSON错误当文件流处理了响应拦截器判断Content-TypeJSON走错误逻辑这套速查表里的每一条都是我们在迭代过程中实际遇到并解决的。建议新加入项目的人先把这张表打印出来贴在工位边上能省很多排查时间。做这个系统让我最想提醒后来者的不是某个组件版本而是业务上要给自己留对账后门。工资这种东西再怎么自动化最终都要回到“账要平、单要齐、每一分钱要能解释”这三件事。技术上把微服务拆得再漂亮如果月末对不上账所有架构优雅都白搭。建议你在项目启动那天就把详细的流水日志、审计日志和补偿脚本设计进去这比多写两个微服务值钱得多。
