这是一个非常经典且高频的后端架构设计问题。很多开发者在初期为了省事,会直接让小程序和 Web 共用同一个 Controller 或 API 路径,但这往往会在后期导致维护灾难、安全性隐患以及跨域问题。
要实现“共享同一套 API 接口”,核心不在于代码层面的复用(虽然可以用),而在于统一网关层(Gateway)和协议适配层。我们需要解决的核心痛点有三个:
- 认证体系差异:小程序用
openid/session_key,Web 通常用JWT/Session/Cookie。 - 网络环境差异:小程序有严格的域名白名单且不支持自定义 Header 的复杂 CORS 处理,Web 则完全开放。
- 数据结构差异:小程序倾向于扁平化、轻量级响应;Web 可能需要更丰富的元数据或分页结构。
下面我从架构设计和具体实现两个层面,拆解如何优雅地实现这一目标。
一、 架构思路:BFF 模式 vs 统一 API 网关
方案 A:统一 API 网关 + 协议转换(推荐)
这是目前主流云厂商(如阿里云、腾讯云、AWS)推荐的架构。你的后端业务逻辑只关注“数据”,不关注“客户端是谁”。
架构图示:
graph LR
Client[微信小程序] --> Gateway[API 网关]
Client[Web App] --> Gateway
Gateway --> AuthMiddleware[统一鉴权中间件]
AuthMiddleware --> BusinessLogic[后端业务服务]
subgraph "API 网关层"
Router[路由分发]
Adapter[协议适配器]
end
Gateway --> Router
Router --> Adapter
Adapter --> BusinessLogic
关键点:
- 网关层做路由分发:根据请求来源(Header 中的
User-Agent或特定 Token 类型)判断是小程序还是 Web。 - 统一鉴权中间件:
- 如果是小程序,调用微信登录接口换取
openid,生成一个内部使用的 Session 或 JWT。 - 如果是 Web,解析 Cookie 或 Authorization Header 中的 JWT。
- 最终结果:无论前端是什么,进入后端业务层的都是统一的
UserId或UserInfo对象。
- 如果是小程序,调用微信登录接口换取
- 后端业务层无感知:后端只需要定义一套 RESTful 接口,例如
GET /api/user/profile,它不知道也不关心调用者是小程序还是浏览器。
方案 B:BFF (Backend for Frontend) 模式
如果你的小程序和 Web 的数据展示逻辑差异极大(比如小程序需要极简字段,Web 需要完整详情),可以使用 BFF 层。
- 原理:在后端和业务逻辑之间加一层 Node.js 或 Java/Spring Cloud Gateway 编写的 BFF 服务。
- 做法:
- Web 端请求
/bff/web/user/info,BFF 聚合多个微服务接口返回给 Web。 - 小程序请求
/bff/mp/user/info,BFF 聚合相同的服务但裁剪字段后返回给小程序。
- Web 端请求
- 优点:前后端解耦彻底,各自优化性能。
- 缺点:增加了运维复杂度,不适合小型项目。
二、 技术落地细节
假设你使用的是 Spring Boot / Node.js / Go 等常见后端框架,以下是具体操作步骤:
1. 统一入口与路由前缀
不要混用 URL 路径!建议采用版本化管理:
/api/v1/common/... # 公共接口,小程序和 Web 共用
/api/v1/web/... # Web 专属接口(可选,如果逻辑差异大)
/api/v1/mp/... # 小程序专属接口(可选)
最佳实践:尽量将业务逻辑收敛到 /api/v1/common/ 下,通过 Query Parameter 或 Header 区分场景。
2. 认证体系的融合(最难点)
小程序没有 Cookie,也没有标准的 HTTP Basic Auth。你需要建立一个“桥梁”。
步骤:
-
小程序侧:
// 小程序 wx.login() wx.login({ success: res => { // 将 code 发给后端 fetch('/api/auth/login', { method: 'POST', body: JSON.stringify({ code: res.code }) }).then(res => res.json()).then(data => { // 后端返回一个通用的 JWT Token localStorage.setItem('token', data.token); }); } }); -
后端侧(关键):
创建一个统一的/auth/login接口,支持多种登录方式:- 如果 Body 中有
code-> 调微信服务端 API 换openid-> 查询用户 -> 签发 JWT。 - 如果 Body 中有
username/password-> 传统登录 -> 签发 JWT。 - 输出:无论哪种方式,都返回相同的
{ token: "eyJhbG..." }。
- 如果 Body 中有
-
后续请求:
小程序和 Web 在后续所有请求中,都在 Header 中携带Authorization: Bearer <token>。后端只需验证一次 JWT,即可统一身份。
注意:微信小程序不允许设置自定义 Header(除了 Content-Type 等少数几个)。因此,必须使用 URL 参数传递 Token 或者依赖小程序自动携带 Cookie(如果后端部署在小程序配置的安全域名内且开启了 Set-Cookie 支持,但体验较差)。
更稳妥的做法:小程序登录后,将 JWT 存储在
wx.setStorageSync中,每次请求通过 URL Query 参数?token=xxx发送。后端网关层从 Query 中提取 Token 进行校验。
3. 跨域与 CROS 处理
- Web 应用:正常配置 Nginx 或后端 CORS Filter,允许
Access-Control-Allow-Origin: *或指定域名。 - 微信小程序:
- 不需要手动处理 CORS,因为小程序的请求是由微信客户端发出的,不受浏览器同源策略限制。
- 但是:必须在微信公众平台后台配置“服务器域名”(Request 合法域名)。
- 重点:确保你的 API 域名同时满足小程序的白名单要求和 Web 的跨域要求。通常这意味着你要用一个 CDN 或统一的 API 域名。
4. 响应格式标准化
为了避免小程序和 Web 对同一接口返回不同结构导致前端混乱,建议定义统一的响应信封(Envelope):
{
"code": 200,
"message": "success",
"data": { ... },
"traceId": "abc-123"
}
- 小程序:可能只关心
data里的内容。 - Web:可能关心
traceId用于日志追踪。 - 后端:统一封装这个结构,通过 AOP 或拦截器自动添加。
三、 避坑指南 & 最佳实践
-
不要直接在小程序里写业务逻辑:
有些开发者喜欢在小程序云开发里直接操作数据库,而 Web 走另一套。这会导致数据不一致。务必让小程序也调用后端 API,保持单一数据源。 -
图片上传问题:
小程序有wx.chooseImage和wx.uploadFile,Web 有<input type="file">。- 解决方案:后端提供一个统一的
/upload/file接口。 - 小程序端:先获取临时文件路径,再用
wx.uploadFile发送到该接口。 - Web 端:直接用 FormData POST 到该接口。
- 后端统一处理 Multipart/Form-Data,返回统一的 OSS 文件 URL。
- 解决方案:后端提供一个统一的
-
敏感信息脱敏:
小程序接口暴露在公网,容易被抓包。虽然 HTTPS 是必须的,但对于手机号、XX等敏感字段,建议在网关层或后端服务层进行脱敏处理,或者为小程序提供专门的“脱敏视图”接口。 -
灰度发布与限流:
利用 API 网关的能力,可以对小程序流量和 Web 流量分别设置限流策略。例如,大促期间限制小程序的并发数,但不影响 Web 端的正常访问。 -
国内云厂商的特殊性:
- 腾讯云:如果你用的是云开发(CloudBase),它天然支持小程序和 Web 共用函数,但要注意权限隔离。
- 阿里云:推荐使用 ARMS + SAE + API 网关组合。API 网关可以很好地处理小程序的签名验证(如果需要)和 JWT 解析。
- 华为云:CSE(Service Stage Engine)也能实现类似功能,注意配置好 VPC 内的服务发现。
总结
让微信小程序与 Web 应用共享 API 接口的本质是:后端抽象出统一的业务模型,前端通过不同的接入方式(Token 机制)融入这个模型。
行动清单:
- 搭建统一的 API 网关。
- 实现基于 JWT 的统一认证中心,兼容小程序 Code 登录和 Web 账号密码登录。
- 规范所有业务接口的入参和出参格式。
- 确保小程序配置的 Request 域名与 Web 访问的域名一致,并处理好 HTTPS。
这样,你的后端团队只需要维护一套代码,前端团队可以根据平台特性选择调用方式,效率最高,维护成本最低。
云技术博客