省 API 调用方法

这是一个 Codex Skill，用来为付费、限额或响应较慢的外部 API 设计“按需、每日、共享缓存”。

它来自一个真实价格系统的实践：数据库里没有当天数据时，只让当天第一位真实用户触发一次供应商请求；成功结果写回数据库，之后所有用户共享。历史曲线第一次完整获取，以后只追加当天点。

核心原则

flowchart LR
    A[用户请求] --> B{数据库有当天缓存?}
    B -->|有| C[直接返回数据库]
    B -->|没有| D{获得原子租约?}
    D -->|没有| E[返回旧缓存和更新中状态]
    D -->|获得| F[调用一次外部 API]
    F --> G[保存当前值和当天历史点]
    G --> H[后续用户共享结果]

Loading

• 不后台遍历完整目录调用付费 API。
• 当天缓存存在时，外部调用为零。
• 并发冷启动使用数据库租约，避免重复扣费。
• 无数据、限流、服务错误和鉴权错误分别处理。
• 180 天历史只在首次需要时请求一次；稀疏历史也不重复下载。
• 次日只按需更新当前值并追加当天历史点。
• 纯手动、没有正式目录身份的数据永不调用供应商。
• 鉴权失败不能伪装成“没有数据”。

适用场景

• 股票、商品、卡牌或电商价格 API。
• 天气、汇率、物流等有调用额度的 API。
• AI 推理、图片识别或其他按次计费服务。
• Supabase/Postgres + Edge Functions，以及其他拥有共享数据库的后端。

安装

仓库发布后可使用 Codex 的技能安装器：

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo Marirofumi/api-cache-aside-skill \
  --path api-cache-aside

也可以把 api-cache-aside 目录复制到：

~/.codex/skills/api-cache-aside

重新启动 Codex 后即可使用。

使用示例

使用 $api-cache-aside，把这个付费价格接口改成数据库优先、每天最多调用一次的共享缓存。

使用 $api-cache-aside，检查当前 180 天历史接口为什么会被重复调用，并补齐并发和错误重试测试。

使用 $api-cache-aside，审查项目中是否仍有后台任务在遍历完整目录消耗 API 配额。

Skill 会要求的验收证据

• 同一缓存键当天首次访问最多一次外部调用。
• 并发请求只有一个获得租约。
• 首次历史请求一次，第二天只补当前点。
• 401/403、429、5xx 和无数据进入不同状态。
• 自动化测试与真实 API 测试分开报告。
• 日志、代码和提交中不包含 API Key。

详细工作流位于 api-cache-aside/SKILL.md，实现数据结构和测试矩阵位于 implementation-guide.md。