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 工厂接口。
## 二、整体流程

流程说明:
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 即可。