Hono Waitlist API

轻量级 Waitlist 收集 API，一键部署到 Cloudflare Workers

✨ Features

• 🚀 一键部署到 Cloudflare Workers
• 📧 邮箱格式验证
• 🔔 飞书卡片通知
• 🎉 里程碑通知（可配置）
• 💾 D1 数据库存储
• 🌐 CORS 支持
• 🔒 防重复提交
• ⚡ 零成本运行（Cloudflare 免费额度）

🚀 Quick Start

1. 部署到 Cloudflare Workers

点击上方 "Deploy to Cloudflare Workers" 按钮，或手动部署：

# 克隆仓库
git clone https://github.com/wangrunlin/hono-waitlist-api.git
cd hono-waitlist-api

# 安装依赖
npm install

# 创建 D1 数据库
wrangler d1 create hono-waitlist

# 复制返回的 database_id，更新 wrangler.toml 中的 database_id

# 初始化数据库表
wrangler d1 execute hono-waitlist --file=./schema.sql

# 部署到生产环境
npm run deploy:prod

2. 配置环境变量

在 Cloudflare Dashboard 中配置以下环境变量：

变量名	必填	说明	示例
FEISHU_WEBHOOK_URL	✅	飞书机器人 Webhook 地址	https://open.feishu.cn/open-apis/bot/v2/hook/...
MILESTONE_ENABLED	❌	是否启用里程碑通知	true / false
MILESTONES	❌	里程碑数字（逗号分隔）	100,500,1000

3. 绑定域名

在 Cloudflare Dashboard 中将 Worker 绑定到你的域名（如 waitlist.yourdomain.com）

📖 API Documentation

POST /

提交 Waitlist 请求

请求体:

{
  "email": "user@example.com",
  "product": "your-product-name",
  "source": "twitter",
  "message": "Looking forward to this!"
}

字段说明:

• email (必填): 用户邮箱
• product (必填): 产品标识（只允许字母、数字、连字符、下划线）
• source (可选): 来源渠道
• message (可选): 用户留言

成功响应 (200):

{
  "success": true
}

失败响应 (400/500):

{
  "success": false,
  "error": "错误信息"
}

GET /

健康检查

响应:

{
  "service": "Waitlist API",
  "version": "1.0.0",
  "status": "ok",
  "endpoints": {
    "waitlist": "POST /"
  }
}

🎨 使用示例

HTML/JavaScript

查看 examples/index.html 获取完整示例，或访问 在线 Demo。

<form id="waitlist-form">
  <input type="email" name="email" placeholder="your@email.com" required>
  <button type="submit">Join Waitlist</button>
</form>

<script>
const form = document.getElementById('waitlist-form')

form.addEventListener('submit', async (e) => {
  e.preventDefault()
  
  const response = await fetch('https://waitlist.yourdomain.com/', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: e.target.email.value,
      product: 'your-product-name',
      source: 'landing-page'
    })
  })
  
  const result = await response.json()
  if (result.success) {
    alert('Success! You\'ve been added to the waitlist.')
  }
})
</script>

cURL

curl -X POST https://waitlist.yourdomain.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "product": "your-product-name",
    "source": "twitter"
  }'

🎉 里程碑通知

当启用里程碑功能时，达到指定用户数会自动发送特殊通知到飞书：

🎉 里程碑达成！

产品: your-product-name
已达到: 100 位用户
时间: 2026-02-04 16:00:00

可以开始启动项目了！🚀

配置方式：

# wrangler.toml
[vars]
MILESTONE_ENABLED = "true"
MILESTONES = "100,500,1000"

每个里程碑只会通知一次。

🗄️ 数据库结构

waitlist 表

字段	类型	说明
id	INTEGER	主键
email	TEXT	用户邮箱
product	TEXT	产品标识
source	TEXT	来源渠道
message	TEXT	用户留言
created_at	DATETIME	创建时间

唯一约束: (email, product) - 防止重复提交

milestones 表

字段	类型	说明
id	INTEGER	主键
product	TEXT	产品标识
milestone	INTEGER	里程碑数字
reached_at	DATETIME	达成时间

唯一约束: (product, milestone) - 每个里程碑只记录一次

🛠️ 本地开发

# 安装依赖
npm install

# 本地开发（需要先创建 D1 数据库）
npm run dev

# 测试
curl -X POST http://localhost:8787/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","product":"test"}'

📁 项目结构

hono-waitlist-api/
├── src/
│   ├── index.ts              # Hono app 入口
│   ├── types.ts              # TypeScript 类型定义
│   ├── routes/
│   │   └── waitlist.ts       # Waitlist 路由
│   └── services/
│       ├── feishu.ts         # 飞书通知服务
│       └── validator.ts      # 邮箱验证服务
├── examples/
│   └── simple.html           # HTML 示例
├── schema.sql                # 数据库表结构
├── wrangler.toml             # Cloudflare Workers 配置
├── tsconfig.json             # TypeScript 配置
└── package.json

🔮 未来计划

• 多通知渠道（Slack、Discord、Webhook）
• 导出功能（CSV / JSON）
• 统计 API（查看各产品用户数）
• 邮件通知（Resend / SendGrid）
• 自定义字段支持

📄 License

MIT

🙏 Credits

Built with Hono and Cloudflare Workers

---

Made with ❤️ by Leo Wang