YwxAppThink/docs/api/ywxapp-api-v1.md

YwxApp 标准 App 接口 v1 测试文档

适用对象：App / 小程序 / 第三方客户端联调与测试（Apifox / Postman） 基础路径：/api/v1（建议环境变量 base_url = http://你的域名/api/v1） 最后更新：2026-08-17

---

字段 值 uid 88889464 account testuser password Test@123456 status 1(正常) gid 2(普通会员)

1. 通用约定

1.1 响应结构（统一 JSON）

所有接口均返回以下结构（强制 JSON，不受请求类型影响）：

{
  "code": 0,
  "msg": "success",
  "data": {},
  "timestamp": 1765900000
}

字段	类型	说明
code	int	0=成功；1=业务失败；401=未登录/鉴权失败
msg	string	提示信息
data	object/null	业务数据；登录类接口含 access_token 等
timestamp	int	服务器时间戳（秒）

1.2 业务 code 与 HTTP 状态码

• 业务 code 与 HTTP 状态码解耦：未登录时返回 code=401 且 HTTP 状态也为 401。
• 业务失败时 HTTP 状态保持 200，仅 code 非 0（除 401 外）。

1.3 鉴权（Bearer Token）

• 登录 / 注册成功后，响应 data 内含 access_token、refresh_token、expires_in。
• 需登录接口在请求头携带：

  Authorization: Bearer <access_token>
  

• 跨域：路由已挂载 AllowCrossDomain 中间件，前端联调无 CORS 问题。

1.4 接口清单一览

接口	方法	鉴权	说明
/common/init	GET	否	启动初始化（站点/注册方式/版本）
/common/config	GET	否	站点配置
/common/upload	POST	是	文件上传
/user/register	POST	否	注册
/user/login	POST	否	账号密码登录
/user/loginBySms	POST	否	短信验证码登录（未注册自动注册）
/user/refresh	POST	否(refresh_token)	刷新 access_token
/user/logout	POST	是	退出登录
/user/profile	GET	是	获取会员资料
/user/updateProfile	POST	是	修改资料
/user/changePwd	POST	是	修改密码
/user/resetPwdBySms	POST	否	短信重置密码
/user/resetPwdByEmail	POST	否	邮箱重置密码
/sms/send	POST	否	发送短信验证码
/sms/check	POST	否	校验短信验证码
/ems/send	POST	否	发送邮箱验证码
/ems/check	POST	否	校验邮箱验证码

---

2. 接口详情

2.1 Common

GET /common/init

启动初始化，App 冷启动首屏调用。

• 响应示例：

{ "code": 0, "msg": "success", "data": { "site": {...}, "register_type": "all", "version": "1.0.0" }, "timestamp": 1765900000 }

GET /common/config

站点配置（公开）。

• 响应 data 结构同 init 中的 site 字段。

POST /common/upload

文件上传（需登录），Content-Type: multipart/form-data，字段名 file。

• 成功响应：

{ "code": 0, "msg": "上传成功", "data": { "url": "/storage/uploads/xxx.png", "path": "uploads/xxx.png" }, "timestamp": 1765900000 }

---

2.2 User

POST /user/register

注册账号。

• 请求体（x-www-form-urlencoded）：account(必填), password(必填,≥6位), nickname(可选), mobile(可选), email(可选), captcha(可选, 手机号注册时必填且需先调 /sms/send)
• 成功响应（自动签发 token）：

{
  "code": 0, "msg": "注册成功", "timestamp": 1765900000,
  "data": { "uid": 1, "account": "testuser", "nickname": "测试", "access_token": "...", "refresh_token": "...", "expires_in": 3600, "token_type": "Bearer" },
  "access_token": "...", "access_expired": 3600, "refresh_token": "...", "refresh_expired": 86400
}

说明：token 同时出现在 data 内与响应顶层（供不同客户端习惯取用）。

POST /user/login

账号密码登录。

• 请求体：account(必填), password(必填)
• 响应结构同 register。

POST /user/loginBySms

短信验证码登录；手机号未注册则自动注册。

