首页 / 项目文档

One Sentence - 一言API

基于Hono框架和EdgeOne Pages构建的现代化随机句子API服务。

🚀 特性

  • 随机获取: 每次请求返回不同的随机句子
  • 丰富内容: 包含93条精选励志句子和古典诗词
  • 易于集成: 简单的RESTful API，支持多种编程语言
  • 高性能: 基于EdgeOne Pages，全球CDN加速
  • 现代化UI: 简洁美观的前端界面，支持响应式设计
  • 完整CRUD: 支持获取、添加、删除句子的完整操作
  • 密码保护: 支持管理员密码认证进行敏感操作
  • 环境变量支持: 支持自定义默认作者名、管理员密码和跨域域名白名单
  • 批量操作: 提供PowerShell脚本支持批量添加句子
  • 自动文档: 自动生成HTML格式的API文档
  • 错误处理: 完善的错误处理和用户友好的错误页面

📡 API接口

1. 获取随机句子

GET /api/random

响应示例:

{
  "success": true,
  "data": {
    "text": "人生有几件绝对不能失去的东西：自制的力量，冷静的头脑，希望和信心。",
    "author": "佚名",
    "id": 1
  }
}

2. 获取指定ID的句子

GET /api/{id}

响应示例:

{
  "success": true,
  "data": {
    "text": "人生若只如初见，何事秋风悲画扇。",
    "author": "纳兰性德",
    "id": 90
  }
}

错误响应（ID不存在）:

{
  "success": false,
  "message": "句子不存在"
}

3. 获取所有句子列表

GET /api/list

响应示例:

{
  "success": true,
  "data": [
    {
      "text": "人生有几件绝对不能失去的东西：自制的力量，冷静的头脑，希望和信心。",
      "author": "佚名",
      "id": 1
    },
    {
      "text": "人生若只如初见，何事秋风悲画扇。",
      "author": "纳兰性德",
      "id": 90
    }
  ],
  "count": 93
}

4. 添加新句子（需要密码认证）

POST /api/add

请求体:

{
  "text": "新的句子内容",
  "author": "作者名（可选）",
  "password": "管理员密码"
}

成功响应:

{
  "success": true,
  "data": {
    "text": "新的句子内容",
    "author": "作者名",
    "id": 94
  },
  "message": "句子添加成功"
}

错误响应:

{
  "success": false,
  "message": "密码错误，无权限添加句子"
}

5. 删除句子（需要密码认证）

DELETE /api/{id}

请求体:

{
  "password": "管理员密码"
}

成功响应:

{
  "success": true,
  "message": "句子删除成功"
}

错误响应:

{
  "success": false,
  "message": "密码错误，无权限删除句子"
}

错误响应（句子不存在）:

{
  "success": false,
  "message": "句子不存在"
}

🛠️ 使用示例

JavaScript

// 获取随机句子
fetch('/api/random')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log(data.data.text);
      console.log(data.data.author);
    }
  });

// 获取指定句子
fetch('/api/90')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log(data.data.text);
      console.log(data.data.author);
    } else {
      console.error('句子不存在:', data.message);
    }
  });

// 添加新句子
fetch('/api/add', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: '新的励志句子',
    author: '作者名',
    password: 'your_admin_password'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log('添加成功:', data.data);
  } else {
    console.error('添加失败:', data.message);
  }
});

// 删除句子
fetch('/api/123', {
  method: 'DELETE',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    password: 'your_admin_password'
  })
})
.then(response => response.json())
.then(data => {
  if (data.success) {
    console.log('删除成功:', data.message);
  } else {
    console.error('删除失败:', data.message);
  }
});

Python

import requests

# 获取随机句子
response = requests.get('/api/random')
data = response.json()

if data['success']:
    print(data['data']['text'])
    print(data['data']['author'])

# 获取指定句子
response = requests.get('/api/90')
data = response.json()

if data['success']:
    print(data['data']['text'])
    print(data['data']['author'])
else:
    print('句子不存在:', data['message'])

# 添加新句子
response = requests.post('/api/add', json={
    'text': '新的励志句子',
    'author': '作者名',
    'password': 'your_admin_password'
})
data = response.json()

if data['success']:
    print('添加成功:', data['data'])
else:
    print('添加失败:', data['message'])

# 删除句子
response = requests.delete('/api/123', json={
    'password': 'your_admin_password'
})
data = response.json()

if data['success']:
    print('删除成功:', data['message'])
else:
    print('删除失败:', data['message'])

cURL

# 获取随机句子
curl -X GET https://your-domain.com/api/random

# 获取指定句子
curl -X GET https://your-domain.com/api/90

# 获取所有句子列表
curl -X GET https://your-domain.com/api/list

# 添加新句子（需要密码）
curl -X POST https://your-domain.com/api/add \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"新的句子\", \"author\": \"作者\", \"password\": \"your_admin_password\"}"

# 删除句子（需要密码）
curl -X DELETE https://your-domain.com/api/123 \
  -H "Content-Type: application/json" \
  -d "{\"password\": \"your_admin_password\"}"

