llms.txt · xianyan.cc
快速开始 更新于 2026-08-15

APP 接入指南

职责：指引 APP 端对接所有闲言接口（认证 / 数据 / 推送 / 错误处理 / 设备注册 / 后端架构说明）。

本页接口速览（6 个）
GET /health GET /api/app/init GET /api/user_center/index GET /api/feed/list?type=... GET /api/searchall/search?q=... GET /api/fortune/today

APP 端接口开发指南 v9.2.0

版本: v9.2.0 | 更新: 2026-08-15
基础URL: https://tools.wktyl.com
测试账号: apitest_user / 123456
测试验证码: 888888
回执密钥: Xy7kP9mL2qR4wS8v (HMAC-SHA256)
维护: Xianyan 团队

职责：指引 APP 端对接所有闲言接口（认证 / 数据 / 推送 / 错误处理 / 设备注册 / 后端架构说明）。

1. 认证机制

1.1 三种登录方式

# 1) 用户名+密码 → token（最常用）
POST /api/user_security/login
{ "account": "alice", "password": "P@ss" }
→ { code:1, data: { token: "eyJ0eXAi...", user_id: 12345 } }

# 2) OAuth (GitHub / Apple / Google)
→ 见 [API_OAUTH_DOC](./API_OAUTH_DOC.md)

# 3) 手机号+验证码
POST /api/user_security/mobilelogin
{ "mobile": "13800138000", "captcha": "888888" }

1.2 Token 使用

GET /api/user_center/index
Header: token: eyJ0eXAi...

返回响应会带 __token__ Header 和 Set-Cookie: uid=...; token=...。后续请求三选一： - Header token: ...（推荐） - Cookie - URL 参数 ?token=...

1.3 Token 续期

POST /api/user_security/tokenLogin
{ "token": "old_token" }
→ { code:1, data: { token: "new_token", expires_in: 2592000 } }

2. 通用响应

{
  "code": 1,        // 1=成功 0=业务失败 -1=未登录 -2=无权限
  "msg": "提示",
  "time": 1777156407,
  "data": { ... }
}

统一处理： - code=-1 → 跳登录页 - code=-2 → 提示无权限 - code=0 + data.retry_after → 限流，按秒退避

3. 设备注册

首次登录时建议同步注册设备（多设备管理 / 在线状态 / 安全审计）：

POST /api/user_security/login
{
  "account": "alice",
  "password": "...",
  "device_name": "Alice's iPhone",
  "device_model": "iPhone 15",
  "platform": "ios",          // ios/android/web/windows/mac/linux
  "app_name": "Xianyan",
  "device_id": "<uniqueId>",
  "ip_city": "北京"           // 通过 /api/ip/self 获取
}

4. 推送 / WebSocket

文件传输、聊天等场景需要双向通信：

wss://tools.wktyl.com/ws/file_transfer

详见 API_FILE_TRANSFER_CORE_DOC §WebSocket 信令

5. 错误重试建议

code 推荐处理
200 (HTTP) 正常
401 重新登录
429 按 retry_after 退避
5xx 指数退避（1s/2s/4s，最多 3 次）
网络错 离线缓存

6. 上线前自检清单

  • [ ] Token 持久化到 Keychain/Keystore
  • [ ] 网络层证书校验
  • [ ] HTTPS 强制（明文 HTTP 拒绝）
  • [ ] 启动时 GET /health 健康检查
  • [ ] Crash 监控接入
  • [ ] 设备注册随登录一次成功
  • [ ] 推送通道（极光/小米）配置正确

7. 常用接口速查

场景 接口
启动配置 GET /api/app/init
用户资料 GET /api/user_center/index
信息流 GET /api/feed/list?type=...
搜索 GET /api/searchall/search?q=...
今日运势 GET /api/fortune/today
今日一诗 GET https://today.xianyan.cc/api/today
翻译 POST https://fy.wyi.cc/translate
短链生成 POST https://wyi.cc/api/shortener/create

8. 关联文档