• 请求体：mobile(必填), captcha(必填)
• 响应结构同 register，自动注册时初始密码为随机值（仅短信登录可用）。

POST /user/refresh

使用 refresh_token 换取新 access_token。

• 请求体：refresh_token(必填)
• 成功响应：

{ "code": 0, "msg": "刷新成功", "data": { "access_token": "...", "refresh_token": "...", "expires_in": 3600, "token_type": "Bearer" }, "timestamp": 1765900000 }

• 失败（refresh_token 无效/过期）：code=401，HTTP 401。

POST /user/logout

退出登录（需登录）。

• 响应：{ "code": 0, "msg": "已登出", "data": [], "timestamp": 1765900000 }

GET /user/profile

获取当前会员资料（需登录，Header 带 Authorization: Bearer <token>）。

• 响应 data 字段（password/delete_at 已隐藏，附加 status_text/last_login）：

{
  "code": 0, "msg": "success",
  "data": { "uid": 1, "account": "testuser", "nickname": "测试", "mobile": "", "email": "", "avatar": "", "status": 1, "status_text": "正常", "last_login": "...", "create_at": 1765900000 },
  "timestamp": 1765900000
}

POST /user/updateProfile

修改资料（需登录）。

• 请求体（均可选）：nickname, mobile, email, avatar
• 响应 data 为更新后的会员数组。

POST /user/changePwd

修改密码（需登录）。

• 请求体：oldpassword(必填), newpassword(必填,≥6位)
• 错误示例：{ "code": 1, "msg": "原密码错误", "timestamp": 1765900000 }

POST /user/resetPwdBySms

短信重置密码（免登录）。

• 请求体：mobile(必填), captcha(必填), newpassword(必填,≥6位)

POST /user/resetPwdByEmail

邮箱重置密码（免登录）。

• 请求体：email(必填), captcha(必填), newpassword(必填,≥6位)

---

2.3 验证码

POST /sms/send

发送短信验证码。

• 请求体：mobile(必填), event(必填, 如 register/login/mobilelogin/resetpwd/changepwd/changemobile)
• 频率限制：同手机号 60 秒内不可重复；同 IP 1 小时上限 5 条。

POST /sms/check

校验短信验证码。

• 请求体：mobile(必填), event(必填), captcha(必填)

POST /ems/send

发送邮箱验证码。请求体：email(必填), event(可选, 默认 register)。

POST /ems/check

校验邮箱验证码。请求体：email(必填), event(可选), captcha(必填)。

---

3. Apifox / Postman 联调步骤

1. 导入集合文件 docs/postman/ywxapp-api-v1.postman_collection.json（Postman 直接导入；Apifox 选择「导入 → Postman 格式」）。
2. 设置环境/变量 base_url 为你的本地域名，例如 http://localhost/api/v1。
3. 先调试公开接口 GET /common/init，确认返回 JSON（非 HTML）即链路通。
4. 调 POST /user/login（或先 register），登录成功后在 Tests 脚本里自动把 access_token 写入变量 token。
5. 之后调 /user/profile 等需登录接口，自动带 Authorization: Bearer {{token}}。
6. 故意不带 token 调 /user/profile，应得 code=401 + HTTP 401。

排错

• 全部 404：清除路由缓存 runtime/route_list.php 后重试（TP 缓存机制）。
• 返回 HTML 而非 JSON：确认路径为小写 /api/v1/...，且域名正确（非后台 admin 域）。
• 401 但 token 有效：检查 token 是否过期，/user/refresh 用 refresh_token 换新；注意 access_token 默认有效期见 expires_in。

---

4. 测试 Checklist（建议用例）

• init / config 公开可访问且返回 JSON
• register 正常注册并拿到 token
• register 重复账号 → code=1 提示「该账号已被注册」
• login 密码错误 → code=1 提示「密码错误」
• login 成功后 profile 返回会员资料
• profile 不带 token → code=401 HTTP 401
• refresh 用 refresh_token 换发新 token 成功
• refresh 用错误 token → code=401
• changePwd 原密码错误 → code=1
• logout 成功 → code=0