做后端这些年被同行问得最多的一类问题就是Java小程序到底该怎么搭。先把话说清楚这里讲的Java小程序不是早年浏览器里那个要装插件的 Applet而是指小程序这种前端形态背后、用 Java 兜住接口服务与业务逻辑的那整套东西。它的分工其实很干脆——小程序端管界面、管交互、管本地缓存Java 侧管身份、管数据、管权限、管那些绝对不能放到客户端的判断。很多刚接手的同学会误以为小程序嘛前端重一点就行真跑到线上才发现接口幂等没做、令牌没续期、并发一上来连接池就爆问题全在后端。这篇东西适合三类人刚从小程序前端转全栈的、要独立扛一个 Java小程序后端项目的、以及已经在写但总觉得代码越写越乱的。下面按我自己的落地顺序从架构判断讲到动手搭骨架再到线上排查尽量把每一步为什么这么定说透。1. 先判断清楚Java在小程序这套体系里的真实站位1.1 小程序的三层结构以及前后端分离到底分在哪把一个小程序拆开看其实只有三层客户端渲染层、平台侧的网关层、你自己的业务服务层。渲染层跑在用户手机上受包体积、内存、网络环境限制平台网关负责把请求转发给你的服务器同时做一些基础的风控和来源校验业务服务层才是 Java 真正的主场。很多人调试时会懵明明是本地代码写错了报错却从平台侧返回就是因为没搞清责任边界。我一般会画一条简单的分界线凡是结果不能由客户端单方面决定的逻辑全部落在 Java 侧。用户看到的余额、订单状态、优惠是否可用、内容是否可见这些数值必须由服务端算完再下发客户端只负责展示。反过来动画、列表滚动、表单即时校验这类纯体验的东西放在小程序端就好别为了架构统一把它们也搬到后端白白增加一次网络往返。这条线划清楚之后还有一个绕不开的现实小程序端是没有常驻进程概念的页面一关内存里的东西就没了。所以客户端的登录态必须靠令牌维持而令牌的签发、校验、续期、注销全是 Java 侧要写的代码。这就是为什么我说Java小程序的复杂度八成集中在会话和数据一致性这两个词上。1.2 为什么后端多半落在 Java 上三个挺实在的理由第一个理由是人。小程序项目通常起得快但活下来之后要接的东西特别杂——对账、导出、定时任务、第三方回调、内部管理系统复用同一套数据。Java 生态在这些脏活上的积累最厚一个成熟的 ORM、一个靠谱的任务调度、一套现成的权限模型能省下大量从零造轮子的时间。第二个理由是工程约束。Java 的强类型和编译期检查在中大型团队里是硬需求。小程序接口字段经常变前后端如果是两个人写没有类型约束字段名拼错、类型对不上这种低级错误能拖掉半天。用 Java 定义好请求响应对象编译不过就是编译不过问题在提交前就暴露了。第三个理由是可观测性。线上出问题时你需要一条完整的链路哪个用户、哪个接口、耗时多少、卡在数据库还是下游。Java 侧成熟的日志框架、指标采集、链路追踪组件接进去成本很低。我做过一个对比同样是排查某个接口偶尔慢 3 秒有完整链路记录的项目半小时定位没有的一整天在猜。1.3 什么时候别硬上 Java以及轻量方案的取舍也不是所有场景都适合。如果只是做一个纯展示的活动页数据从内容管理系统里读一天几百次请求那用 Java 起一整套服务纯属浪费运维成本比开发成本还高。这种情况我通常建议先用平台侧提供的云函数或者轻量服务顶一阵等业务真的长出复杂度了再迁。还有一种情况是团队里没人熟悉 JVM 调优。Java 服务的坑往往不在写代码而在运行期堆内存怎么设、垃圾回收怎么选、连接池开多大。如果没有一个人能看懂这些参数线上一次内存告警就够喝一壶。我的经验是团队里至少要有一个能独立看线程栈和堆快照的人再决定用 Java 扛核心链路否则先把非核心的部分放上去试水。至于版本选择新项目我一般直接上长期支持版本别贪新。生态兼容性比语言特性重要得多你用的那些中间件客户端、序列化库未必跟得上最新版本的节奏。2. 整体设计从一次请求进来开始拆解2.1 一次小程序请求的完整生命周期把一次请求摊开看路径大致是这样用户点按钮 → 小程序端组装参数 → 平台网关转发 → 你的接入层反向代理→ 应用服务 → 业务逻辑 → 数据访问 → 组装响应 → 原路返回。这条链上每一段都可能成为瓶颈但排查顺序不能乱得从最有把握的地方开始。接入层我一般只做三件事终止加密连接、按路径做简单分流、限制单 IP 的请求频率。业务判断一律不进接入层因为配置写多了很难维护出了问题也不好回溯。应用服务层才是做鉴权、参数校验、业务编排的地方这一层的原则是薄控制器、厚服务控制器只负责接收和返回把所有判断塞进服务类。数据访问层要注意的是别让一次请求打太多次库。我见过一个接口为了拼一个列表循环里查了 40 多次数据库单次 2 毫秒加起来 80 多毫秒QPS 一上来数据库连接就被占满了。正确做法是批量查、内存拼装或者干脆让数据库一次关联查完。2.2 分层边界怎么划才不会越写越乱分层这件事教程里都写控制器、服务、仓储三层但真正落地时最容易糊掉的是服务层该多厚。我的判断标准很朴素一个服务方法如果里面出现了跨两个以上业务概念的操作就该拆。比如下单会涉及库存、订单、优惠三块那就拆成三个内部方法主方法只负责编排顺序和事务边界。事务边界是个高频雷区。很多人在控制器上直接加事务注解结果一次请求里包了好几件不相关的事任何一步失败全部回滚日志还看不出是哪一步。我的做法是把事务控制在服务方法上并且明确这个方法的语义是要么全成要么全不成那些可以失败但不影响主流程的动作比如发一条通知一律挪到事务外面用异步或者事后补偿处理。还有一点容易被忽略异常的处理层次。业务异常应该在服务层抛出由统一入口捕获转成响应技术异常数据库连不上、下游超时要单独记日志并告警不能和业务异常混在一个处理分支里否则真正的故障会被淹没在参数不合法这种噪音里。2.3 鉴权方案的选择会话标识与自包含令牌怎么选这是 Java小程序项目里第一个要拍板的架构决定。两种主流做法一种是服务端存会话客户端只拿一个随机标识另一种是令牌自带签名服务端不存状态。前者好理解、能随时踢人下线但每次请求都要查一次存储后者省了查询但注销和权限变更会有延迟。我的取舍是这样的如果业务对立刻失效有硬要求比如涉及资金操作、后台管理那走服务端存储别犹豫。如果是普通的内容浏览、点赞收藏这类用自包含令牌完全够配合较短的过期时间加刷新机制安全性和性能都能接受。混合方案也常见——主体用令牌敏感操作再查一次服务端状态这样把成本和安全性做了折中。注意无论选哪种令牌都必须带签发时间、过期时间和唯一标识。少了唯一标识出问题时你连这个令牌是哪次登录发的都查不出来只能全量踢下线。3. 核心细节拆解登录、令牌与数据交互3.1 登录闭环从临时凭证到自有用户体系小程序的登录流程和传统网页不一样它没有账号密码输入这一步。客户端通过平台侧拿到一个短期有效的临时凭证把它传给 Java 服务端服务端拿着这个凭证加上自己的应用标识和应用密钥去平台侧换回用户的唯一标识和会话信息。这个换的动作必须放在服务端做因为应用密钥绝对不能出现在客户端代码里反编译一下就能拿到。换回来之后一般有两种处理如果业务只需要识别是不是同一个人那直接把平台唯一标识当主键用就行但绝大多数业务会长出自己的用户表因为要存昵称、头像、手机号、会员等级这些东西。我的做法是建一张映射表平台标识和自有用户 ID 一一对应首次登录时自动创建用户记录后续登录直接查映射。这里有个细节特别关键登录接口必须做幂等。用户手抖点两下、网络抖动重试都可能让同一个临时凭证被提交两次。如果代码里是查不到就插入两个请求并发过来就会插出两条用户记录然后这个人的数据从此分成两半修复起来极其痛苦。解决办法是在平台标识字段上加唯一索引捕获唯一冲突异常后回查一次返回已存在的记录。public LoginResult login(String tempCredential) { // 1. 服务端换取平台侧身份密钥不出服务端 PlatformUser platformUser platformClient.exchange(tempCredential); // 2. 先查映射命中直接返回 UserMapping mapping mappingRepo.findByPlatformId(platformUser.getOpenId()); if (mapping ! null) { return issueToken(mapping.getUserId()); } // 3. 未命中才创建依赖唯一索引兜住并发 try { Long userId userService.createFromPlatform(platformUser); mappingRepo.insert(platformUser.getOpenId(), userId); return issueToken(userId); } catch (DuplicateKeyException e) { // 并发下另一条请求已创建回查即可 UserMapping existing mappingRepo.findByPlatformId(platformUser.getOpenId()); return issueToken(existing.getUserId()); } }这段代码里第三步的异常捕获不是容错补丁而是设计的一部分。很多同学觉得捕获异常不优雅但在并发创建场景下唯一索引加回查是成本最低、最可靠的方案比加分布式锁轻量得多。3.2 令牌有效期与刷新策略的参数推算令牌多久过期这个数不能拍脑袋。定太短用户频繁被踢定太长一旦泄露风险窗口巨大。我的推算逻辑是从用户行为出发的普通用户一次使用时长通常在 3 到 15 分钟间隔几小时再回来。把访问令牌有效期定在 2 小时能覆盖绝大多数连续使用场景又不会让泄露后的窗口太长。刷新令牌则是另一回事它决定用户多久需要重新点一次授权。这个值要看业务对留存的要求我一般定 7 到 30 天。7 天适合低频工具类30 天适合高频内容类。这里有个成本账要算刷新令牌必须存服务端因为要能主动作废如果日活 5 万、人均 1.2 个活跃设备那就是 6 万条记录按每条 200 字节算约 12MB这个量级放缓存里毫无压力。刷新动作本身也有讲究。我见过把刷新做成每次请求都刷新的实现结果令牌一直在变多端同时在线就互相顶掉用户被反复踢下线。正确做法是设一个刷新阈值当访问令牌剩余有效期低于总量的三分之一时才触发刷新比如 2 小时有效期剩不到 40 分钟才换新的。这样既避免了频繁刷新又保证用户在持续使用时不会突然过期。参数建议取值推算依据常见错误访问令牌有效期2 小时覆盖单次连续使用时长设成 7 天泄露后无法挽回刷新令牌有效期7 至 30 天按业务使用频率定与访问令牌设成一样长刷新触发阈值剩余不足三分之一减少无意义刷新每次请求都刷新导致互踢令牌唯一标识长度不少于 32 位随机值防碰撞用自增 ID 做标识3.3 接口字段设计让前端少写一半兼容代码小程序接口的字段设计直接影响前后端协作的摩擦成本。我踩过的坑里最高频的是空值语义不清一个字段没返回到底是没有这个数据还是服务端忘了填前端的处理方式完全不同。我的规范是列表字段永远返回空数组而不是不返回对象字段如果可能为空就显式返回空对象或者明确的占位绝不省略。第二个坑是数值精度。小程序端处理大整数时超过某一位数会丢精度订单号、长整型 ID 传过去可能就变了。我的做法是所有超过安全范围的数值统一转成字符串传输客户端不需要做任何转换直接用就行。这个约定要在项目开始就定死后期改起来要动所有接口。第三个是时间格式。我统一用带时区的标准格式或者毫秒时间戳二选一全项目一致。混用是最要命的前端一会儿按字符串解析一会儿按数字解析出了问题很难判断是哪个接口的锅。字段命名也一样到底用驼峰还是下划线定一个就写进文档别让不同的人写不同的风格。4. 动手搭骨架从工程初始化到本地跑通4.1 依赖清单与工程结构新起一个 Java小程序后端我的依赖清单压得很克制。核心就几样Web 框架提供路由和参数绑定、数据访问层、数据库驱动、连接池、缓存客户端、参数校验组件、日志门面加实现。那些看起来很有用的全家桶先别加加进去之后每个都要配配置项本身就会变成维护负担。工程结构按功能切不按技术切。也就是说不建控制器包服务包然后每个功能都往里塞一个类而是按业务模块分目录每个模块内部自带自己的控制器、服务、数据对象。这样做的好处是删除一个功能时直接删一个目录不用在四个包里翻来翻去。项目小的时候两种差别不明显超过二十个功能之后按模块切的优势就出来了。src/main/java/com/example/app ├── common 公共能力 │ ├── auth 鉴权拦截、令牌工具 │ ├── exception 统一异常与错误码 │ └── util 通用工具 ├── modules │ ├── user 用户模块 │ │ ├── UserController.java │ │ ├── UserService.java │ │ └── dto 出入参对象 │ ├── order 订单模块 │ └── content 内容模块 └── Application.java 启动入口配置文件里我只强调两个东西日志级别和连接池上限。开发环境把业务日志开到详细方便调试生产环境一律收紧只保留关键节点不然磁盘一天就满。连接池上限别贪大很多人设成 100觉得越多越快实际上数据库侧的最大连接数有限应用侧开太大只会让请求在数据库那头排队反而拖长响应。4.2 令牌签发与校验的落实现场令牌签发这块我用的方案是签名式令牌载荷里放用户 ID、签发时间、过期时间、唯一标识用服务端持有的密钥签名。为什么不加密只签名因为载荷里不该放敏感信息用户 ID 本身不敏感加密反而增加复杂度。密钥存在配置中心或者环境变量里绝对不能写进代码仓库。public String issueToken(Long userId) { long now System.currentTimeMillis(); long expireAt now ACCESS_TOKEN_TTL_MILLIS; // 2 小时 String tokenId UUID.randomUUID().toString().replace(-, ); String payload String.join(|, String.valueOf(userId), String.valueOf(now), String.valueOf(expireAt), tokenId); String signature hmacSha256(payload, secretKey); return base64UrlEncode(payload) . signature; } public Long verifyAndGetUserId(String token) { String[] parts token.split(\\.); if (parts.length ! 2) { throw new BizException(ErrorCode.TOKEN_MALFORMED); } String payload base64UrlDecode(parts[0]); String expected hmacSha256(payload, secretKey); if (!constantTimeEquals(expected, parts[1])) { throw new BizException(ErrorCode.TOKEN_INVALID); } String[] fields payload.split(\\|); long expireAt Long.parseLong(fields[2]); if (System.currentTimeMillis() expireAt) { throw new BizException(ErrorCode.TOKEN_EXPIRED); } return Long.parseLong(fields[0]); }签名比对必须用恒定时间比较普通的字符串相等在理论上会泄露时间信息。这个细节在真实攻击场景里可能不太现实但成本几乎为零没有理由不做。另外过期校验一定要在服务端做客户端传来的任何时间戳都不可信。4.3 拦截器、全局异常与错误码设计拦截器负责在请求进入业务逻辑前做统一校验从请求头取出令牌解析出用户 ID塞进当前请求的上下文里。这样业务代码里就不需要到处传用户 ID直接从上下文取。要注意的是上下文必须在请求结束时清理否则线程被复用时下一个请求可能读到上一个用户的身份这是个非常隐蔽的越权漏洞。Component public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest req, HttpServletResponse resp, Object handler) { String token req.getHeader(Authorization); if (token null || token.isBlank()) { throw new BizException(ErrorCode.TOKEN_MISSING); } Long userId tokenService.verifyAndGetUserId(stripPrefix(token)); RequestContext.setUserId(userId); return true; } Override public void afterCompletion(HttpServletRequest req, HttpServletResponse resp, Object handler, Exception ex) { RequestContext.clear(); // 必须清理防止线程复用串号 } }全局异常处理的价值在于统一响应结构。业务异常返回明确的错误码和提示语技术异常返回统一的服务繁忙提示同时把堆栈记进日志。错误码我建议分段1 开头是通用错误2 开头是用户相关3 开头是业务相关这样看错误码就能大致定位问题范围排查效率提升明显。4.4 本地联调与接口自测本地调试小程序后端最麻烦的是登录态。平台侧的临时凭证只能在真机或模拟器里拿到本地接口测试没法直接用。我的做法是在开发环境开一个调试登录通道输入一个测试用户标识直接签发令牌这个通道用配置开关控制生产环境必须关闭最好在打包流程里加检查。自测环节我一般准备一份可反复执行的请求集合覆盖正常流程、边界值、越权访问三类。越权这块最容易被漏掉用小明的令牌去请求小红的订单详情如果返回了数据说明你的接口只验了登录了没没验是不是你的数据。这个检查在每次改动后都跑一遍能挡住绝大多数严重问题。提示接口返回里不要带内部主键以外的敏感字段比如手机号全量、身份标识、内部状态码。需要展示时做脱敏脱敏逻辑写在服务端客户端只拿展示值。5. 常见问题排查实录与速查表5.1 线上高频故障的分类与定位顺序线上问题我一般按影响面 × 可复现性排优先级。全量用户都受影响、且百分百复现的先处理只影响个别用户、偶发的先记录再排查。判断影响面最快的方式是看错误率曲线如果是一条陡直的上升线多半是发布引起的如果是缓慢爬升通常是资源耗尽或者数据量增长触发的问题。定位顺序上我从外往里看先确认请求有没有到应用接入层日志再看应用日志有没有异常再看下游依赖是否正常最后看数据库。跳过前面的步骤直接查数据库是新手最容易犯的错因为数据库日志最复杂一旦钻进去就很难出来。5.2 故障速查表现象最可能原因快速验证方式处理动作部分用户登录后立刻掉线多端令牌互相顶掉查同一用户近期签发记录改为令牌并存加设备标识接口偶发超时且无异常日志数据库连接池被占满看连接池活跃数与等待数缩小单次事务范围加超时列表接口返回条数少于预期分页参数未校验边界打印实际查询条件限制单页上限校验偏移量定时任务重复执行多实例未加分布式协调看任务日志时间戳加任务锁或改为单实例执行内存缓慢上涨不回落缓存无上限或上下文未清理抓堆快照看对象数量设置缓存容量与过期时间用户看到别人的数据上下文串号或权限未校验构造越权请求复现补资源归属校验清理上下文5.3 几个只有踩过才知道的坑第一个坑缓存穿透。有些接口会按 ID 查详情如果客户端传来大量不存在的 ID每次都会穿透到数据库。我一般的处理是查不到也缓存一个短期的空标记比如 60 秒这样高频的无效查询就被挡住了。但要注意空标记的时间不能太长否则新数据写入后用户要等很久才能看到。第二个坑事务里的远程调用。在事务方法里调下游接口下游一慢数据库连接就被一直占着事务迟迟不提交很快就拖垮整个连接池。这个问题的隐蔽之处在于本地测试完全正常因为下游很快。解决办法是把远程调用挪到事务外先调完拿到结果再开事务写库。第三个坑日志打太多。为了排查方便有人把整个请求体和响应体都打进日志结果单条日志几 KB一天几个 G。更麻烦的是请求体里往往有敏感信息。我的做法是只打关键字段和耗时需要完整内容时按 traceId 单独开启临时采样。第四个坑时间处理。服务器时区不统一导致存储的时间少了几小时用户看到的刚刚发布变成三小时前。统一用同一个时区存储展示时再按客户端时区转换这个规矩要在项目第一天就定。6. 上线前后容量估算、部署与观测6.1 容量参数怎么算别靠感觉容量估算是很多人的短板其实算法很简单只是需要几个真实数字。假设日活 5 万人均每天发起 60 次接口请求集中在 4 小时高峰期内产生 70% 的流量。那么高峰请求量是 50000 × 60 × 0.7 210 万次高峰时长 14400 秒平均 QPS 约 146。考虑突发乘一个 2.5 的峰值系数得到约 365 QPS 的设计目标。有了 QPS线程数就能算并发数 ≈ QPS × 平均响应时间。假设接口平均 50 毫秒365 × 0.05 ≈ 18 个并发留三倍余量约 55 个工作线程足够。连接池按数据库侧能力反推如果单条 SQL 平均耗时 5 毫秒18 个并发只需要不到 4 个连接同时活跃配 15 到 20 个上限非常充裕配 100 反而会打爆数据库。堆内存按常驻对象估算。如果每个会话对象约 1KB缓存 6 万个约 60MB加上框架本身、连接池、临时对象2GB 堆对 365 QPS 的接口服务是够用的起步值。上线后看垃圾回收日志如果老年代增长平稳、回收后能回落说明设置合理如果回收后仍持续上涨那就是有对象没释放得抓快照分析。估算项计算方式示例结果备注高峰 QPS日活 × 人均请求 × 高峰占比 ÷ 高峰秒数约 146基础值设计 QPS高峰 QPS × 峰值系数 2.5约 365留突发余量并发线程设计 QPS × 平均响应秒数约 18实际配 3 倍连接池上限并发数 ÷ 单 SQL 耗时占比15 至 20别超过数据库上限的 30%初始堆大小常驻对象 临时对象2GB按回收日志调整6.2 部署形态与最小可用观测部署上我倾向先单机多实例把无状态的服务横向铺开会话状态全部外置到缓存。这样扩容就是加实例缩容就是减实例不用改代码。反向代理层负责健康检查和流量分发健康检查接口要真的检查依赖数据库和缓存能否连通不能只返回一个固定字符串否则依赖挂了流量还在往里打。观测这块最小可用的配置是三样结构化日志、关键指标、慢请求记录。日志统一格式带上 traceId、用户标识、接口名、耗时这样按 traceId 一搜就能还原整条链路。关键指标至少要有 QPS、错误率、响应时间分位数、连接池使用率、缓存命中率。慢请求单独记录一份超过 500 毫秒的请求都留下来这是优化最有价值的输入。告警阈值别设太敏感我见过错误率超过 0.1% 就告警的配置结果每天几十条通知最后所有人都把告警静音了真出问题反而没人看。我的经验是分层错误率超过 1% 且持续 5 分钟才推送到人超过 5% 才触发紧急通知资源类指标看趋势不看瞬时值。注意上线前一定要验证一件事——把数据库停掉看接口返回什么。如果返回的是堆栈信息或者内部地址说明异常处理没做干净这些信息不该给到客户端。我在实际接手别人的 Java小程序后端时最先看的三样东西是登录接口有没有幂等、拦截器有没有清理上下文、慢请求有没有记录。这三样齐了项目基本不会出大事故缺哪一样就先补哪一样比急着加新功能有价值得多。