xianyan/docs/03_API与数据.md

📡 闲言APP — API与数据

更新: 2026-04-20 | 作用: API 接口文档 + 数据源 + 错误处理策略

---

一、T1后端云 API

基础域名：动态配置，getAccountApiUrl() 获取

• 默认：http://i.lixiaoyin.cc（线路1）
• 备用：http://i.iqg.cc（线路2）

认证：key=39be0d5ca4c91dee, httk=5c26b6aee071ac70d9f5b1872dedf1fb, token=MD5动态生成

核心 API 列表

端点	方法	说明
/user_reg.json	POST	注册
/user_info.json?type=info	POST	登录/获取信息
/user_info.json?type=changepass	POST	修改密码
/user_info.json?type=qd	POST	每日签到（+1天会员+1积分）
/user_info.json?type=edu_jf	POST	修改积分
/user_info.json?type=edu_money	POST	修改余额
/user_info.json?type=mtv	POST	余额换会员
/user_info.json?type=cj	POST	抽奖
/user_all.json?type=text&id=	GET	云文档获取
/user_all.json?type=get_goods_info	GET	商品信息
/pay.do?...	GET	支付（微信/支付宝/QQ）

---

二、自建服务器 API

域名：http://zt.lixiaoyin.cc

端点	说明
/app/xianyan/more/boot.txt	启动页广告
/app/xianyan/more/adwords.txt	启动文字
/app/xianyan/more/Update.txt	应用更新检测
/app/xianyan/more/guide.txt	使用帮助数据
/app/xianyan/tp/bway.json	API线路配置
/app/xianyan/tp/shop.json	商城/赞助商配置
/app/xianyan/tuisong/sup.html	会员公告

---

三、第三方 API

API	URL	说明	频率限制
一言	https://v1.hitokoto.cn/?encode=json	随机句子	≤1次/秒
天气	https://www.tianqiapi.com/api/?version=v1	天气信息	≤1次/10分钟

一言 API 返回格式

{
  "id": 1234,
  "hitokoto": "句子内容",
  "type": "a",
  "from": "出处",
  "from_who": "作者",
  "creator": "提交者"
}

---

四、爬虫类 API（原项目使用，Flutter 版需替换）

原 API	原方式	Flutter 替代方案	优先级
毒鸡汤	自建 HTML 正则	自建 RESTful API (Supabase Edge Functions)	P0
微甜情话	自建纯文本	自建 RESTful API	P0
名人名言	juzimi.com 爬虫	自建数据库 + API	P1
搜索	wncx.cn Jsoup 爬虫	自建全文搜索 (MeiliSearch)	P1
T1 后端云	自有后端	迁移到 Supabase	P0

---

五、错误处理策略

错误类型	处理方式
网络超时	自动重试1次 → 缓存降级 → 错误提示
服务器错误 (5xx)	缓存降级 → 错误提示 → 稍后重试按钮
客户端错误 (4xx)	显示具体错误信息
Token 过期	自动刷新 → 重试原请求
数据解析失败	记录日志 → 缓存降级
无网络连接	读取本地缓存 → 底部提示"离线模式"

---

六、本地数据存储（Flutter 版）

存储方式	用途	实现
KvStorage (SharedPreferences)	主题/语言/首次启动等	kv_storage.dart
SecureStorage	Token 等敏感数据	secure_storage.dart
AppDatabase (Drift/SQLite)	句子/收藏/历史/模板 4表	app_database.dart