上傳 API

最後更新


本頁說明 POST /upload/*path 的請求格式、檔名產生規則與各種回應。

請求


  1. curl -X POST -F "filepath=@./photo.jpg" http://localhost:8080/upload/blog/2025

項目規則
*path目標資料夾,相對於 storage/image/upload/;不存在時自動建立;空值回 400
表單欄位filepath(multipart/form-data)
類型判斷依該 part 的 Content-Type 標頭,不檢查檔案內容
支援類型image/jpeg、image/jpg、image/png、image/webp、image/svg+xml、application/pdf
大小上限Go 端無限制;Nginx client_max_body_size 100M

檔名


上傳檔一律重新命名為 {16 位英數}_{毫秒時間戳}{副檔名},副檔名由 GetExtension 依 MIME 決定(image/jpeg、image/jpg 皆為 .jpg)。隨機字元由 math/rand 產生,程式啟動時以當下時間為 seed。

回應


成功回 201:
  1. {
  2. "success": 1,
  3. "filename": "ERftP1gTS7WCTeJ8_1744080848530.jpg",
  4. "type": "image/jpeg",
  5. "size": 2501808,
  6. "src": "http://localhost:8080/c/img/blog/2025/ERftP1gTS7WCTeJ8_1744080848530.jpg"
  7. }

src 的網域由 configs.GetDomain() 決定:GO_ENV=development 時為 http://localhost:{PORT},否則為 https://{DOMAIN}。
狀態碼內容情境
400please assign a path first*path 為空
400can not create folder: ...建立資料夾失敗
400can not get file form request缺少 filepath 欄位
400can not save file寫檔失敗
201filename/type/src 為空字串、size 為該檔大小的 JSON;檔案不會寫入不支援的類型
408timed out超過 30 秒

判斷上傳結果


只看 201 不代表檔案已寫入:不支援的類型同樣回 201,但 filename 為空。需同時檢查狀態碼與 filename:
  1. status=$(curl -s -o response.json -w "%{http_code}" \
  2. -X POST -F "filepath=@./photo.jpg" \
  3. http://localhost:8080/upload/blog/2025)
  4. if [ "$status" != "201" ] || [ -z "$(jq -r '.filename // empty' response.json)" ]; then
  5. echo "upload failed ($status): $(cat response.json)" >&2
  6. exit 1
  7. fi
  8. jq -r '.src' response.json

即使上傳被拒,storage/image/upload/ 下的目標資料夾也已建立:os.MkdirAll 在讀取表單欄位與檢查類型之前就執行。
EN