🔧 环境变量

  • DEFAULT_AUTHOR: 当句子没有作者信息时使用的默认作者名（默认为"佚名"）
  • ADMIN_PASSWORD: 管理员密码，用于添加新句子的认证

📦 部署

使用EdgeOne Pages部署

  1. 安装EdgeOne CLI:
npm install -g edgeone
  1. 设置环境变量（可选）:
# 在EdgeOne Pages控制台设置
DEFAULT_AUTHOR=佚名
ADMIN_PASSWORD=your_secure_password
  1. 部署项目:
npm run deploy

本地开发

  1. 安装依赖:
npm install
  1. 生成文档:
npm run sync-docs
  1. 启动开发服务器:
npm run dev

批量添加句子

项目提供了PowerShell脚本来批量添加句子：

  1. 准备句子数据文件 scripts/sentences.txt，每行一个句子
  2. 修改 scripts/add-sentences.ps1 脚本中的配置：
    • $url: API地址
    • $password: 管理员密码
    • $dataFile: 数据文件路径（默认为"sentences.txt"）
  3. 运行脚本：
.\scripts\add-sentences.ps1

脚本会自动：

  • 读取句子文件
  • 逐条发送API请求
  • 显示进度和结果
  • 统计成功/失败数量

🏗️ 项目结构

├── functions/
│   ├── index.tsx              # 主入口文件，处理路由和错误页面
│   ├── [[default]].ts         # EdgeOne Functions默认路由
│   └── routers/              # 路由模块
│       ├── index.ts          # 统一路由导出
│       └── sentence.tsx      # 句子API路由（包含所有CRUD操作）
├── public/
│   ├── index.html            # 前端页面（现代化UI界面）
│   ├── docs.html             # 项目文档（自动生成）
│   ├── style.css             # 样式文件（响应式设计）
│   └── favicon.ico            # 网站图标
├── scripts/
│   ├── sync-docs.js          # 文档生成脚本（Markdown转HTML）
│   ├── add-sentences.ps1     # PowerShell批量添加脚本
│   └── sentences.txt         # 句子数据源文件（93条精选句子）
├── package.json              # 项目配置和依赖
├── tsconfig.json             # TypeScript配置
└── README.md                 # 项目说明文档

🎨 前端特性

  • 响应式设计: 适配各种设备尺寸
  • 现代化UI: 渐变背景、毛玻璃效果、卡片式设计
  • 交互体验: 平滑动画、悬停效果、加载动画
  • API演示: 内置API测试功能
  • 完整文档: 详细的API使用说明
  • 文档页面: 自动生成的README文档页面

📝 数据源

项目内置了93条精选句子，包含：

  • 现代励志句子: 89条（80字以内）
  • 古典诗词: 4条（带作者信息）

句子内容涵盖：

  • 人生哲理
  • 励志名言
  • 成功学
  • 古典诗词
  • 哲学思考

你可以通过POST接口添加更多句子，或者替换内置数据源。

🔒 安全特性

  • 密码认证: 添加句子需要管理员密码
  • 环境变量: 密码存储在环境变量中，不暴露在代码中
  • 跨域控制: 使用Hono CORS中间件，支持通过环境变量配置域名白名单
  • 输入验证: 检查句子内容不能为空
  • 错误处理: 完善的错误处理和状态码

⚙️ 环境变量配置

在EdgeOne Pages控制台中设置以下环境变量：

变量名 说明 示例 必需
ALLOWED_ORIGINS 跨域访问域名白名单（用逗号分隔） https://example.com,https://www.example.com 否
DEFAULT_AUTHOR 默认作者名 佚名 否
ADMIN_PASSWORD 管理员密码 your_secure_password 是

跨域配置示例

# 设置域名白名单
ALLOWED_ORIGINS=https://example.com,https://www.example.com,https://app.example.com

# 禁止所有跨域访问（设置为空字符串）
ALLOWED_ORIGINS=

# 不设置CORS头（不设置此环境变量）
# 不设置 ALLOWED_ORIGINS 环境变量

CORS处理逻辑

环境变量状态 行为 说明
未设置 不设置CORS头 使用浏览器默认同源策略
空字符串 禁止跨域访问 返回null，拒绝跨域请求
域名白名单 只允许白名单中的域名 自动检查Origin头并设置相应CORS头

技术实现:

  • 使用Hono框架内置的CORS中间件
  • 支持动态域名白名单配置
  • 自动处理OPTIONS预检请求
  • 域名用逗号分隔，自动去除空格

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目。

📄 许可证

MIT License

🔗 相关链接

📊 项目统计

  • 总句子数: 93条（89条现代励志句子 + 4条古典诗词）
  • API端点: 5个（随机获取、指定ID查询、列表查询、密码添加、密码删除）
  • 数据结构: KV格式（Record<string, { text: string; author: string }>）
  • 支持语言: JavaScript, Python, cURL等
  • 部署平台: EdgeOne Pages
  • 框架: Hono + TypeScript
  • 前端技术: 原生HTML/CSS/JS，响应式设计
  • 文档生成: 自动Markdown转HTML
  • 批量工具: PowerShell脚本支持
On this page