weather-api/README_zh-CN.md

EdgeOne Pages Hono 应用程序

这是一个基于 Hono 框架构建的现代 Web 应用程序，部署在 EdgeOne Pages 平台上。

在线演示：https://hono.edgeone.site

部署

🚀 项目特性

• 模块化路由设计 - 清晰的路由组织结构
• 服务端渲染 - 使用 JSX 和 HTML 模板进行页面渲染
• 文件上传 - 文件上传功能支持
• 图书管理 - 示例 CRUD 操作
• 错误处理 - 精美的 404 和 500 错误页面
• TypeScript 支持 - 完整的类型定义

📁 项目结构

functions/
├── index.tsx              # 主入口文件
├── [[default]].ts         # EdgeOne Functions 默认路由
├── env.ts                 # 环境类型定义
├── components/            # 组件目录
│   └── Layout.tsx         # 页面布局组件
└── routers/              # 路由模块
    ├── index.ts          # 统一路由导出
    ├── book.tsx          # 图书相关路由
    ├── ssr.tsx           # 服务端渲染路由
    └── upload.ts         # 文件上传路由

🛣️ 路由详情

静态路由

路径	方法	描述
/	GET	静态首页，从 public 目录提供 index.html

示例：

• https://hono.edgeone.app/ - 静态首页

SSR 路由 (/ssr)

路径	方法	描述
/ssr/:name	GET	动态 SSR 页面，显示个性化欢迎消息

示例：

• https://hono.edgeone.app/ssr/john - 显示 "Hello john!" 页面

图书管理路由 (/book)

路径	方法	描述
/book	GET	获取所有图书列表页面
/book/:id	GET	获取特定图书详情页面
/book	POST	创建新图书（API 端点）

示例：

• https://hono.edgeone.app/book - 图书列表
• https://hono.edgeone.app/book/1 - 第一本书的详情

创建图书 API 请求示例：

curl -X POST https://hono.edgeone.app/book \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新书标题",
    "author": "作者姓名"
  }'

支持的功能：

• CORS 跨域支持

文件上传路由 (/upload)

路径	方法	描述
/upload	POST	文件上传端点

示例：

curl -X POST https://hono.edgeone.app/upload \
  -F "file=@example.txt"

📖 详细 API 文档

基本信息

• Base URL: https://hono.edgeone.app
• Content-Type: application/json
• 编码: UTF-8

API 详情

1. 文件上传

端点: POST /upload

描述: 上传文件到服务器

请求格式: multipart/form-data

请求参数:

• file (必需): 要上传的文件

curl 请求示例:

# 上传文本文件
curl -X POST https://hono.edgeone.app/upload \
  -F "file=@/path/to/your/file.txt"

# 上传图片文件
curl -X POST https://hono.edgeone.app/upload \
  -F "file=@/path/to/image.jpg"

# 上传并自定义文件名
curl -X POST https://hono.edgeone.app/upload \
  -F "file=@document.pdf;filename=my-document.pdf"

响应示例:

{
  "success": true,
  "message": "文件上传成功",
  "fileName": "file.txt"
}

错误响应:

{
  "success": false,
  "message": "未提供文件"
}

2. 创建图书

端点: POST /book

描述: 创建新的图书记录

请求参数:

{
  "title": "图书标题",
  "author": "作者姓名"
}

参数说明:

• title (可选): 图书标题，默认为 "Untitled"
• author (可选): 作者姓名，默认为 "Unknown"

curl 请求示例:

# 创建包含完整信息的图书
curl -X POST https://hono.edgeone.app/book \
  -H "Content-Type: application/json" \
  -d '{
    "title": "红楼梦",
    "author": "曹雪芹"
  }'

# 只创建标题的图书
curl -X POST https://hono.edgeone.app/book \
  -H "Content-Type: application/json" \
  -d '{
    "title": "新书标题"
  }'

# 创建空图书（使用默认值）
curl -X POST https://hono.edgeone.app/book \
  -H "Content-Type: application/json" \
  -d '{}'

响应示例:

{
  "success": true,
  "message": "图书创建成功",
  "book": {
    "id": "abc123def",
    "title": "图书标题",
    "author": "作者姓名",
    "createdAt": "2023-12-01T10:00:00.000Z"
  }
}

3. 获取图书信息

curl 请求示例:

# 获取所有图书列表
curl -X GET https://hono.edgeone.app/book

# 获取特定图书详情
curl -X GET https://hono.edgeone.app/book/1

# 获取个人页面
curl -X GET https://hono.edgeone.app/john

错误码说明

错误码	HTTP 状态码	描述
VALIDATION_ERROR	400	请求参数验证失败
FILE_UPLOAD_ERROR	400	文件上传失败
NOT_FOUND	404	资源未找到
INTERNAL_ERROR	500	内部服务器错误

频率限制

• 目前所有 API 端点均无频率限制
• 建议客户端进行请求频率控制

CORS 支持

所有 API 端点均支持跨域访问，响应头包含：

• Access-Control-Allow-Origin: *
• Access-Control-Allow-Methods: POST, GET, OPTIONS
• Access-Control-Allow-Headers: Content-Type, Authorization

🔧 开发

本地开发

# 安装依赖
npm install

# 启动开发服务器
edgeone pages dev

🌐 环境变量

项目使用以下环境变量和全局对象：

• my_kv - KV 存储实例，用于数据持久化

🛡️ 安全特性

IP 限制（可选）

项目包含 IP 限制中间件配置（默认注释），可以限制访问来源：

app.use('*', ipRestriction(/* 配置 */));

📝 API 响应格式

成功响应

{
  "success": true,
  "message": "操作成功",
  "data": {}
}

错误响应

{
  "error": "ERROR_CODE",
  "message": "错误描述"
}

🎨 UI 设计

项目采用现代化 UI 设计：

• 响应式布局
• 系统字体栈
• 卡片式设计
• 统一色彩主题
• 优雅的错误页面

📦 依赖

• hono - Web 框架
• @edgeone/ef-types - EdgeOne Functions 类型定义
• edgeone - EdgeOne CLI 工具

🤝 贡献

欢迎提交 Issues 和 Pull Requests 来改进这个项目。

<EFBFBD><EFBFBD> 许可证

MIT License