加载中…

uni 一键登录对接 API 工厂教程

> 适用场景:App / 小程序通过 **uni 一键登录(UniVerify)** 获取本机手机号,在云函数中完成与 API 工厂后台的用户匹配、注册与登录 token 签发。 > > uni 一键登录依赖 DCloud 云服务,真实手机号必须在**云函数(服务端)**换取;拿到手机号后,再由云函数调用 API 工厂接口完成登录闭环。 > ## 一、前置准备 1. **开通 uni 一键登录**:在 DCloud 开发者后台开通 UniVerify 一键登录服务,配置好 App 信息与运营商认证。官方文档:[https://uniapp.dcloud.net.cn/univerify.html](https://uniapp.dcloud.net.cn/univerify.html) 2. **获取 API 工厂免登录调用凭证**:三个后台接口均使用 **Basic Authentication** 免登录调用,凭证在 API 工厂后台获取,配置方式见官方说明:[https://www.yuque.com/apifm/doc/guzeid](https://www.yuque.com/apifm/doc/guzeid) 3. **准备云函数环境**:在 uniCloud 中部署一个云函数(本教程示例为 Node.js),用于换取手机号并调用 API 工厂接口。 ## 二、整体流程 ![](./uni-apifm-login-flow.png)![](https://dcdn.it120.cc/yuque/0/2026/png/572726/1794536051097-36fde7dd-a8a5-4a6e-b8a5-5c5cb0b80f1a.png) 流程说明: 1. 前端点击「本机号码一键登录」,调用 uni 一键登录能力,向运营商请求授权并拿到手机号授权 code; 2. 云函数使用 code 调用 DCloud 云端接口,换取真实手机号 `mobile`; 3. 云函数携带 Basic Authentication 调用 API 工厂,按手机号查询用户; 4. 用户已存在:直接取出用户编号;用户不存在:调用创建用户接口写入资料,得到新用户编号; 5. 凭用户编号调用接口换取登录 token; 6. 云函数将 token 与用户信息返回前端,前端保存 token,后续业务请求携带 token,登录完成。 ## 三、前端:发起一键登录 前端只负责拉起一键登录、拿到授权 code 后提交给云函数,**不在前端直接处理手机号**。具体 API 调用方式以 uni 官方文档为准:[https://uniapp.dcloud.net.cn/univerify.html](https://uniapp.dcloud.net.cn/univerify.html) 示意代码(前端页面): ```javascript // 1. 拉起 uni 一键登录,拿到授权 code(具体参数以官方文档为准) uni.getProvider({ service: 'oauth', success: (res) => { uni.login({ provider: res.provider, success: (loginRes) => { // loginRes 中包含一键登录授权 code,提交给云函数换取手机号 uniCloud.callFunction({ name: 'apifmLogin', data: { code: loginRes.code }, success: (callRes) => { if (callRes.result.code === 0) { // 保存 token,登录成功 uni.setStorageSync('token', callRes.result.data.token) uni.setStorageSync('userInfo', callRes.result.data.user) } else { uni.showToast({ title: callRes.result.msg, icon: 'none' }) } } }) } }) } }) ``` ## 四、云函数:对接 API 工厂三个接口 > 以下三个接口统一通过请求头 `Authorization: Basic <凭证>` 免登录调用,凭证获取方式:[https://www.yuque.com/apifm/doc/guzeid](https://www.yuque.com/apifm/doc/guzeid) > > 接口返回结构统一为 `{ code, msg, data }`,`code: 0` 表示成功。 > ### 4.1 按手机号查询用户 + 接口地址:`https://common.apifm.com/apifmUser/userBase/info/mobile` + 参数: | 参数名 | 介绍 | | --- | --- | | mobile | 手机号码 | 返回 `data` 中包含用户信息(含用户编号 `id`);查无此用户时按返回 `code` / `data` 为空判断,走创建用户分支。 ### 4.2 创建新用户 + 接口地址:`https://common.apifm.com/apifmUser/userBase/addNewUser` + 参数: | 参数名 | 介绍 | | --- | --- | | shopId | 所属门店ID | | openid | 用户对应微信的openid | | unionid | 用户对应微信的unionid | | source | 来源:0 小程序、1 手机注册、2 公众号、3 支付宝小程序 | | mobile | 手机号码 | | email | 电子邮箱地址,unbind 为解除手机号码绑定 | | username | 用户名 | | pwd | 登录密码 | | nick | 昵称 | | nfcCardId | nfc 卡序列号 | | levelId | 会员等级,传 0 为取消用户等级 | | isSeller | 是否设置为分销商,true / false | | sellerLevelId | 分销商等级ID | | province | 省份名称 | | city | 城市名称 | | avatarUrl | 用户头像 Url | | wx | 微信号 | | departmentId | 所属部门ID | | remark | 备注 | | extJsonStr | 用户的扩展属性的 JSON 格式 | | tags | 用户标签,多个标签用英文逗号分割 | | grade | 年级(适合做校园类小程序) | | xiaoqu | 所在校区 | | serviceCities | 可服务的城市ID,多个用英文逗号分隔 | > 一键登录场景下,`source` 传 `1`(手机注册),`mobile` 传云函数换取到的手机号;其余参数按业务需要补充,无对应资料可不传。 > ### 4.3 获取用户登录 token + 接口地址:`https://common.apifm.com/apifmUser/userBase/token` + 参数: | 参数名 | 介绍 | | --- | --- | | id | 用户编号 | 返回 `data` 中包含该用户的登录 token,前端后续业务请求携带此 token 即可。 ## 五、完整云函数示例(Node.js / uniCloud) ```javascript // uniCloud 云函数:apifmLogin // 依赖:axios(在云函数目录 npm install axios) const axios = require('axios') // ===== 配置项 ===== const APIFM_BASE = 'https://common.apifm.com' // Basic Authentication 凭证(后台获取,切勿泄露到前端) // 格式:商户号:秘钥,再做 Base64 编码 const BASIC_AUTH = 'Basic ' + Buffer.from('商户号:秘钥').toString('base64') const http = axios.create({ baseURL: APIFM_BASE, headers: { Authorization: BASIC_AUTH } }) exports.main = async (event) => { try { // 1. 用前端传来的 code 调用 DCloud 云端接口换取手机号 // 具体换号接口以 uni 一键登录云端文档为准 const mobile = await getMobileFromDCloud(event.code) // 2. 按手机号查询 API 工厂用户 const queryRes = await http.get('/apifmUser/userBase/info/mobile', { params: { mobile } }) let userId if (queryRes.data.code === 0 && queryRes.data.data && queryRes.data.data.id) { // 用户已存在 userId = queryRes.data.data.id } else { // 3. 用户不存在,创建新用户 const addRes = await http.post('/apifmUser/userBase/addNewUser', { source: 1, // 1 手机注册 mobile: mobile, nick: '用户' + mobile.slice(-4) // 其余参数按业务补充:shopId、avatarUrl、province、city 等 }) if (addRes.data.code !== 0) { return { code: addRes.data.code, msg: addRes.data.msg, data: null } } // 新用户编号(以创建接口返回结构为准) userId = addRes.data.data.id } // 4. 凭用户编号换取登录 token const tokenRes = await http.get('/apifmUser/userBase/token', { params: { id: userId } }) if (tokenRes.data.code !== 0) { return { code: tokenRes.data.code, msg: tokenRes.data.msg, data: null } } return { code: 0, msg: 'success', data: { token: tokenRes.data.data.token, user: queryRes.data.data || addRes.data.data } } } catch (err) { return { code: -1, msg: err.message || '登录失败', data: null } } } // 占位:调用 DCloud 云端接口,用授权 code 换取真实手机号 // 具体接口地址与参数以 uni 一键登录官方云端文档为准 async function getMobileFromDCloud(code) { // TODO: 按 DCloud 文档完成云端校验与换号 return '' } ``` ## 六、注意事项 1. **手机号只能在服务端换取**:一键登录的授权 code 必须在云函数中完成云端校验,真实手机号不经过前端明文传输。 2. **凭证保密**:Basic Authentication 凭证只保存在云函数 / 服务端配置中,禁止写入前端代码、小程序包或公开仓库。 3. **用户去重以手机号为准**:同一手机号重复一键登录时,应命中已有用户,避免重复注册;如需绑定微信 openid / unionid,可在创建或更新用户时一并传入。 4. **返回判断**:所有接口以 `code === 0` 为成功;非 0 时把 `msg` 透传给前端提示,并记录服务端日志便于排查。 5. **token 有效期**:前端保存的 token 过期后,重新走一键登录流程换取新 token 即可。