家政平台多端适配改造:基于源码扩展H5、技师APP端方案
一、改造背景与业务目标
多数家政平台初始版本只落地微信小程序,随着业务扩张,需要面向用户开放H5网页访问渠道、给一线技师提供独立APP接单工具。直接重构一套后端会带来大量重复开发、数据不一致的问题。本文基于现有SpringBoot+UniApp家政源码,通过后端接口分层、前端条件编译的方式扩展H5与技师APP,复用工单、派单、结算、评价等核心业务逻辑,实现一套服务支撑多终端访问,同时隔离不同终端的权限与能力差异。
改造核心目标:原有小程序业务不受影响;H5端支持浏览器访问、公众号登录;技师APP具备后台定位打卡、离线消息缓存、推送提醒能力,多端订单状态实时同步。
二、整体架构改造思路
后端保持原有业务模型不变,新增终端适配器层,采用策略模式处理不同终端的登录、支付、推送差异;前端基于UniApp一套工程,通过条件编译,分别编译输出小程序、H5、技师APP包。
- 后端:SpringBoot + MyBatis-Plus + Redis + WebSocket
- 前端:UniApp,统一业务组件,平台独有API做隔离
- 存储:MySQL主业务库、Redis缓存位置、令牌、在线状态
- 通信:WebSocket同步工单变更,APP使用厂商推送通道兜底离线消息
整体遵循业务逻辑收敛、终端差异外移的原则,核心工单、结算代码不改动,只在接入层适配各平台特性。
三、后端多端鉴权与接口适配实现
新增终端类型标识,在请求头携带terminal字段区分 MP / H5 / APP,统一鉴权拦截器,再通过策略模式分发登录逻辑。
// 终端枚举
public enum TerminalType {
MP, H5, TECH_APP
}
// 登录策略接口
public interface LoginStrategy {
LoginResp login(LoginDTO dto);
}
// 策略工厂,根据终端类型匹配对应登录实现
@Service
public class LoginStrategyFactory {
@Autowired
private Map<String, LoginStrategy> strategyMap;
public LoginStrategy getStrategy(TerminalType type) {
return strategyMap.get(type.name());
}
}
H5端对接公众号OAuth2登录,技师APP使用账号密码+短信验证码登录,小程序保留微信授权登录。接口统一返回结构,但是针对技师APP增加打卡、接单推送、离线消息接口;H5端屏蔽原生小程序能力接口,同时配置CORS跨域,适配浏览器访问。
权限层面增加角色+终端双重校验:技师账号仅允许在技师APP登录,禁止在普通用户H5端访问接单接口,防止越权操作。
四、UniApp前端多端兼容改造要点
前端不拆分多个项目,共用一套页面与业务组件,通过#ifdef条件编译处理平台差异化代码:
- 登录模块:
#ifdef MP-WEIXIN走微信授权;#ifdef H5走公众号授权;#ifdef APP-PLUS走账号验证码登录。 - 定位打卡:H5依赖浏览器定位API,APP调用原生定位SDK,增加定位失败降级逻辑。
- 支付模块:H5使用网页支付,APP唤起支付SDK,小程序沿用微信支付。
- 推送消息:APP集成厂商推送,H5仅在页面活跃时使用WebSocket接收消息。
- 样式适配:统一使用rpx单位,单独处理H5滚动、安全区、刘海屏兼容。
打包发布时,分别执行H5发行、APP云打包,生成独立部署包,H5静态资源部署在Nginx站点。
五、工单实时同步与多端状态一致性设计
家政工单是核心数据,用户下单、派单、技师接单、完工,所有终端需要同步状态。系统采用WebSocket长连接作为主通道,APP离线时通过厂商推送下发通知。
在工单状态变更的切面中,广播消息给对应角色的在线终端:用户端、技师端、管理后台。同时Redis缓存工单最新快照,新打开页面优先读取缓存,保证弱网下多端展示一致。
需要注意:技师APP存在后台保活差异,安卓、iOS推送通道不同,不能强依赖长连接,消息需要做幂等处理,避免重复提醒。
六、安全与风控适配调整
不同终端安全策略不一样:
- H5暴露在公网浏览器,增加请求频率限制、验证码防刷,做好CORS白名单;
- 技师APP增加设备绑定,支持设备解绑,同一账号限制同时在线设备数量;
- 令牌体系区分终端,H5令牌有效期短,APP令牌支持续期,敏感操作(提现、结算)二次短信校验;
- 所有终端上传的打卡图片、凭证文件统一校验文件类型、大小,防止恶意文件上传。
七、测试验证方案
分三个阶段验证:
- 单端回归:小程序原有流程全部复测,保证改造不影响存量业务;
- 新端专项测试:H5浏览器多浏览器兼容、跨域、公众号登录;技师APP定位、后台推送、离线接单;
- 多端联动测试:在H5下单、APP技师接单,查看两端工单状态同步是否正常,验证消息推送、订单回调、结算流程。
同时增加弱网、断网场景测试,验证缓存、重试、消息兜底机制。
八、总结
家政平台多端扩展,最稳妥的方案不是重复开发多套后端,而是把业务核心收敛,将平台差异在接入层、前端层隔离。通过策略模式处理H5、APP、小程序的登录与能力差异,UniApp条件编译复用页面组件,配合WebSocket+推送保障工单实时同步,能够低成本完成H5与技师APP的落地。
这套方案的优势是后续迭代工单、结算、评价等业务时,只修改一处核心代码,所有终端同步更新;代价是需要持续维护多端兼容清单,重点关注浏览器跨域、APP推送、定位权限这类平台特有坑点。在业务持续增长后,可以再基于这套统一接口,继续扩展商家端、管理后台等其他终端。