Universal API Container (万能接口容器)

一个基于 PWA (渐进式 Web 应用) 的高性能图片/内容容器，通过加载外部 JSON 配置文件，动态生成 UI 布局、发起 API 请求并解析数据。

技术栈

• 后端/BFF： Supabase Edge Functions (Deno Runtime)
• 前端渲染： HTML5 + Tailwind CSS + Swiper.js + 原生 JavaScript
• 数据解析： 内置 JSONPath 解析器
• 部署：
  • 前端：Vercel
  • 后端：Supabase Edge Functions

项目结构

api2UI/
  ├── frontend/            # 前端代码
  │   ├── index.html       # 主页面
  │   ├── manifest.json    # PWA 配置
  │   └── sw.js            # Service Worker
  ├── backend/             # 后端代码
  │   ├── index.ts         # Supabase Edge Function
  │   └── api.json         # API 配置文件
  ├── vercel.json          # Vercel 部署配置
  ├── package.json         # 项目配置
  └── README.md            # 项目说明

功能特性

• 动态 URL 构建： 支持在 URL 模板中使用占位符，例如 https://api.com?idx={idx}
• 指令化参数： 运行时支持指令解析，如 {@eval:random(0,100)} 或 {@eval:date('yyyyMMdd')}
• 解析映射： 配置文件需包含 jsonpath 映射规则，将第三方 API 返回值转换为标准模型
• 全屏滚动： 实现垂直方向的 Snap Scroll（吸附式滚动），确保每张图占据完整视口
• 左右滑动： 支持左右滑动切换图片
• 预加载策略： 支持图片懒加载
• PWA 支持： 支持“添加到主屏幕”，移除浏览器地址栏
• 离线能力： 缓存已加载的图片/内容和 UI 资源
• 多端兼容： 支持 PC 和移动端

快速部署

前端部署（Vercel）

点击下方按钮，一键将前端部署到 Vercel：

部署说明：

• 点击按钮后会自动克隆仓库并预填配置
• Root Directory 已预设为 frontend
• 静态站点无需构建命令

后端部署（Supabase）

Supabase Edge Functions 需要先创建项目，再通过 CLI 部署：

1. 前往 Supabase 创建新项目
2. 安装 Supabase CLI：

   npm install -g supabase

3. 登录并部署：

   supabase login
   supabase functions deploy universal-api-container --project-ref your-project-ref

4. 确保 verify_jwt 设置为 false，允许免认证访问

访问方式

前端页面

部署到 Vercel 后，通过 Vercel 提供的 URL 访问前端页面，例如：

https://your-vercel-app.vercel.app

API 接口

API 接口已部署到 Supabase Edge Functions，访问地址为：

https://your-project-id.functions.supabase.co/universal-api-container

使用示例

默认配置

访问前端页面，默认会从 api.json 中随机选择一个配置，加载对应的 API 内容。

自定义配置

通过 URL 参数 config 传递自定义配置，例如：

https://your-vercel-app.vercel.app?config={"source_name":"Custom API","request":{"url":"https://api.example.com/data","params":{"page":"1","limit":"10"}},"extract":{"list":"$.items","image_url":"$.image","title":"$.title","prefix":"https://api.example.com"}}

随机参数

通过 URL 参数 idx 传递随机参数，或使用 {@eval:random(0, 100)} 指令：

https://your-vercel-app.vercel.app?idx=42

核心数据结构

配置文件结构

{
  "source_name": "Bing_Wallpaper",
  "request": {
    "type": "json",
    "url": "https://cn.bing.com/HPImageArchive.aspx",
    "params": {
      "format": "js",
      "idx": "{@eval:random(0, 7)}",
      "n": "3",
      "mkt": "zh-CN"
    }
  },
  "extract": {
    "list": "$.images",
    "image_url": "$.url",
    "title": "$.copyright",
    "prefix": "https://cn.bing.com"
  }
}

API 返回数据结构

{
  "source_name": "Bing_Wallpaper",
  "items": [
    {
      "title": "Japanese tree frog in a pink morning glory",
      "image_url": "https://cn.bing.com/th?id=OHR.JapaneseTreeFrog_ROW2089186965_1920x1080.jpg"
    }
  ]
}

本地测试

启动后端服务器

cd backend
deno run --allow-net --allow-read index.ts

启动前端 HTTP 服务器

cd frontend
python -m http.server 8080

访问本地页面

在浏览器中访问 http://localhost:8080

故障排查

API 返回数据为空

1. 检查 API URL 是否正确
2. 检查 API 配置中的 extract 规则是否正确
3. 查看 Supabase Edge Function 日志，了解具体错误信息

前端页面无法加载

1. 检查 Vercel 部署是否成功
2. 检查 API URL 是否正确指向 Supabase Edge Function
3. 检查浏览器控制台是否有错误信息

卡片无法左右滑动

1. 检查 Swiper.js 是否正确引入
2. 检查水平 Swiper 的配置是否正确
3. 检查 CSS 样式是否冲突

PWA 无法安装

1. 确保网站使用 HTTPS
2. 检查 manifest.json 文件是否正确配置
3. 检查 sw.js 文件是否正确注册

注意事项

• CORS 配置：确保 Supabase Edge Function 已添加 Access-Control-Allow-Origin: * 头
• API 访问限制：部分 API 可能有访问频率限制，使用时请注意
• PWA 特性：需要 HTTPS 环境才能使用 PWA 特性
• 性能优化：对于大量图片的场景，建议合理设置 n 参数，避免一次性加载过多图片

贡献

欢迎提交 Issue 和 Pull Request，帮助改进这个项目。

许可证

MIT