一、前言
紫微斗数整套测算系统需要同时支撑 H5 页面、微信小程序两端访问。如果给 H5 和小程序分开写两套接口，不仅重复开发工作量大，后续改排盘算法、更新解读规则、调整限流逻辑时，两边都要同步修改，很容易出现接口返回不一致、BUG 不同步的问题。
统一接口的目标，就是后端只维护一套服务，通过参数区分客户端来源，差异化处理权限、登录、交互提示，保证排盘、四化计算、规则解读这些核心逻辑完全复用。本文结合项目落地经验，分享这套多端统一接口的设计思路、参数规范、适配处理以及踩过的坑。
二、多端差异梳理
H5 和小程序核心业务逻辑是一样的，都需要提交生辰参数、获取排盘结果、查询历史命盘、查看解读内容。真正的差异集中在周边能力上。
登录体系不一样，小程序依赖微信授权登录，拿到 code 换取用户信息；H5 可以支持手机号登录、微信网页授权。图片、分享能力也有区别，小程序有原生分享 API，H5 分享依赖网页方案。另外两端的文件上传、埋点上报、弹窗提示样式不同，部分接口返回字段需要做适配。
核心计算逻辑，也就是农历换算、星曜排布、四化计算、规则引擎解读，完全不需要区分端，这部分是统一接口复用的基础。
三、接口整体设计原则
所有接口分为两层，核心业务层和端适配层。核心业务层不感知客户端是 H5 还是小程序，只负责接收标准入参，执行排盘、查询、存储等计算，返回标准命盘数据。端适配层在网关或者接口入口处，根据端标识做裁剪、转换、权限校验，不改动核心计算逻辑。
约定统一的入参出参规范，采用 JSON 格式，错误码体系全局统一。增加一个固定的客户端标识参数，用来标记是 h5 还是 mini_program，后端根据这个参数做差异化分支，不会污染主流程。
接口粒度尽量按业务划分，不要按页面划分。比如排盘接口、历史命盘查询接口、保存命盘接口、获取星曜科普接口，两端共用同一个地址，避免接口泛滥。
四、入参与返回适配策略
入参里面，生辰、性别、流派、时区这些业务参数结构完全一致，只有登录相关参数不一样。小程序传 code，H5 传 token 或者手机号验证码信息，后端单独处理登录逻辑，登录成功之后，统一生成内部用户 ID，后续所有业务接口都基于这个用户 ID 操作。
返回数据分为公共字段和可选扩展字段。命盘、宫位、星曜、四化这些核心数据原样返回，两端共用。针对端特有能力的字段，用扩展字段包裹，小程序识别小程序扩展字段，H5 直接忽略，不会造成前端解析报错。
字段尽量不要随意增减，新增内容放到扩展对象里面，保证老版本前端兼容，减少升级成本。
五、核心代码示例
// 统一排盘入口，通过clientType区分端 public ResultDTO getPanResult(PanQueryDTO query) { PanResultDTO panResult = panCoreService.calcPan(query); // 根据客户端类型附加端专属扩展信息 PanExtDTO ext = extService.buildExt(query.getClientType(), panResult.getId()); panResult.setExt(ext); return ResultDTO.success(panResult); }
// 登录分发逻辑，统一返回内部用户凭证 public ResultDTO login(LoginDTO loginDTO) { if("mini_program".equals(loginDTO.getClientType())){ return miniLoginService.doLogin(loginDTO.getCode()); }else{ return h5LoginService.doLogin(loginDTO); } }
六、权限与安全处理
小程序有域名校验、业务域名限制，H5 有跨域问题，这部分在网关层统一处理。网关配置跨域规则，同时针对小程序来源请求做来源校验，防止伪造请求。
限流策略可以结合端标识微调，小程序端一般用户更稳定，阈值可以适当放宽；H5 容易被爬虫批量访问，限流规则收紧一点。同时敏感生辰数据脱敏逻辑统一，不管哪个端返回，都按照同样脱敏规则处理，保证数据安全合规。
七、开发踩坑点
第一个坑，前端直接写两套不一样的入参结构，后端被迫写大量 if 判断，接口慢慢变得臃肿。提前约定好参数规范，只把登录、分享这类差异化内容放到扩展区。 第二个坑，错误提示文案没有适配，小程序弹窗提示和 H5 提示风格不一样，全部写死一套文案，体验割裂。可以在配置里按端维护提示文案。 第三个坑，缓存 key 没有带上端标识，H5 和小程序缓存混用，扩展信息错乱。缓存 key 拼接 clientType，隔离两端扩展数据。 第四个坑，调试不方便，开发阶段在日志里打印端标识，方便快速定位是哪一端传来的请求。
八、版本兼容管理
多端前端迭代节奏经常不一样，小程序审核慢，H5 可以随时发布。接口要做好版本管理，在请求头携带版本号，老版本前端继续使用旧返回逻辑，新版本启用新字段。不强制两端同步升级，避免小程序审核卡住整体项目进度。
九、总结
这套统一接口方案的核心就是业务逻辑统一，端侧差异隔离。核心排盘、解读、存储逻辑一份代码维护，差异只在登录、分享、扩展信息、安全校验这些外围环节处理。
好处很明显，后续算法迭代、规则更新，只改一处后端代码，不用重复开发，减少不一致 BUG。后续如果再新增 APP、其他渠道，只需要新增适配分支，核心服务不用改动。
十、互动
如果你做多端测算工具，在小程序授权、H5 网页登录、跨域和缓存隔离方面遇到问题，可以一起交流适配方案。
