以下整理了一份生产环境微信小程序必备 API 及对应数据库表设计，覆盖登录鉴权、版本更新、性能监控、错误处理、容灾等核心模块。前端 API 均指微信原生能力，后端 API 为开发者服务器需要实现的接口。
一、登录与用户身份
1.1 前端 API
| API | 说明 |
|---|
wx.login() | 获取临时登录凭证 code，用于换取 openid |
wx.checkSession() | 检查当前登录态是否过期 |
<button open-type="getPhoneNumber"> | 获取用户手机号（需加密数据解密） |
wx.getUserProfile() | 获取用户头像昵称（必须用户手动点击允许） |
1.2 后端 API
| 方法 | 路径 | 说明 |
|---|
| POST | /api/user/login | 接收 code，调用微信 code2Session 换取 openid，生成自定义 token 返回 |
| POST | /api/user/update-profile | 接收加密的手机号/用户信息，解密后更新用户资料 |
| GET | /api/user/info | 通过 token 获取当前用户信息 |
1.3 数据库表
用户表 users
| 字段 | 类型 | 说明 |
|---|
| id | bigint(20) | 主键，自增 |
| openid | varchar(64) | 微信 openid，唯一索引 |
| unionid | varchar(64) | 微信 unionid（可选） |
| nickname | varchar(64) | 用户昵称 |
| avatar_url | varchar(512) | 头像地址 |
| phone | varchar(20) | 手机号（加密存储） |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
登录凭证表 user_tokens
| 字段 | 类型 | 说明 |
|---|
| id | bigint(20) | 主键，自增 |
| user_id | bigint(20) | 关联 users.id |
| token | varchar(256) | jwt token |
| platform | tinyint(2) | 登录平台（微信小程序=1） |
| expire_at | datetime | 过期时间 |
| created_at | datetime | 创建时间 |
可选用 JWT 无状态方案，无需存储 token，但生产环境建议保留该表以支持强制下线、多设备管理。
二、版本更新管理
2.1 前端 API
| API | 说明 |
|---|
wx.getUpdateManager() | 管理小程序版本更新，提示用户重启 |
2.2 后端 API（可选）
| 方法 | 路径 | 说明 |
|---|
| GET | /api/config/version | 返回最低要求版本号，前端可在启动时检查，若当前版本过低可引导升级或限制使用 |
2.3 数据库表
应用版本表 app_versions
| 字段 | 类型 | 说明 |
|---|
| id | int(11) | 主键，自增 |
| version | varchar(20) | 版本号，如 "3.2.1" |
| min_version | varchar(20) | 最低兼容版本 |
| update_desc | varchar(512) | 更新描述 |
| force_update | tinyint(1) | 是否强制更新 1=是 0=否 |
| platform | varchar(20) | 平台，如 "weapp" |
| created_at | datetime | 创建时间 |
即使有小程序自带的更新机制，此表仍可用于 首次冷启动时的版本拦截 或 后端对低版本用户做接口限制。
三、网络状态监听
3.1 前端 API（纯客户端，无后端接口）
| API | 说明 |
|---|
wx.onNetworkStatusChange() | 监听网络切换（Wi-Fi / 4G / 无网络），触发界面提示或重连 |
wx.onAppHide() | 应用切到后台，可手动关闭连接 |
wx.onAppShow() | 应用切回前台，可重新校验登录态 |
无需对应数据库表，但前端需在封装请求时根据网络状态做自动重试。
四、性能监控与错误上报
4.1 前端 API
| API | 说明 |
|---|
wx.getPerformance() | 获取性能对象 |
wx.reportPerformance(id, cost) | 上报自定义性能指标（id 需先在后台配置） |
wx.onError() | 监听脚本错误 |
wx.onUnhandledRejection() | 监听未处理的 Promise 拒绝 |
wx.onPageNotFound() | 页面不存在监听 |
wx.onLazyLoadError() | 异步组件加载失败监听 |
4.2 后端 API
| 方法 | 路径 | 说明 |
|---|
| POST | /api/log/error | 接收客户端 JS 异常、网络请求错误等 |
| POST | /api/log/performance | 接收页面加载耗时、接口耗时等性能数据 |
4.3 数据库表
错误日志表 error_logs
| 字段 | 类型 | 说明 |
|---|
| id | bigint(20) | 主键，自增 |
| user_id | bigint(20) | 关联用户（可空） |
| page | varchar(256) | 错误发生的页面路径 |
| error_type | varchar(64) | 错误类型（JS错误、接口错误、资源错误） |
| message | text | 错误消息 |
| stack | text | 错误堆栈 |
| device_info | json | 设备信息（型号、系统、微信版本等） |
| app_version | varchar(20) | 小程序版本号 |
| occur_at | datetime | 发生时间 |
| created_at | datetime | 上报时间 |
性能日志表 performance_logs
| 字段 | 类型 | 说明 |
|---|
| id | bigint(20) | 主键，自增 |
| user_id | bigint(20) | 关联用户（可空） |
| page | varchar(256) | 页面路径 |
| metric | varchar(64) | 指标名（如 page_load_time） |
| value | int(11) | 耗时（毫秒） |
| extra | json | 扩展信息（网络类型等） |
| app_version | varchar(20) | 版本号 |
| created_at | datetime | 上报时间 |
这两个表是生产环境问题排查的基础，必须建好并定期归档。
五、通用配置与容灾
5.1 后端 API
| 方法 | 路径 | 说明 |
|---|
| GET | /api/config/all | 拉取客户端需要的全局配置（如客服电话、公告、功能开关） |
5.2 数据库表
配置表 configs
| 字段 | 类型 | 说明 |
|---|
| id | int(11) | 主键，自增 |
| key | varchar(64) | 配置键，唯一 |
| value | text | 配置值（支持 JSON） |
| description | varchar(256) | 描述 |
| updated_at | datetime | 更新时间 |
典型配置项：
maintenance_mode：是否开启维护模式force_update_version：强制更新最低版本contact_phone：客服电话home_banner：首页轮播图数据
六、数据安全补充
6.1 前端策略
- 所有网络请求必须使用
https / wss - 敏感数据存储时使用
wx.setStorageSync 配合加密（或使用 wx.setStorage 的安全标记 encrypted）
6.2 后端策略
appsecret 严禁出现在前端代码，只能在服务端调用微信接口- 生成的
session_key 只能保存在服务端，不可返回给前端 - 所有接口做好参数校验和限流
6.3 对应数据库表（可选）
密钥管理表 app_secrets（服务端内部）
| 字段 | 类型 | 说明 |
|---|
| id | int(11) | 主键 |
| app_id | varchar(32) | 小程序 appid |
| secret | varchar(128) | appsecret（加密存储） |
| token_expire | int(11) | 自定义登录态有效时间（秒） |
| created_at | datetime | 创建时间 |
七、完整 API 清单总结
| 优先级 | 模块 | 前端 API | 后端 API | 数据库表 |
|---|
| 🔴 最高 | 登录鉴权 | wx.login wx.checkSession getPhoneNumber | /api/user/login /api/user/info | users user_tokens |
| 🔴 最高 | 错误监控 | wx.onError onUnhandledRejection /onPageNotFound | /api/log/error | error_logs |
| 🟡 高 | 版本更新 | wx.getUpdateManager | /api/config/version | app_versions |
| 🟡 高 | 性能上报 | wx.reportPerformance getPerformance | /api/log/performance | performance_logs |
| 🟡 高 | 网络监听 | onNetworkStatusChange onAppHide/Show | — | — |
| 🟢 中 | 全局配置 | — | /api/config/all | configs |
| 🟢 中 | 数据安全 | — | — | app_secrets |
以上内容足以支撑一个小程序的生产环境稳定运行。建议在 app.js 启动时统一完成如下初始化工作：
- 拉取全局配置 + 版本检查
- 校验登录态（有则续期，无则重新登录）
- 注册全局错误监听
- 注册网络变化监听
- 启动更新管理器
这样可确保小程序从启动到使用的全链路具备高可用性。
评论