努力
加油

如何让微信小程序与Web应用共享同一套API接口?

这是一个非常经典且高频的后端架构设计问题。很多开发者在初期为了省事,会直接让小程序和 Web 共用同一个 Controller 或 API 路径,但这往往会在后期导致维护灾难、安全性隐患以及跨域问题。

要实现“共享同一套 API 接口”,核心不在于代码层面的复用(虽然可以用),而在于统一网关层(Gateway)和协议适配层。我们需要解决的核心痛点有三个:

  1. 认证体系差异:小程序用 openid/session_key,Web 通常用 JWT/Session/Cookie。
  2. 网络环境差异:小程序有严格的域名白名单且不支持自定义 Header 的复杂 CORS 处理,Web 则完全开放。
  3. 数据结构差异:小程序倾向于扁平化、轻量级响应;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

关键点:

  1. 网关层做路由分发:根据请求来源(Header 中的 User-Agent 或特定 Token 类型)判断是小程序还是 Web。
  2. 统一鉴权中间件:
    • 如果是小程序,调用微信登录接口换取 openid,生成一个内部使用的 Session 或 JWT。
    • 如果是 Web,解析 Cookie 或 Authorization Header 中的 JWT。
    • 最终结果:无论前端是什么,进入后端业务层的都是统一的 UserId 或 UserInfo 对象。
  3. 后端业务层无感知:后端只需要定义一套 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 聚合相同的服务但裁剪字段后返回给小程序。
  • 优点:前后端解耦彻底,各自优化性能。
  • 缺点:增加了运维复杂度,不适合小型项目。

二、 技术落地细节

假设你使用的是 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。你需要建立一个“桥梁”。

步骤:

  1. 小程序侧:

    // 小程序 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); 
        });
      }
    });
  2. 后端侧(关键):
    创建一个统一的 /auth/login 接口,支持多种登录方式:

    • 如果 Body 中有 code -> 调微信服务端 API 换 openid -> 查询用户 -> 签发 JWT。
    • 如果 Body 中有 username/password -> 传统登录 -> 签发 JWT。
    • 输出:无论哪种方式,都返回相同的 { token: "eyJhbG..." }。
  3. 后续请求:
    小程序和 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 或拦截器自动添加。

三、 避坑指南 & 最佳实践

  1. 不要直接在小程序里写业务逻辑:
    有些开发者喜欢在小程序云开发里直接操作数据库,而 Web 走另一套。这会导致数据不一致。务必让小程序也调用后端 API,保持单一数据源。

  2. 图片上传问题:
    小程序有 wx.chooseImage 和 wx.uploadFile,Web 有 <input type="file">。

    • 解决方案:后端提供一个统一的 /upload/file 接口。
    • 小程序端:先获取临时文件路径,再用 wx.uploadFile 发送到该接口。
    • Web 端:直接用 FormData POST 到该接口。
    • 后端统一处理 Multipart/Form-Data,返回统一的 OSS 文件 URL。
  3. 敏感信息脱敏:
    小程序接口暴露在公网,容易被抓包。虽然 HTTPS 是必须的,但对于手机号、XX等敏感字段,建议在网关层或后端服务层进行脱敏处理,或者为小程序提供专门的“脱敏视图”接口。

  4. 灰度发布与限流:
    利用 API 网关的能力,可以对小程序流量和 Web 流量分别设置限流策略。例如,大促期间限制小程序的并发数,但不影响 Web 端的正常访问。

  5. 国内云厂商的特殊性:

    • 腾讯云:如果你用的是云开发(CloudBase),它天然支持小程序和 Web 共用函数,但要注意权限隔离。
    • 阿里云:推荐使用 ARMS + SAE + API 网关组合。API 网关可以很好地处理小程序的签名验证(如果需要)和 JWT 解析。
    • 华为云:CSE(Service Stage Engine)也能实现类似功能,注意配置好 VPC 内的服务发现。

总结

让微信小程序与 Web 应用共享 API 接口的本质是:后端抽象出统一的业务模型,前端通过不同的接入方式(Token 机制)融入这个模型。

行动清单:

  1. 搭建统一的 API 网关。
  2. 实现基于 JWT 的统一认证中心,兼容小程序 Code 登录和 Web 账号密码登录。
  3. 规范所有业务接口的入参和出参格式。
  4. 确保小程序配置的 Request 域名与 Web 访问的域名一致,并处理好 HTTPS。

这样,你的后端团队只需要维护一套代码,前端团队可以根据平台特性选择调用方式,效率最高,维护成本最低。