壁纸管理 API 文档

环境：Python 3.9+、Flask 2.x、PyMySQL 1.x
运行：python app.py
监听：http://0.0.0.0:5000

通用响应格式

{"code": 200,       // 业务码：200 成功，201 创建成功，400 参数错误，404 资源不存在，500 服务器错误"message": "success","data": {...},     // 具体数据"total": 10        // 部分列表接口返回
}

---

1. 健康检查

GET /health

测试服务是否存活。

响应示例

{"status":"ok","message":"API is running"}

---

2. 壁纸列表

GET /api/wallpapers

返回全部壁纸，按创建时间倒序。

响应示例

{"code": 200,"message": "success","data": [{"wallpaper_id": 1,"title": "星空","category_name": "宇宙","file_url": "https://example.com/full/1.jpg","preview_url": "https://example.com/preview/1.jpg","resolution": "3840x2160","file_size": 2048000,"uploader_name": "admin","status": "active","view_count": 1024,"download_count": 256,"like_count": 128,"create_time": "2025-07-25 14:30:00"}],"total": 1
}

---

3. 壁纸详情

GET /api/wallpapers/int:wallpaper_id

响应示例

{"code": 200,"message": "success","data": { ...单条壁纸对象... }
}

---

4. 新增壁纸

POST /api/wallpapers

Body(JSON)

字段	类型	必填	说明
title	string	√	壁纸标题
category_name	string	√	分类名称
file_url	string	√	原图地址
preview_url	string	√	预览图地址
resolution	string	√	分辨率，如 1920x1080
file_size	int	√	文件大小（字节）
uploader_name	string	×	上传者
status	string	×	状态，默认 pending

响应示例

{"code": 201,"message": "壁纸添加成功","data": { "wallpaper_id": 12 }
}

---

5. 修改壁纸

PUT /api/wallpapers/int:wallpaper_id

Body(JSON)
只需传要更新的字段，支持：title、category_name、file_url、preview_url、resolution、file_size、uploader_name、status。

响应示例

{ "code": 200, "message": "壁纸更新成功" }

---

6. 删除壁纸

DELETE /api/wallpapers/int:wallpaper_id

响应示例

{ "code": 200, "message": "壁纸删除成功" }

---

7. 分类列表

GET /api/categories

响应示例

{"code": 200,"message": "success","data": ["宇宙", "动漫", "风景"]
}

---

8. 根据分类获取壁纸

GET /api/wallpapers/category/<category_name>

响应示例
与「壁纸列表」格式相同，仅筛选对应分类。

---

9. 更新统计信息

PUT /api/wallpapers/int:wallpaper_id/stats

Body(JSON)

字段	类型	说明
view_count	int	本次浏览增量
download_count	int	本次下载增量
like_count	int	本次点赞增量

可单独或组合传递；值为增量而非绝对值。

响应示例

{ "code": 200, "message": "统计信息更新成功" }

---

状态码说明

HTTP	业务 code	场景说明
200	200	成功
201	201	创建成功
400	400	参数缺失或格式错误
404	404	指定壁纸不存在
500	500	服务器内部异常

---

常见错误示例

{ "code": 400, "message": "title 是必填字段" }{ "code": 404, "message": "壁纸不存在" }

---

数据库表结构（参考）

CREATE TABLE wallpapers (wallpaper_id INT AUTO_INCREMENT PRIMARY KEY,title VARCHAR(255) NOT NULL,category_name VARCHAR(64),file_url VARCHAR(512),preview_url VARCHAR(512),resolution VARCHAR(32),file_size BIGINT,uploader_name VARCHAR(64),status ENUM('pending','active','banned') DEFAULT 'pending',view_count INT DEFAULT 0,download_count INT DEFAULT 0,like_count INT DEFAULT 0,create_time DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

---

可直接将以上 Markdown 保存为 API.md，放入项目根目录，即可作为接口文档使用。