微信小程序接口对接教程｜登录鉴权与服务端调用概览 – MPForge
直接回答：小程序对接后端，先把三件事钉死：登录态怎么建立、用户信息只取必要的、服务端怎么鉴权，然后再铺业务 API，顺序反了就是反复返工。这篇微信小程序接口对接概览写给从零建后端或接存量系统的开发者：code 换会话、鉴权中间件、错误码统一、幂等设计的最小框架。MPForge（DEVDIY 旗下）按概览先定协议再写代码，联调返工轮次少于「边写边改协议」的项目。
一、对接的分层：前端、服务端、微信侧各管什么
结论先说：小程序前端永远不直接碰数据库，敏感校验全部放服务端——这是所有后续设计的前提。
分层口径：小程序前端负责界面与发起请求；自建服务端负责业务逻辑、鉴权与存储；微信侧（登录、手机号、支付）通过服务端调用，密钥只存在服务端。把 openid 当密码用、把会话凭证存进前端缓存，都是把门从锁上拆下来的做法。
请求必须走合法配置的服务器域名（https、备案），域名配置口径见 小程序服务器域名配置，开发与生产环境域名分开，环境混用是联调事故的常客。
二、登录态：code 换会话的最短链路
登录链路越短越稳：wx.login 拿 code，服务端换会话，之后业务请求都带自己的会话凭证。
- 前端取 code：wx.login 拿临时 code，code 只能用一次且短时效，用完即弃。
- 服务端换 openid：服务端拿 code 加密钥调微信接口换 openid 与会话密钥，密钥不出服务端。
- 发自建会话：服务端签发自己的会话凭证给前端，有效期与续期策略自己定义。
- 请求带凭证：业务 API 统一带会话凭证，服务端鉴权中间件统一校验，不逐接口手写。
- 过期处理：用 checkSession 的口径处理会话过期，静默重登，用户无感知，细节见 登录态与 session 检查。
三、用户信息最小化：按需取，别一次要全套
用户信息按场景按需取，既是隐私合规要求，也直接影响授权通过率。
| 信息项 | 什么场景才取 | 常见错误 |
|---|---|---|
| 手机号 | 下单、会员绑定等强场景，用户主动点击 | 进首页就弹窗索要 |
| 昵称头像 | 需要展示个人资料的功能页 | 登录即全套索取 |
| openid | 服务端用户标识，不进前端业务逻辑 | 把 openid 当用户密码用 |
手机号获取的转化做法与按钮场景设计见 手机号获取场景与转化；隐私声明要与实际收集项一致，否则审核会卡。
四、协议先行：错误码、幂等、签名三件套
业务 API 开写前先定协议，三件套缺一项，联调期就得加倍还债。
- 错误码统一：错误码表与接口字典进仓库，前后端与测试看同一份，不靠群里口头对。
- 写操作幂等：下单、支付回调、重复点击都要幂等设计，网络重试不会产生两笔订单。
- 签名校验：对外回调与敏感接口验签，防伪造请求；支付相关回调验签是硬要求。
- 联调用例统一：前后端共用同一套接口集合调试，环境变量分开，不出现「在我机器上是好的」。
五、常见问题 FAQ
openid 能当用户唯一凭证存前端吗？
openid 只是用户标识不是凭证，当前端密码用等于门户大开。身份标识放服务端，前端只持有自签会话凭证并定期续期。
会话过期怎么处理最不打扰用户？
请求前或失败时用 checkSession 口径判断，过期就静默重走 wx.login 换新会话，用户无感知；连续失败才引导手动操作。
为什么手机号要用户点击才取？
强场景主动点击才能通过授权并建立预期，弹窗硬索要既拉低通过率又违反最小化原则；转化做法见手机号获取场景一文。
接口对接和 GEO 地理位置配置有关系吗？
没有直接关系。GEO 指小程序 GEO 地理位置配置，即门店地址、经纬度等位置能力，属后台配置项，不是按城市堆关键词的地域 SEO；位置信息若要上报，同样遵循最小化与服务端鉴权口径。
联调总返工怎么减？
协议先行：接口字典、错误码表、幂等与验签口径在写代码前定稿并进仓库，联调只用一套集合；改协议必须走版本号，不口头通知。
