壁紙管理 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，放入項目根目錄，即可作為接口文檔使用。